Get help on Discord

Understanding version dropdown in Sanity Studio's Vision tab

3 replies
Last updated: Oct 5, 2021
I’m curious what the version dropdown in sanity studio “vision” tab shows. I can’t see how it relates to any of the API versions i think(?) we are using (2021-06-07)
AI Update

The version dropdown in the Vision plugin controls which API version your GROQ queries are executed against. According to the Vision plugin documentation, it "allows you to query against different datasets within your project and select different API versions."

So yes, it's directly related to the API version like 2021-06-07 that you're using! The dropdown lets you select from versions like:

  • v1 or vX (the original API version)
  • v2021-03-25
  • v2021-10-21
  • v2021-06-07 (what you're using)
  • And other date-based versions

Why this matters: Different API versions can have different GROQ query behaviors and features. For example, the v2021-03-25 release introduced full GROQ specification compliance, fixed the parent operator (^), and changed how three-valued logic works. The most recent v2025-02-19 changed the default perspective from raw to published.

Best practice: You should match the version selected in Vision with what your application code uses (in your Sanity client configuration's apiVersion parameter). This ensures that queries behave the same way when you test them in Vision as they will in your production app. If you're using 2021-06-07 in your code, select that same version in the Vision dropdown to get consistent results.

The dropdown is essentially letting you test your queries against the specific query engine version that will parse and execute them, which is why it's important to keep them aligned between Vision and your application.

Sorry for the confusion, User. Until earlier this year, GROQ operated on 
v1
. That version still exists and can be used both in Vision and in your code.
When it came time to implement versioning, we went with a
date scheme rather than incremental version numbers. The first big release was 
2021-03-25
, which is why it’s included in the dropdown.
As changes are made and released, they have that day’s date as their version. This allows me to use today’s date (
2021-10-05
) as a version and know that it will continue to work going forward. If Sanity decides tomorrow to make a breaking change like switching GROQ comments from 
//
to 
#
, I’m fine because I’m using API 
v2021-10-05
. Anyone using 
v2021-10-06
or later would be using 
#
for comments. This hopefully also clarifies why we discourage the use of a dynamic date to set the API version. Any particular version can be used in Vision by selecting 
Other
in the dropdown and entering the version. (Note: Non-breaking changes may be retroactively added to a version, which is why 
sanity::dataset()
works in 
v2021-03-25
even though it wasn’t present back in March.)
Finally, there’s 
vX
. This is an experimental version that is not stable and is not recommended for production. This lets you use functions and features that aren’t part of any release and may (or may not) be released later.
tl;dr - If you’re using 
v2021-06-07
on your front end, then in Vision you’ll want to use either 
v2021-03-25
or 
Other
-> 
v2021-06-07
.
Ok, i see, thanks 🙂

Sanity – Build the way you think, not the way your CMS thinks

Sanity is the developer-first content operating system that gives you complete control. Schema-as-code, GROQ queries, and real-time APIs mean no more workarounds or waiting for deployments. Free to start, scale as you grow.

Get started for freeExplore the demo

Was this answer helpful?