GROQ parser

The GROQ parser allows you to query and transform JSON data using GROQ (Graph-Relational Object Queries) syntax. GROQ was developed by Sanity.io as a query language designed to work directly on JSON documents.

Caution
The GROQ parser is currently in alpha. The underlying groq-js library is still under development, and some features may be limited.

Supported data formats

GROQ is available as a frontend parser for the following data formats:

Data format	Available
JSON	Yes
GraphQL	Yes
CSV	No
TSV	No
XML	No
HTML	No

You can also use GROQ as a standalone query type by selecting GROQ from the Type drop-down.

Basic syntax

GROQ queries start with * which represents all documents in the dataset. You can then filter and project the results.

Select all data

To return all data without transformation:

Filter by condition

Use square brackets to filter data:

*[age >= 20]

This returns only items where age is 20 or greater.

Project specific fields

Use curly braces to select specific fields:

*{name, email}

This returns only the name and email fields from each item.

Combine filter and projection

You can chain filtering and projection:

*[age >= 20]{name}

This filters items where age is 20 or greater, then returns only the name field.

Query examples

Filter by string value

*[status == "active"]

Filter by multiple conditions

*[age >= 18 && country == "US"]

Select nested fields

*{name, address{city, country}}

Order results

*[_type == "user"] | order(name asc)

Limit results

*[0...10]

Returns the first 10 items.

Use GROQ with JSON data

To use GROQ with JSON data:

Select JSON as the Type
Set the Parser to GROQ (under Frontend options)
Enter your GROQ query in the GROQ Query field

Alternatively, select GROQ directly as the Type for a simplified interface.

Known limitations

Array data: GROQ works best with array-type JSON documents. Object-type responses may require additional handling.
Alpha status: Some advanced GROQ features may not be available due to the alpha status of the groq-js library.
Frontend only: GROQ runs in the browser, not on the Grafana server. This means GROQ queries don’t support features that require backend processing, such as alerting or recorded queries.