Skip to content
bucker

Saved queries

A saved query is a question you have asked once and want answered the same way every time: a query spec pinned as a version, with the typed variables it needs, a record of every run, and, if an organization owner chooses, a REST endpoint an outside system can call. People run them from the dashboard; agents run them as saved_query_run; a team can keep the approved version in bucker.yml.

What a version is

A version is immutable. Changing anything is a new version.

Field Meaning
spec A strict query spec v1. A saved query reads spans, logs, events or metrics; a dataset that needs analytics:read or cost:read is refused until those datasets exist.
variables [{ name, type, required: true, enum?, min?, max? }] with type string, number or string_list. Every variable is required; there is no default.
specDigest, compiledDigest SHA-256 of the canonical spec and of what it compiles to. Computed by Bucker from the spec; a caller cannot state one.
outputSchema The columns a row has, derived from the spec. A group column is customer text and is marked so.
tokenCeiling, freshnessSeconds What an agent calling the version is promised: at most this many tokens, data at most this old.
author, sponsor Who proposed it, and the person an agent acted for. Read from Bucker's record of the requester, never from the request.

A query has a state (draft, shared, disabled), a shared version (the one that runs by default), a published version (the one the external endpoint serves), a certified flag (reserved for WH-18) and an archive flag.

Variables are bound, never interpolated

A filter names a variable ({ "key": "service", "op": "eq", "var": "service" }); a run supplies its value, and the printer binds it as a parameter. An injection through a value is one bound parameter, shown in the run's compiled.params; the statement text never holds it. A value outside its declared enum, min or max is a 422 that names the variable. A variable that names the tenant (org, org_id, project, project_id, tenant, workspace, and spellings of them) is refused when the version is proposed, and a run that supplies a name the version does not declare is refused: the organization and the project always come from the call, never from a value.

Drafts, sharing and approval

You want Call What happens
Try a query out saved_query_propose with visibility: draft Stored at once (saved_query.draft). Private to you; runs charge your own scan budget; the operation's time-box ends after 14 days (the registry's default) and archives the query if it is still exactly as that draft left it; a later draft or an approved shared version supersedes that, and an unshared draft is in any case hidden on read after 30 days. Only on a query nobody has shared.
Share a query visibility: shared saved_query.create (first version) or .update (a new one). Always pending approval, whatever the organization's policy says. Nothing is live until a person approves the plan with its digests.
Re-pin an earlier version, enable, disable, withdraw the endpoint, archive saved_queries_update The act is derived from what would change: saved_query.update, .disable, .unpublish, .archive. Disabling a query something reads is SENSITIVE.
Undo a new shared version operation_revert Re-pins the previous shared version.

Applying is a compare-and-swap on the query's revision: an approval given to revision N is never spent on revision N+1, including after an edit through any other door. A draft cannot be stored on a query that is already shared: a change to a live query is a proposal for a new shared version.

Publishing, query tokens and deletion are a person's. saved_query.publish, query_token.create and saved_query.delete are human-only: no agent, no OAuth client and no delegated credential reaches them, and the governed engine refuses them too. Publishing and minting need org:admin.

Slugs and tool names

A slug is 2 to 60 lower-case letters, digits and hyphens. Its per-version tool name is sq_<slug> (hyphens become underscores), generated from the slug alone: the free-text name and description travel as scrubbed data and never become part of a name an agent calls. A slug is refused when its tool name would exceed 40 characters, contains a forbidden word as a whole segment (delete, publish, launch, ship, erase, purge, widen) or as a fragment (approve, merge, deploy, buy, purchase, lift), or starts with view- (the prefix a converted Explore view carries). The sq_<slug> aliases themselves are not served yet.

Explore views

A saved view of surface explore is shown as a saved query with one version (its question as a spec) and the slug view-<id>. Nothing is written or moved: the view keeps working exactly as before, and a private view is still its owner's alone.

Running

Door Who Notes
saved_query_run (MCP) Any caller with event:read on the project Up to 200 rows, a cursor, the evidence block, the scan class.
POST …/saved-queries/{slug}/run A signed-in caller with event:read The same function.
POST …/saved-queries/{slug}/versions/{v}/run A query token The external endpoint. Published versions only.

Every run is a query-log row of surface saved_query carrying the saved query's id and the version; GET …/saved-queries/{slug}/runs lists them (your own, unless you can read the organization's log). A version nobody has shared runs for its author only; a disabled or archived query refuses every run. Rows are telemetry: group labels are cleaned and listed as untrusted, and an agent receives them fenced. So are the words the query's author wrote that a run hands back: the query's name and the bound values in the compiled statement (the spec's own filter values among them).

The external endpoint and query tokens

An organization owner publishes the current shared version (POST …/versions/{v}/publish). A version that needs issue data (the events dataset) or a person-level key cannot be published: a query token carries neither. GET …/versions/{v}/openapi.json describes the run route, its typed variables as a required body and the shape of a row.

A query token (bkr_qt_…) is minted by a person (POST …/query-tokens, owner or admin, behind the password step-up):

  • it pins at most 20 published versions of one project and lives at most 90 days;
  • it runs 60 times a minute (counted from the log, so it holds across machines);
  • it is shown once, stored only as a SHA-256 digest, and backed by a service principal with no membership;
  • it is accepted by exactly two routes, the run route and openapi.json. Everywhere else it is an invalid access token; the RFC 8693 exchange and the MCP server refuse it.

Revoking is idempotent and needs only an owner or admin.

In bucker.yml

version: 2
projects:
  checkout:
    savedQueries:
      - slug: checkout-errors
        name: Checkout errors by service
        version:
          spec: { v: 1, dataset: spans, select: [{ fn: count, as: n_spans }],
                  where: [{ key: service, op: eq, var: service }],
                  variables: { service: { type: string, required: true } } }
          variables: [{ name: service, type: string, required: true }]

Applying a file proposes the version through the governed operation, which asks for approval, so nothing a file says is live until an approver says yes. A file never deletes a query, never exports a private draft, and plan after export is unchanged.

Not yet

Materialization (WH-17), suggestions and certification (WH-18), alert rules reading a query (MON-32) and the sq_<slug> per-version tools are later work; the tools that would carry them answer not_available rather than reading as empty.