Query language

query is the one tool that takes Cypher: you write the pattern, the server validates it, and the response carries the query that actually ran. Reach for it when no prepared investigation fits — explain_indicator and run_workflow cover the common questions. For its arguments and response shape see the Reference, and for a worked investigation Your first investigation.

What happens to a query

The server does more than accept or refuse:

1. Input-length pre-check. An over-long cypher string is rejected outright, ahead of everything else and under an EXPLAIN prefix too — never shortened and run for you.
2. Type/value autocorrect. A label or relationship type that is not in the live schema is resolved through a curated alias map, then nearest-match against the live set; a confident correction runs and the result says so.
3. Read-only pre-check. Write and admin clauses, and mutating or admin CALL procedures, are rejected before anything runs — an EXPLAIN prefix included.
4. The ten safety rules, in order, first failure wins.
5. The cost gate, which reads the query plan and rejects only a genuine blow-up.
6. Execution, and on an engine error one bounded retry that translates a recognized non-Whisper idiom and runs again.

Step 3 is what makes the whole server read-only: query is the only place a caller supplies Cypher at all — the prepared workflows behind run_workflow take a slug and parameter values, never a query string.

The ten safety rules

Each rule names a query shape the engine cannot serve. The validator runs them in order and the first failure wins; string literals, comments and backtick-quoted identifiers are stripped before matching, so a value can never trip a rule, and an EXPLAIN is exempt. Two never reject: a LIMIT the engine will not serve is clamped, a missing one is injected, and the query runs. What each rejects and allows is tabled on the Reference, with the cost gate that reads the plan after them.

What comes back

A success carries columns, rows and statistics, plus an evidence block naming the Cypher that ran, its timestamp and which instance answered — enough to cite a row or reproduce it.

A failure carries a typed envelope rather than free text: the message, a suggestion to apply, a machine-readable errorCode, and a retryable flag read straight off that code, so a client branches on a field rather than on prose. The codes are listed on the Reference.

No rejection is ever a bare error. A correction that only narrows the result is applied, run, and reported in autoLimited or rewritten; one that would change which rows match comes back as a fix for the agent to apply. A bounded result says so in a field rather than in the prose, so read the self-correction fields before concluding you have the whole set.

Names come from the schema

Label names, property names and which way an edge points belong to the Graph Schema, and explain_schema answers the same question in a call. A query that returns nothing without an error is usually a reversed edge or a label that carries no edges; the shapes specific to this surface are under traversal landmines.

query also takes the whisper.* procedures inside Cypher, so a verdict or an enrichment composes into a larger query; the callable list is on the Reference.

Read coverage before band. Only known-clean — coverage: known-clean. In coverage, no malicious evidence. licenses the word "clean"; no-data — coverage: no-data. Not in coverage. This is not a verdict — nothing was looked at. means unknown, which is a different thing again; malicious-evidenced — coverage: malicious-evidenced. In coverage, with positive evidence of malice. and ambiguous — coverage: ambiguous. In coverage, and the evidence points both ways. mean there is evidence, whatever the band says. Full contract: Coverage — what we looked at.

Next

• Reference — the tools, with input shapes and response fields.
• Cypher guide — the language reference, functions and the cookbook.
• Your first investigation — these rules on one real alert.