Data Queries

Cerb data queries

The text-based key:value query language used for worklists, metrics, charts, and other data.

Essentials

• A data query is a set of key:value pairs. No space after the colon. type:worklist.records is one pair; type: worklist.records is the key type with an empty value plus a stray bare term, which is not what you meant and usually will not error.
• Quote a value only when it contains a space. of:ticket, limit:25, and sort:-updated need no quotes; query:"status:open" does. Quotes are not what makes something a string, and unnecessary ones are just noise to read past.
• Group a key's children with ( ).
• Pairs are separated by whitespace, and a newline IS whitespace, so break a long query across lines wherever it reads best:

type:worklist.records
of:ticket
query:(
  status:open
  sort:-updated
  limit:10
)
format:dictionaries

• Every query MUST include a type:. The available types — e.g. worklist.records, worklist.subtotals, worklist.metrics, worklist.series, worklist.xy, metrics.timeseries, record.fields, record.filters, record.types, ui.icons — are documented under /cerb-docs/references/docs/data-queries/; data.query.types lists them all.
• A format: prepares the response for its consumer (e.g. dictionaries).
• For worklist queries, confirm the record type's valid search filters (their names, example values, and which are sortable) and its fields before writing query:/sort: — don't assume field names. The record.filters and record.fields query types exist precisely for this discovery; point people at them when useful.
• Reach for worklist.subtotals / metrics.timeseries / worklist.series for aggregation and reporting rather than hand-rolling; use worklist.records for a filtered list of record dictionaries.

Untrusted input goes in query_params:, never in the query text

Interpolating someone's words straight into query: is an injection: their text is parsed as query syntax, so a value can add filters, widen the result set, or reach records they should never see.

Pass it as a binding instead. data.query: takes a query_params: block, and the query references each entry as ${name}:

data.query:
  output: results
  inputs:
    query_params:
      term: {{search_text}}
    query@text:
      type:worklist.records
      of:ticket
      query:(subject:${term} status:open)

A substituted value is forced to a quoted string token, so whatever it contains -- colons, parentheses, another key:value -- lands as one literal value and cannot become syntax. record.search: and record.upsert: take the same thing under record_query_params:.

Ground truth — read the docs, don't guess

The cerb-docs filesystem is the full, authoritative Cerb documentation. When a query type, key, field, search filter, format, or icon is in question, look it up before you write it, and cite what you relied on. Invented field or filter names silently return nothing (or error), so confirm them.

• /cerb-docs/references/docs/data-queries/ — one page per type (e.g. worklist/records.md, worklist/subtotals.md, record/filters.md).

Related skills

• records — confirm a record type's alias for of:, and its real filter keys, against THIS install rather than the baseline docs.
• search-queries — the grammar for the query: you put inside a worklist data query.