Skip to content
Sanity
Get started
  • Sanity Studio - Flexible editing environment
  • Content Lake - Real-time database
  • Developer experience - Tooling you love
  • Structured content - The philosophy behind Sanity
  • Review changes - View edits & rollback instantly
  • Image pipeline - On-demand transformations
  • E-commerce - Better shopping experiences
  • Marketing sites - Control your story
  • Products & services - Innovate and automate
  • Mobile apps - Content backend for every OS
  • Aether - Unique digital shopping experience
  • Morning Brew - Omnichannel media distribution
  • InVision - Delivering exceptional customer experiences
  • DataStax - Personalization for global audience
  • React
  • Gatsby
  • Next
  • Nuxt
  • Eleventy
  • Netlify
  • Vercel
  • Algolia
  • Documentation
  • Reference
  • Guides
  • Resource library
  • Headless CMS
  • Tools & plugins
  • Project showcase
  • Schemas & snippets
  • Agency partners
  • Technology partners
  • Get support
  • Share your work
  • 5 Disadvantages Of Wordpress That Are Holding You Back
EnterprisePricing
Contact salesLog inGet started
Published February 26th 2020

Introducing our new GraphQL API

With GraphQL out of beta, Sanity.io has one of the richest API offerings in content management.

Even Eidsten Westvang

Even is a Sanity.io co-founder and product person

You know us, we’re careful about our APIs – our GraphQL APIs have seen production use for over a year, but it's not till now we're declaring them officially out of beta. You can try it out by updating to the newest version of the Sanity CLI and learn more about usage and migration paths in the documentation. With the update you will also get more features, including improved filters and sorting, as well as the ability to deploy tagged versions of your GraphQL endpoints.

GraphQL is available for all plans, and you can upgrade by running the following in your command line:

npm i -g @sanity/cli && sanity upgrade

Of course there are also new features!

Sorting, and filtering, for most things!

The beta version had limited field options when it came to filters, and sorting. So we made sure to improve those. If you want to get to a post by its slug or sort a product by its price, that’s totally doable. You can also filter and sort by nested values and with different boolean operators. As you would expect to be able to.

Input

{
  allBook(
    where: {
      author: { name: { matches: "Gibson" } }
      publishYear: { gt: "2013" }
    }
    sort: { publishYear: ASC }
  ) {
    title
    publishYear
    author {
      name
    }
  }
}

Output

{
  "allBook": [
    {
      "title": "The Peripheral",
      "year": 2014,
      "author": {
        "name": "William Gibson"
      }
    },
    {
      "title": "Agency",
      "year": 2019,
      "author": {
        "name": "William Gibson"
      }
    }
  ]
}

What! _ ?!

If you inspect the schema for the new version, you’ll notice an underscore of the type DocumentFilter. We studied most of the other automatically generated GraphQL APIs out there and saw a lot of different approaches. Our concern is getting in the way between you and what you want to do. We used the underscore because it is an invalid field name for Sanity’s content backend, and will never come in conflict with any of your content type names. We did look for prior art but soon realized that most vendors of automatically generated GraphQL APIs do this somewhat differently, and they will not always guarantee you against collisions between field names and filters.

Behind the underscore, you can filter documents based on what references them. For example, “give me all documents that reference the product with this ID”. You can also filter out all drafts if you happen to make an authenticated request with access to those.

Input

{
  allBook(where:{
    _: { references: "0e8c6c52-7ebb-4a9c-8212-d8ff052bd162" } }
    limit: 1
  ) {
    title
    author {
      _id
      name
    }
  }
}

Output

{
  "allBook": [
    {
      "title": "Agency",
      "year": 2014,
      "author": {
        "_id": "0e8c6c52-7ebb-4a9c-8212-d8ff052bd162",
        "name": "William Gibson"
      }
    }
  ]
}

Stay stable with tagged versions

The Sanity CLI will now warn you if you try to deploy breaking changes in your schemas. If you are not ready to adjust your queries in production, you can now deploy a new tagged version. This means you can run different endpoints with different subsets of your schemas at once. Or if you want to version your schemas, that’s a possibility too. We reasoned that the point with GraphQL is to have stable and predictable APIs, and not something that automatically changes whenever you’re experimenting with your content model or the like. We have also updated our source plugins for Gatsby and Gridsome to support tagged APIs.

GraphQL, powered by GROQ

Sanity’s primary query APIs is powered by GROQ. And people do sometimes ask us if we will support both GROQ and GraphQL going forward. The answer is an unequivical “yes”, we will support both because we don’t see these as opposed to each other. In fact, GROQ is what powers the GraphQL APIs (and it’s doing a great job of it as well). While GraphQL is more of a pattern for how to design an API, GROQ is an actual query language. You can in a way compare GraphQL to RESTful, and GROQ to SQL. We will continue developing both offers, and we look forward to learning what you will use them for.

Page content

  • Sorting, and filtering, for most things!
  • What! _ ?!
  • Stay stable with tagged versions
  • GraphQL, powered by GROQ

Platform

Structured ContentDeveloper experienceContent LakeSanity StudioSecurity & Compliance
  • Sanity vs Contentful
  • Sanity vs Strapi
  • Sanity vs Wordpress
  • Sanity vs Adobe Experience Manager
  • Sanity vs Hygraph
  • Sanity vs Sitecore
  • Sanity vs Storyblok
  • Sanity vs Contentstack
  • Sanity vs Prismic
  • Sanity vs Drupal
  • Sanity vs ButterCMS

Resources

Documentation
  • React Blog
  • Gatsby Blog
  • Next.js Landing Pages
  • Progressive Web Application
  • Single Page Application
  • Svelte & Typescript App
  • Vue & Tailwind Blog
  • Developer Portfolio Templates
  • Form validation with Yup
  • Live Preview with Next.js and Sanity.io
Resource library
  • Agency partners
  • Technology partners
  • Blog Template
  • Personal Website Template
  • Developer Portfolio Templates
  • All Templates
Case Studies
  • Headless CMS
  • What is an API CMS
  • Static Sites 101
  • Headless SEO
  • Localization
  • GraphQL vs REST
  • What is a DXP?
  • Typescript 101
  • Content as a Service
  • Ecommerce SEO
  • React CMS
  • Next.JS CMS
  • CMS for Shopify
  • Content platform
  • Multilingual CMS
  • Static Site CMS
  • Gatsby CMS
  • Node CMS
  • E-commerce CMS
  • Vue CMS
  • Angular CMS
  • GraphQL CMS
  • Newspaper CMS
  • Magazine CMS
  • CMS for apps
  • Remix CMS

Company

Contact SalesEnterpriseCareersTerms of ServiceAccessibility Statement

Stay connected

  • GitHub
  • Slack
  • Twitter
  • YouTube
  • Stack Overflow
  • Blog RSS
  • Newsletter
©Sanity 2023