GROQ Playground (Vision)

Quickly test your GROQ queries using this studio plugin

Vision is a plugin that lets you quickly test your GROQ queries right from the Studio. It shows up as a tool in the navigation bar when installed, and is part of the default Studio setup when running in development mode.

Use the Vision plugin to test your GROQ queries

To install it, go to the root directory of your Sanity project in your terminal and run sanity install @sanity/vision. If you have the development server running while doing this, you will need to restart it in order to see Vision in your Studio.

Configuring your Vision plugin environment

If you want the Vision plugin to be available in all environments, include it in the plugins array in sanity.json. If it should only be available in certain environments (e.g., in the staging environment but not in the production environment), include it in the env.<environment>.plugins array in sanity.json.

The following two examples do not represent your entire sanity.json file. Rather, they are example snippets from a larger context.

To make Vision available in all environments:

{
  "plugins": [
    "@sanity/base",
    "@sanity/desk-tool",
    "@sanity/components",
    "@sanity/dashboard",
    "@sanity/default-layout",
    "@sanity/default-login",
    "@sanity/vision"
  ]
}

Alternatively, to make Vision available only in the staging environment:

{
  "plugins": [
    "@sanity/base",
    "@sanity/desk-tool",
    "@sanity/components",
    "@sanity/dashboard",
    "@sanity/default-layout",
    "@sanity/default-login"
  ],
  "env": {
    "staging": {
      "plugins": [
        "@sanity/vision"
      ]
    }
  }
}

If Vision is installed but isn't appearing in your studio, it might be configured for a different environment than the one you're in (e.g., you might be viewing your deployed studio but Vision is only configured for development).

Setting a default API version

Beginning in v2.27.0, you can set a default API version for the Vision plugin. Upon upgrading to or installing studio v2.27.0 or later, there should be a config file at config/@sanity/vision.json (if it's not there, you can create it). The file accepts one key—defaultApiVersion. Permissible values are v1, vX, v2021-03-25, or v2021-10-21.

// config/@sanity/vision.json

{
  "defaultApiVersion": "v2021-10-21"
}

The value set here will be the default for anyone using the Vision plugin who has not explicitly set an API version.

Using the Vision plugin

Getting familiar with Vision

The Vision plugin allows you to quickly test a GROQ query against any of the datasets in your Content Lake. At the top of the page, you'll find dropdowns to select your dataset and API version.

Each time you run a query (we'll see how in a moment), you'll see a third field at the top containing a URL for your query. This URL contains the API call to the Content Lake that's querying for your data.

If your dataset is public, that URL can be run in a browser, cURL, or an app like Postman or Insomnia, and it will return the same JSON as you see in Vision. If your dataset is private, the request must be authenticated in order to return data. The decision on dataset visibility is up to you, but it can always be changed later.

On the left side of the Vision plugin are two panes: query and params. In the query pane, you can enter any valid GROQ query.

Gotcha

You can only use Vision to test queries. You cannot use it for mutations.

Protip

Query parameters in Vision works the same way as with the Sanity client libraries. Given an object {minSeats: 2} in the Params field, you may use the keys in the object as parameters in the query: *[_type == "bike" && seats >= $minSeats] {name, seats}. Note that every param key is prefixed with $.

To learn more about how to write queries for Vision, read How Queries Work - GROQ.

Protip

The Vision plugin is an example of a Studio tool. Want to write your own tool? You can bootstrap one by running sanity init plugin and select it from the list.

Was this article helpful?