Discussion on using GROQ vs GraphQL for Sanity.io, with GROQ being recommended for its capabilities.

18 replies

Last updated: Apr 12, 2021

Hey all, happy Friday 😄 Just looking into Sanity and wondering: would you consider GraphQL to have first-class support? Or will the experience generally be smoother using GROQ? It's not a dealbreak either way.

AI Update

Happy Friday! 😄

GraphQL definitely has solid support in Sanity, but GROQ is the first-class, native query language and will generally give you a smoother experience. Here's the breakdown:

Why GROQ is "first-class"

Native integration: GROQ was built specifically for Sanity and works seamlessly with all features
More flexible: GROQ handles complex content structures like Portable Text better than GraphQL
Real-time features: The Vision plugin gives you an integrated playground right in your Studio
Type generation: Full TypeScript support via Sanity TypeGen
Perspectives support: Full support for drafts, published content, and content releases

GraphQL limitations to know about

While Sanity does support GraphQL, there are some constraints:

Schema strictness: Your Sanity schema needs to be more rigid for GraphQL. Anonymous object types have to be "lifted" to the top-level scope with explicit names.
No subscriptions: The GraphQL API doesn't support subscriptions
Manual deployment: You need to run sanity graphql deploy via CLI whenever your schema changes—it doesn't auto-update
Perspectives: While GraphQL supports the published, raw, drafts, and release perspectives via query parameters, it's not as seamlessly integrated as with GROQ
No mutations: GraphQL is read-only; you'll still use Sanity's Mutation API for writes

When GraphQL makes sense

You're already invested in the GraphQL ecosystem
You need strict typing at the API level
Your team is more comfortable with GraphQL than learning GROQ
You're using tools that specifically require GraphQL

The verdict

GROQ is definitely the recommended path—Sanity's docs even suggest giving GROQ a try before reaching for GraphQL. That said, GraphQL support is production-ready and maintained, so it's not a dealbreaker if you prefer it. You'll just have a bit more friction with schema management and miss out on some of the more flexible querying patterns.

Since it's not a dealbreaker for you either way, I'd recommend starting with GROQ—it's more powerful for Sanity's use cases and has better DX integration. You can always add GraphQL later if you need it for specific integrations!

GROQ is more capable than GraphQL in any setting, so I would definitely recommend using that over gql.

In that it's more sanity-aware? I haven't played with it yet

Install the vision plugin in the studio and you can try it out (I only wish there was autocompletion). You can use some pretty good filtering with GROQ.
You can have a play around on this site as well:
https://groq.dev/

And there’s some pretty good docs here: https://www.sanity.io/docs/groq

Okay this is really helpful. Looking at the "Complex" variant at groq.dev, I can see what you're saying about its power. Just need to weigh whether that justifies eschewing all the tooling that comes with GraphQL (Typescript, React, etc)

It’s definitely more capable for Sanity than GraphQL. But even in general I find that it has the edge on some things, it’s more the tooling around it that gql takes. You can perform more operations on your queries with GROQ than gql. Unlike gql GROQ has a spread operator to grab all the fields (though it doesn’t resolve references).

Yeah for sure, gql has a lot more tooling support. Especially in the sense that it builds an API schema which offers up nice documentation, autocompletion and type generation.

Lots of good food for thought, thanks!

Using GraphQL with Sanity still works fine. The Gatsby plugin uses GraphQL.

No worries!

I only wish there was autocompletion.

Ctrl-<space>

should work in Vision, albeit it doesn’t appear to be context-aware.

I've tried that out of habit a few times and it doesn't seem to do anything for me 🤷‍♂️

Any chance you’re overriding that keybinding with TextExpander or something similar?

I don't even know what that is 😅 but it works in GraphiQL so I don't think so.

I'll give it another go next week when I work in the studio again

Eliot: I personally love GROQ. It just works—and works really well with Sanity. You don’t need to define a schema and can just query any JSON data with it. You can play around with the GROQ Arcade at https://groq.dev/ . Espen gave a recorded talk a few years ago that helps distinguish GROQ a bit. About 4 minutes in he points out exactly what Max said about autocompletion. There are also a few notes about why Sanity uses GROQ here .
As GROQ is a Sanity creation, the docs tend to be written using GROQ queries (outside of the docs that are specific to the
GraphQL API ).
There are plenty of people in this community using both GROQ and GraphQL so I think you’ll get great support either way.

Great info thanks! To me, defining a schema is an advantage from a code stability perspective. But I come from a non-JS background 😉

Understandable, and GROQ won’t mind at all (and as you may have already seen in your research, when using Sanity a schema will be a requirement).

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 free Explore the demo