groq

What is groq?

The groq npm package is a JavaScript implementation of GROQ (Graph-Relational Object Queries), a query language designed for querying JSON documents. It is particularly useful for querying data in headless CMS systems like Sanity.io.

What are groq's main functionalities?

Basic Querying

This feature allows you to perform basic queries on JSON documents. The example code demonstrates how to query all documents of type 'post'.

const groq = require('groq');
const query = groq`*[_type == 'post']`;
console.log(query);

Filtering

This feature allows you to filter documents based on specific conditions. The example code demonstrates how to query documents of type 'post' with the title 'Hello World'.

const groq = require('groq');
const query = groq`*[_type == 'post' && title == 'Hello World']`;
console.log(query);

Projection

This feature allows you to project specific fields from the documents. The example code demonstrates how to query documents of type 'post' and project only the 'title' and 'author' fields.

const groq = require('groq');
const query = groq`*[_type == 'post']{title, author}`;
console.log(query);

Ordering

This feature allows you to order the results of your query. The example code demonstrates how to query documents of type 'post' and order them by the 'publishedAt' field in descending order.

const groq = require('groq');
const query = groq`*[_type == 'post'] | order(publishedAt desc)`;
console.log(query);

Other packages similar to groq

graphql

GraphQL is a query language for APIs and a runtime for executing those queries by using a type system you define for your data. Unlike GROQ, which is designed for querying JSON documents, GraphQL is more versatile and can be used to query various types of data sources.

jsonpath

JSONPath is a query language for JSON, similar to XPath for XML. It allows you to navigate and query JSON documents. While JSONPath is more focused on navigating JSON structures, GROQ provides more advanced querying capabilities like filtering, ordering, and projections.

lodash

Lodash is a JavaScript utility library that provides functions for common programming tasks, including querying and manipulating JSON objects. While Lodash is not a query language, it offers methods that can achieve similar results to GROQ queries through its utility functions.

README

GROQ tagged template literal

This module exports a single function that can be called with an ES2015 template string to signal that it represents a GROQ-query.

The result will be the exact same string as the input, - this is currently helpful for getting syntax highlighting in editors, but in the future it might also parse and validate queries, strip unncessary whitespace and similar.

Pairs well with vscode-sanity!

Installing

npm install --save groq

Usage

import groq from 'groq'

const query = groq`*[_type == 'products'][0...10]`

Automatic type inference

If you are using @sanity/codegen you can use defineQuery instead of groq to get type inference out of the box:

import {defineQuery} from 'groq'

const query = defineQuery(`*[_type == 'products'][0...10]`)

In the future we might merge defineQuery with groq, but this is currently not 100% supported by TypeScript.

What is Sanity? What is GROQ?

Sanity is a real-time content infrastructure with a scalable, hosted backend featuring a Graph Oriented Query Language (GROQ), asset pipelines and fast edge caches.

To get started with Sanity, please head over to our getting started guide

License

MIT-licensed. See LICENSE.