GROQ Playground (Vision)

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.

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.

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).

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.

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.

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