Skip to main content

Query catalog

A named query is a parameterized telemetry analysis. The catalog has two halves:

  1. Built-in queries under the telemetry.* namespace, shipped with exd-client. They back the canned exd telemetry summary / srm / rules / … subcommands.
  2. User-defined queries declared as TOML files in the manifest repository (queries/<name>.toml). Deferred indefinitely — see the banner below.

The query catalog is the analogue of flags/ and segments/ in the manifest tree.

Built-in queries​

The telemetry.* namespace is reserved for built-in queries shipped with exd-client. The initial set:

NamePurposeParameters
telemetry.summaryEval counts and variant distribution per flag.flag (optional), since (required), compare_to (optional duration)
telemetry.srmSample-ratio mismatch check via chi-square test.flag (required), since (required), expected (optional map<string,float>)
telemetry.rulesRule-fire frequency for a flag.flag (required), since (required)
telemetry.userAll evaluations for a single unit_id_hash.id (required), since (optional)
telemetry.coverageFlags evaluated zero times in the window.since (required), namespace (optional)
telemetry.dead-flagsFlags only ever returning the default value.since (required), namespace (optional)
telemetry.version-skewEval counts grouped by manifest_version.flag (optional), since (required)
telemetry.contextsContext-attribute presence and value distribution.flag (required), since (required)
telemetry.simulateEvaluate a candidate manifest against historical context.manifest_path (required), since (required), flag (optional)

Each built-in query has a stable parameter list and a stable output schema. The capabilities manifest is the authoritative machine-readable record of these surfaces; exd telemetry capabilities --format json is the agent discovery point.

The CLI surface for each built-in lives at reference/cli/exd/telemetry/ (summary.md, srm.md, …). The CLI pages cover use cases; this page covers the catalog shape.

User-defined queries​

Deferred indefinitely. The user-defined query catalog at queries/<name>.toml is not landed in Phase 1. The shape below describes what the surface would look like if reintroduced; today, no queries/ directory is recognized by manifest/01-directory-layout.md or by the linter walk. The Q001–Q010 range stays reserved against future reintroduction.

When reintroduced, queries would be version-controlled, lint-validated, and reviewed alongside flags.

Repository layout​

manifest-repo/
  namespace.toml
  flags/
    checkout-redesign.toml
  segments/
    internal-employees.toml
  queries/
    experiment-health.toml
    rule-coverage.toml
    flag-summary.toml
    thresholds.toml

The queries/ directory is OPTIONAL. A flag namespace with no queries/ directory uses only built-in queries. A queries/thresholds.toml file, if present, configures detection thresholds applied to built-in and user-defined queries — see thresholds.

Query file schema​

# queries/experiment-health.toml
name = "experiment-health"
version = 1
description = "End-to-end health check for an experiment flag."

[parameters]
flag = { type = "string", required = true }
since = { type = "duration", required = true }
expected_split = { type = "map<string,float>", required = false }

[[checks]]
id = "exposure-volume"
query = "telemetry.summary"
inputs = { flag = "${flag}", since = "${since}" }

[[checks]]
id = "srm"
query = "telemetry.srm"
inputs = { flag = "${flag}", since = "${since}", expected = "${expected_split}" }
on_diagnostic = ["T001", "T002"]

[[checks]]
id = "rule-coverage"
query = "telemetry.rules"
inputs = { flag = "${flag}", since = "${since}" }
on_diagnostic = ["T005"]

[[checks]]
id = "manifest-skew"
query = "telemetry.version-skew"
inputs = { flag = "${flag}", since = "${since}" }
on_diagnostic = ["T004"]

Top-level fields​

FieldRequiredTypeDescription
nameyesquery_nameStable, repo-unique identifier. MUST equal the filename stem.
versionyesinteger ≥ 1Semantic version. Cited in provenance.
descriptionnostringFree-form.
parametersyestableSchema for the query's inputs. Empty table permitted.
checksyesarray of tablesOrdered list of built-in or user-defined queries to run. Non-empty.

[parameters.<name>] fields​

FieldRequiredTypeDescription
typeyesstringOne of string, int, float, bool, duration, timestamp, map<string,float>, map<string,string>, array<string>.
requirednoboolDefaults to false.
defaultnomatching typeDefault value applied when the parameter is absent. Mutually exclusive with required = true.
descriptionnostringFree-form.

duration values are parsed as Go-style durations: 5m, 1h30m, 7d. timestamp values are RFC 3339 strings.

[[checks]] fields​

FieldRequiredTypeDescription
idyesslugUnique within this query. Names the check in JSON output.
queryyesquery_nameThe built-in or user-defined query to invoke.
inputsyesinline tableMapping from the called query's parameter names to expressions. ${name} substitutes a parameter from this query. Literals are accepted.
on_diagnosticnoarray of T-codesDiagnostics this check is expected to surface. Used for documentation and capability metadata; does not gate execution.

A check MUST NOT reference a parameter that does not exist on this query. A check MUST NOT pass a parameter that does not exist on the called query.

Query lint diagnostics​

Deferred indefinitely with the user-defined query catalog. The range below is reserved against future use; no implementation tracks it today.

CodeSeverityTriggers when
Q001errorA [[checks]] block references a query name (built-in or user-defined) that does not resolve.
Q002errorA parameter type in [parameters.<name>] is not one of the recognized types.
Q003errorA [[checks]].inputs entry references a parameter ${name} that is not declared in this query's [parameters].
Q004errorAn on_diagnostic entry references a T-code not defined in diagnostics.
Q005errorThe name field does not equal the filename stem.
Q006errorTwo queries share a name.
Q007errorA [[checks]] block passes a parameter not declared on the called query, or omits a required parameter.
Q008errorThe name field does not match the query_name pattern.
Q009warningA query has zero [[checks]].
Q010warningA query parameter is declared but never referenced by any [[checks]] entry.

Composition rules​

Composition of [[checks]] would be exactly one level deep at schema version 1. A user-defined query MAY reference any built-in telemetry.* query and any other user-defined query, but the called query MUST NOT itself contain [[checks]] referring to further user-defined queries.

This restriction prevents accidental composition cycles and keeps query execution analyzable.

Versioning​

Each query carries an integer version. A change that adds a new [[checks]] block, alters thresholds, or modifies parameter shapes MUST bump version. The version is included in the provenance block so agent-produced findings can be quoted reproducibly.

Server-side validation​

The exd-server upload endpoint runs the same lint pipeline that operates locally, including Q-codes. A push containing an invalid query file is rejected with manifest_lint_failed (HTTP 422), preserving the manifest reference's "no second validation layer" invariant.

See also​