Compare query languages for content vs. application data: when to use GROQ with Sanity vs GraphQL for complex APIs
Get practical Sanity guides with working examples, schema templates, and time-saving prompts. Everything you need to build faster with Sanity CMS.
No spam. Unsubscribe anytime.
I've built production applications with both GROQ and GraphQL, and the question I get asked most often is: "Which one should I use for my project?" The confusion is understandable - both are query languages, both handle data fetching, and both promise better developer experiences. However, they solve fundamentally different problems and excel in completely different scenarios.
After shipping multiple projects with each technology, I've learned that the choice isn't about which is "better" - it's about matching the right tool to your specific use case. This guide will walk you through the key differences, practical considerations, and real-world scenarios to help you make the right choice for your next project.
Before diving into comparisons, it's crucial to understand what each technology actually is and why it exists.
GROQ (Graph-Relational Object Queries) was created by Sanity specifically for querying their content lake. It's a domain-specific language designed to work with Sanity's document-based data model, providing powerful filtering, joining, and projection capabilities for hierarchical JSON data.
GraphQL (Graph Query Language) was created by Facebook as a general-purpose API layer that can sit on top of any backend. It's a specification for building APIs that allows clients to request exactly the data they need through a strongly-typed schema system.
The key insight is that GROQ is a query language for a specific database system, while GraphQL is an API design specification that can work with any data source.
| GROQ | GraphQL |
|---|---|
| GROQ = Graph-Relational Object Queries | GraphQL = Graph Query Language |
| Created by Sanity.io specifically for querying Sanity's content lake | Created by Facebook (now Meta) to query any backend that exposes a GraphQL API |
| Domain-specific: tightly integrated with Sanity's data model and optimized for content operations | General-purpose: can be used with any backend/service that implements the GraphQL specification |
| Designed for content management and headless CMS scenarios | Designed for unified API layers across multiple data sources and client types |
This fundamental difference impacts every other aspect of how these technologies work and when you should use them.
| GROQ | GraphQL |
|---|---|
| Document store query language: Treats data like a giant, queryable JSON document database | Strongly typed schema: Requires predefined types, queries, mutations, and resolvers |
| No predefined schema required - query what exists in the dataset directly | Requires formal schema definition that the API enforces at runtime |
| Emphasizes flexible filtering, joins, and projections on hierarchical content | Emphasizes predictable, typed data fetching with client-specified field selection |
| Query execution happens entirely on Sanity's optimized backend | Query execution requires custom resolvers that you implement to fetch data |
The architectural difference is profound. With GROQ, you're querying a pre-existing, optimized content database. With GraphQL, you're building an API layer that can aggregate data from multiple sources.
Understanding how each language expresses queries helps illustrate their different philosophies:
GROQ Example:
*[_type == "post" && publishedAt < now() && defined(slug.current)]{
title,
publishedAt,
"author": author->{
name,
image,
bio
},
"categories": categories[]->title,
"relatedPosts": *[_type == "post" && references(^.categories[]._ref)][0...3]{
title,
slug
}
} | order(publishedAt desc)[0..9]
GraphQL Example:
query GetRecentPosts($limit: Int = 10) {
posts(
where: {
publishedAt_lt: "2025-01-01",
slug_exists: true
},
orderBy: publishedAt_DESC,
first: $limit
) {
title
publishedAt
author {
name
image {
url
}
bio
}
categories {
title
}
relatedPosts(first: 3) {
title
slug {
current
}
}
}
}
GROQ reads more like a functional programming language with its pipeline operations and reference following (-> operator). GraphQL reads more like a declarative specification of exactly which fields you want from a predefined schema.
| GROQ | GraphQL |
|---|---|
| Runs entirely on Sanity's backend against their optimized content lake | Runs on any server implementing GraphQL spec with custom resolvers |
| No backend code required for basic queries - just query the content | Requires backend implementation: schema definition, resolvers, authentication |
| Optimized specifically for content operations like filtering, sorting, and joining documents | Performance depends on resolver implementation and underlying data sources |
| Built-in caching, CDN distribution, and query optimization | Caching and optimization strategies must be implemented separately |
This execution difference significantly impacts development complexity. GROQ queries work immediately against Sanity's infrastructure, while GraphQL requires you to build and maintain the server implementation.
| GROQ | GraphQL |
|---|---|
| Highly optimized for content queries with built-in indexing and caching | Performance varies based on resolver implementation and data source efficiency |
| Single request can handle complex joins and filtering server-side | N+1 problem potential without proper batching (dataloader pattern) |
| Built-in pagination and result limiting with efficient server-side processing | Pagination strategies must be implemented in resolvers |
| CDN-distributed queries with global edge caching | Caching strategy depends on your server implementation |
GROQ's performance is generally predictable because it's optimized for its specific use case. GraphQL performance varies widely based on implementation quality and the underlying data sources.
| GROQ | GraphQL |
|---|---|
| Steeper initial learning curve - unique syntax and concepts | Moderate learning curve - familiar REST-like concepts with typing |
| Powerful once mastered - can express complex queries concisely | Gradual complexity - start simple, add complexity as needed |
| Limited to Sanity ecosystem - skills don't transfer to other platforms | Broadly applicable - skills transfer across many backends and frameworks |
| Excellent tooling within Sanity Studio and Vision query explorer | Rich ecosystem - GraphiQL, Apollo DevTools, multiple client libraries |
The learning investment pays off differently for each technology. GROQ mastery makes you highly productive within the Sanity ecosystem, while GraphQL skills are broadly applicable across the industry.
| GROQ | GraphQL |
|---|---|
| Sanity-specific tooling: Vision query explorer, Studio integration, TypeGen | Rich ecosystem: Apollo, Relay, Prisma, Hasura, GraphiQL, and many more |
| Next.js integration optimized for static generation and caching | Framework agnostic - works with React, Vue, Angular, mobile apps |
| Limited client libraries - primarily Sanity's official clients | Multiple client options - Apollo Client, Relay, urql, simple fetch |
| Built-in real-time subscriptions through Sanity's listener API | Real-time capabilities available through subscriptions (implementation-dependent) |
GraphQL's ecosystem is significantly larger and more diverse, while GROQ's tooling is more focused but deeply integrated with the Sanity platform.
Understanding when to choose each technology becomes clearer when you examine specific scenarios:
Content-Heavy Websites:
// Perfect for blog posts with complex relationships
*[_type == "post"]{
title,
body,
"author": author->{name, image},
"category": categories[0]->{title, slug},
"relatedPosts": *[_type == "post" && categories[]._ref in ^.categories[]._ref][0...3]
}
Marketing Sites with Dynamic Content:
Static Site Generation:
getStaticProps and getStaticPathsMulti-Client Applications:
# Same API serves web, mobile, and internal tools
query GetUserDashboard($userId: ID!) {
user(id: $userId) {
profile {
name
avatar
}
orders(first: 5) {
id
total
status
}
recommendations {
id
title
price
}
}
}
Complex Data Aggregation:
Real-Time Collaborative Applications:
If you're currently using REST APIs with a headless CMS, migrating to GROQ with Sanity can significantly simplify your data fetching:
// Before: Multiple REST API calls
const post = await fetch(`/api/posts/${slug}`)
const author = await fetch(`/api/authors/${post.authorId}`)
const relatedPosts = await fetch(`/api/posts?category=${post.categoryId}&limit=3`)
// After: Single GROQ query
const post = await client.fetch(`
*[_type == "post" && slug.current == $slug][0]{
title,
body,
"author": author->{name, image},
"relatedPosts": *[_type == "post" && categories[]._ref in ^.categories[]._ref][0...3]
}
`, { slug })
GraphQL migrations typically involve building the GraphQL layer incrementally:
// Phase 1: Wrap existing REST endpoints
const resolvers = {
Query: {
post: (_, { slug }) => fetch(`/api/posts/${slug}`).then(r => r.json()),
posts: () => fetch('/api/posts').then(r => r.json())
}
}
// Phase 2: Optimize with direct database access
const resolvers = {
Query: {
post: (_, { slug }) => db.posts.findOne({ slug }),
posts: () => db.posts.find({}).limit(10)
}
}
Efficient GROQ:
// Good: Specific filtering and projection
*[_type == "post" && publishedAt > "2024-01-01"]{
title,
publishedAt,
"author": author->name
}[0...10]
// Avoid: Over-fetching without limits
*[_type == "post"]{
title,
body,
"author": author->,
"allRelated": *[_type == "post"]
}
GROQ automatically handles:
Efficient GraphQL:
// Good: Batched data loading
const resolvers = {
Post: {
author: (post) => authorLoader.load(post.authorId)
}
}
// Avoid: N+1 queries
const resolvers = {
Post: {
author: (post) => db.authors.findById(post.authorId) // Called for each post!
}
}
GraphQL requires manual optimization for:
Here's a practical decision framework:
// lib/sanity/queries.ts
export const POSTS_QUERY = defineQuery(`
*[_type == "post" && defined(slug.current)] | order(publishedAt desc) {
_id,
title,
slug,
publishedAt,
excerpt,
"author": author->{name, image},
"categories": categories[]->title
}
`)
// pages/blog/index.tsx
export async function getStaticProps() {
const posts = await sanityFetch({
query: POSTS_QUERY,
tags: ['post']
})
return {
props: { posts },
revalidate: 3600
}
}
// graphql/queries.ts
const GET_POSTS = gql`
query GetPosts($first: Int, $after: String) {
posts(first: $first, after: $after) {
edges {
node {
id
title
slug
publishedAt
excerpt
author {
name
avatar {
url
}
}
categories {
name
}
}
}
pageInfo {
hasNextPage
endCursor
}
}
}
`
// components/BlogList.tsx
const BlogList = () => {
const { data, loading, error, fetchMore } = useQuery(GET_POSTS, {
variables: { first: 10 }
})
if (loading) return <LoadingSpinner />
if (error) return <ErrorMessage error={error} />
return (
<div>
{data.posts.edges.map(({ node }) => (
<PostCard key={node.id} post={node} />
))}
{data.posts.pageInfo.hasNextPage && (
<LoadMoreButton onLoadMore={fetchMore} />
)}
</div>
)
}
The choice between GROQ and GraphQL isn't about picking the "better" technology - it's about matching the right tool to your specific needs and constraints. GROQ excels in content-driven scenarios where you want powerful querying without backend complexity, while GraphQL shines in complex applications requiring unified APIs across multiple data sources and client types.
My recommendation is to start with your primary use case. If you're building content-heavy applications and want to focus on frontend development, GROQ with Sanity provides an incredibly productive development experience. If you're building complex applications with multiple data sources and client types, GraphQL offers the flexibility and control you need.
Remember that these technologies aren't mutually exclusive. Many successful applications use both - GROQ for content operations and GraphQL for application features. The key is understanding each tool's strengths and applying them where they provide the most value.
The best choice is the one that aligns with your project requirements, team expertise, and long-term technical strategy. Both GROQ and GraphQL are excellent technologies that will serve you well when applied to their intended use cases.
Let me know in the comments which approach you're considering for your next project, and subscribe for more practical development guides comparing modern web technologies.
Thanks,
Matija