Understanding SnQL: The Query Language Behind Sentry’s Snuba Data Platform

The article describes Snuba’s query language, SnQL, and how queries are sent as JSON to the /:dataset/snql endpoint.

MATCH

The data model is represented as an entity graph. The MATCH clause identifies the subgraph pattern to query. Three forms are supported:

Simple: MATCH (<entity> [SAMPLE n]) – queries a single entity such as events or transactions, optionally with a sample rate.

Example: MATCH (events) Subquery: MATCH { <query> } – the braces contain a full SQL‑like query whose SELECT/BY results are exposed to the outer query.

MATCH { 
    MATCH (transactions)
    SELECT avg(duration) AS avg_d BY transaction
}
SELECT max(avg_d)

Join:

MATCH (<alias>: <entity> [SAMPLE n]) -[<join>]-> (<alias>: <entity> [SAMPLE n])

– represents a multinode subgraph with directed relationships (1..n, n..1, 1..1). Each entity in a join must have a unique alias, and sampling can be applied to any entity in the join.

MATCH 
    (e: events)-[grouped]->(g: groupedmessage),
    (e: events)-[assigned]->(a: groupassignee)
SELECT count() AS tot BY e.project_id, g.id
WHERE a.user_id = "somebody"

SELECT .. BY

The SELECT clause specifies the output columns. When aggregations are present, everything after BY is treated as a grouping key. An empty SELECT with BY is invalid, and aggregating the whole result set requires a SELECT that contains only aggregation functions.

WHERE

The WHERE clause filters rows before aggregation. Conditions follow the form LHS OP RHS*, where OP can be =, !=, <, <=, >, >=, IN, NOT IN, LIKE, NOT LIKE, IS NULL, IS NOT NULL. Boolean operators AND, OR, and parentheses can combine multiple conditions.

HAVING

HAVING works like WHERE but is applied after the SELECT clause, allowing filters on aggregation results.

ORDER BY

Specifies the expression(s) used to sort the result set.

LIMIT BY / LIMIT / OFFSET

These clauses accept integer values and are passed to ClickHouse. If omitted, LIMIT defaults to 1000 and OFFSET to 0.

GRANULARITY

An integer that defines the time‑based bucket size for grouping results.

TOTALS

If set to true, the Snuba response includes a special "totals" key containing the summed values of all selected rows.

SAMPLE

If no sampling rate is provided in the MATCH clause, SAMPLE can be specified here. It accepts a float between 0 and 1 (percentage of rows) or an integer greater than 1 (exact number of rows to sample).