Sanity API version update causing queries with category references to return empty results

10 replies
Last updated: Oct 28, 2021
Hello, we just updated the API version and some of our queries, like the following, are returning empty results. Is there a list of changes to the API somewhere? There is the general change log that I can try to dig through if not.
This is the query:

*[(_type== 'event' || _type== 'news' || _type== 'resource') &&categories[]._ref == '${category}'][0...12] { ... } 
AI Update

I can see exactly what's happening! The issue is related to the recent API version 2025-02-19 update, specifically the default perspective change from raw to published.

Your query categories[]._ref == '${category}' is likely returning empty results because the API now defaults to perspective=published instead of perspective=raw. This means you're only seeing published documents, not drafts.

The Breaking Change

According to the API version 2025-02-19 changelog, the most significant breaking change is:

The default perspective has switched from raw to published. This affects the /query endpoint and GraphQL queries.

With perspective=published, you only get published documents. With perspective=raw, you get drafts, published documents, AND the new versions.** documents (for Content Releases).

How to Fix It

You have two main options:

1. Explicitly set the perspective parameter in your query request:

// Add perspective=raw to your query parameters
const query = `*[(_type== 'event' || _type== 'news' || _type== 'resource') && categories[]._ref == $category][0...12] { ... }`
const params = { category: 'your-category-id' }
const result = await client.fetch(query, params, { perspective: 'raw' })

2. Use perspective=previewDrafts if you want drafts to take precedence over published versions (this is often what you want in preview contexts).

Additional Changes to Note

The 2025-02-19 version also:

  • Introduced versions.** prefixed documents for Content Releases
  • Fixed a GROQ bug where empty keys would expand incorrectly (this could potentially affect other queries)
  • Added new parameters and functions for Content Releases support

The full API versioning documentation explains how dated API versions work and how to opt into specific versions. If you haven't explicitly set an API version in your client configuration, you might have been automatically upgraded to the latest version.

Show original thread
10 replies
in this case ${category} is a document id that we have
We were able to verify that changing from
==
to
in
gets the expected results.
*[(_type== 'event' || _type== 'news' || _type== 'resource') &&
  "898fcc4d-1562-4aeb-923a-6fccf4682e78" in categories[]._ref][0...12] { ... }

Would be nice to see the docs where this syntax is specified.
I’m glad you got things working! 🙌
The exact syntax is the second example in the code block
here , but a clearer example specific to this use case is a good idea. I’ll add something on that page. Is there anywhere else you looked in the docs that didn’t offer a solution and you think it should?
I think the cheatsheet may have been the source of some confusion
Okay, thanks Adam. I’ll take a look there too.
These examples were the ones that lead us to that approach.
*[count((categories[]->slug.current)[@ in ["action", "thriller"]) > 0]

*[castMembers[].person._ref == 'person_sigourney-weaver'] // Any document having a castMember referencing sigourney as its person

These examples were the ones that lead us to that approach.
*[count((categories[]->slug.current)[@ in ["action", "thriller"]) > 0]

*[castMembers[].person._ref == 'person_sigourney-weaver'] // Any document having a castMember referencing sigourney as its person

Thank you, Wayne. I’ve corrected the sigourney-weaver example on the cheat sheet as the
==
example would only work on
v1
. It now uses
in
, which works on all GROQ versions.
There’s also a Gotcha added
here that attempts to clarify
==
vs.
in
when comparing a string against an array of strings.
Feel free to give any feedback. Or, if you see any other pages that might be worthy of this being mentioned, please let me know. Thanks again!

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.

Was this answer helpful?