Index
Edit

GROQ and GraphQL

Sanity's primary API for querying is GROQ. We also offer a GraphQL API that is currently in beta. Here we look at both of them and how they compare.

Check out the GraphQL API

GraphQL is a pattern for designing flexible APIs to structured, connected data. GraphQL is very popular, and there are loads of nice tooling and libraries for it appearing every week. Naturally we are often asked why we did not design Sanity with GraphQL as the core query language, but rather added it as a mapper.

Take this GROQ-query:

*[_type == "author" && name match "Edgar" && debutYear < 1900]{
  name,
  debutYear
}

(Fetch authors, whose name contain the string "Edgar" and debuted before 1900, return the name, year of debut, and number of books for each author. The results would perhaps include {"name": "Edgar Allan Poe", "debutYear": 1827})

Using our GraphQL mapper you would express it like his:

{
  authors(where: {
      debutedBefore_lt: "1900-01-01T00:00:00Z", 
      name_matches: "Edga*r"
  ) {
    name,
    debutYear,
  }
}

This is just one example. We see a lot of different uses of Sanity. Some people prefer GraphQL so they can tie the API to other services and enjoy the tooling of the GraphQL ecosystem.

Sometimes they run up against what you can reasonably express in the built-in GraphQL mapper and build their own APIs. Then it's really good to have GROQ with its free form queries that translate well to GraphQL.

Others simply prefer GROQ for it's expressive range and what you can accomplish without any configuration whatsoever.

Next: Introduction