Query schema

A query is the JSON body you send to the query endpoint. This page is the field-level reference. For the guided version, see Querying contracts; for the raw, canonical JSON Schema, see JSON schema.

Top level

Query

Dimension

Filter

Operators

Operator caveats

• in and not_in require a non-empty array. Passing an empty [] is rejected with 400. If you want "match nothing" semantics, don't send the filter at all (or rethink the call).
• is_null and is_not_null take value: null literally; the field must still be present in the filter object.
• Multiple filters are ANDed implicitly. There's no OR operator. If you need category = jaffle OR category = beverage, use { "operator": "in", "value": ["jaffle", "beverage"] }. If you need arbitrary OR over distinct shapes, split into two queries and union client-side.
• like uses SQL LIKE semantics: % matches any sequence, _ matches one character.

Filtering on measures (HAVING)

You can put a measure in field. Gaur compiles measure filters as HAVING clauses, applied after aggregation:

{
  "contract_name": "product_performance",
  "query": {
    "dimensions": [{ "name": "sku" }],
    "measures":   ["revenue_usd"],
    "filters": [
      { "field": "revenue_usd", "operator": "gt", "value": 1000 }
    ]
  }
}

This returns only SKUs whose total revenue_usd exceeds 1000 in the grouped result. No separate having field is needed: dimension filters go to WHERE, measure filters go to HAVING, automatically. Callers coming from Cube (which separates the two) just put both in filters.

Date and timestamp filters

Time-dimension filters accept ISO-8601 strings. For a date range, use inclusive start and exclusive end so adjacent ranges don't double-count boundary rows:

"filters": [
  { "field": "ordered_at", "operator": "gte", "value": "2026-04-01" },
  { "field": "ordered_at", "operator": "lt",  "value": "2026-05-01" }
]

Date-only strings ("2026-04-01") and full timestamps ("2026-04-01T07:30:00") both work. Jaffle timestamps are naive local-store time; the filter values are interpreted in the same scale.

Sort

Full example

{
  "contract_name": "product_performance",
  "query": {
    "dimensions": [
      { "name": "ordered_at", "time_grain": "month" },
      { "name": "category" }
    ],
    "measures": ["revenue_usd", "units_sold", "cogs_ratio"],
    "filters": [
      { "field": "category",    "operator": "in",  "value": ["jaffle", "beverage"] },
      { "field": "ordered_at",  "operator": "gte", "value": "2026-01-01" },
      { "field": "ordered_at",  "operator": "lt",  "value": "2026-05-01" },
      { "field": "revenue_usd", "operator": "gt",  "value": 1000 }
    ],
    "sorts": [{ "field": "revenue_usd", "direction": "desc" }],
    "limit": 50,
    "offset": 0
  },
  "context": { "store_id": "STR-008" }
}