Query language

In order:

1. Type/value autocorrect. Any label or relationship-type token not in the live schema is resolved through a curated alias map (DOMAIN → HOSTNAME, IP → IPV4, AS → ASN, …), then case/separator normalization, then nearest-match against the live set — so it self-updates as the schema changes. An ASN {name: …} value is normalized to the canonical AS<digits> form. A confident correction runs automatically and the result carries rewritten: true with a TYPE_NORMALIZED rewrite.
2. Read-only pre-check. Write and admin clauses (CREATE / MERGE / DELETE / SET / REMOVE / FOREACH / LOAD CSV) and mutating or admin CALL procedures are rejected before anything runs — including under an EXPLAIN prefix. A negative lookbehind keeps a property accessor like n.create from tripping it.
3. The nine safety rules, in order, first failure wins.
4. The cost gate, which reads the query plan and rejects only a genuine blow-up.
5. Execution.
6. Idiom correct-and-retry. On an engine error (not a validator rejection), one bounded retry translates a recognized non-Whisper idiom (SHOW PROCEDURES → CALL db.procedures(), YIELD relationshipType → YIELD type) and re-runs once.

The query path is provably read-only. The sanctioned write path is the two dedicated submit_* tools, never query.

query returns a typed error envelope that clients and LLMs can branch on instead of parsing free text.

There are eleven codes:

QUERY_TOO_EXPENSIVE is the size guard, distinct from DB_TIMEOUT's duration guard — a query can be cheap per row and still touch too many elements.

There is no CYPHER_SYNTAX_ERROR code, and there never has been on this server. <!-- drift-ok: named here in order to say it does not exist --> A syntax problem classifies as SCHEMA_ERROR (bad label / property / column) or SYNTAX_ERROR (malformed Cypher), and an over-cap LIMIT as LIMIT_ERROR. If your client branches on CYPHER_SYNTAX_ERROR, that branch is dead code.

The MCP server never returns HTTP 429. It applies no rate or usage limiting of its own — a request is 401 (auth failure) or 503 (auth backend degraded). A 429 you see in this stack came from the graph engine's own concurrency guard and carries the engine's {quota: {plan, maxConcurrent, current}} shape.

The validator runs them in order; the first failure wins; an EXPLAIN <query> is exempt. String literals, // and /* */ comments, and backtick-quoted identifiers are stripped before matching, so a value or a comment can never trip a rule.

Two further guards run alongside the rules rather than as rules, because they depend on the bound parameters rather than the query text: a null LIMIT/SKIP parameter (which the engine reads as unbounded, silently) and an UNWIND over five or more values feeding a CALL {} subquery. Both return a typed error with a fix.

The cost gate

A query can pass all nine rules and still be a blow-up — a Cartesian product from accidentally-disconnected patterns, or an unbounded variable-length expansion off a huge label scan, only shows up in the plan. The gate fetches that plan (an EXPLAIN; nothing executes) and classifies it:

Only DECOMPOSE is rejected, because paging cannot help: the engine materializes the join or expansion before any LIMIT trims it. Rewrite it — anchor a node, connect the patterns, or stage the traversal. The gate is fail-open end to end, so it can only add a rejection on top of the nine rules, never silently drop a query that would otherwise have run.

The validator does more than reject. Where it safely can, it bounds or rewrites the query, runs it anyway, and tells you what it did.

Two classes of correction. Bounding rewrites run automatically — they trim the result to a bounded prefix, same rows, just capped. Semantic rewrites come back as a fix and are never auto-run, because they change which rows match: EXACT_MATCH (an unindexed CONTAINS → =), BOUND_PATH, and ADD_LABEL / PICK_LABEL / ANCHOR_MATCH, which carry no rewrittenCypher because they need a value only you have.

No validator rejection is ever a bare error. It is auto-fixed, auto-bounded, or it carries a fix.

These return a wrong answer rather than an error, which makes them worth more attention than the rules above.

Sorting or aggregating the feed→category chain returns zero rows

Measured on production 2026-08-09, reproducible on an unlimited-depth key:

MATCH (ip:IPV4 {name: "185.220.101.1"})-[:LISTED_IN]->(f:FEED_SOURCE)-[:BELONGS_TO]->(cat:CATEGORY)
RETURN f.id AS feed, cat.id AS category
LIMIT 20

→ 6 rows, correct.

Add ORDER BY category, feed — or replace the projection with count(*) / collect(...) — and the same query returns zero rows with success: true. No error, no advisory. Each hop works alone under ORDER BY, and another two-hop virtual chain (IPV4 → PREFIX ← ASN) is unaffected.

Until it is fixed, sort client-side or stage the hops apart:

MATCH (ip:IPV4 {name: "185.220.101.1"})-[:LISTED_IN]->(f:FEED_SOURCE)
WITH collect(f.id) AS feeds
MATCH (fs:FEED_SOURCE)-[:BELONGS_TO]->(c:CATEGORY) WHERE fs.id IN feeds
RETURN fs.id AS feed, c.id AS category ORDER BY category, feed

Tracked as whisper-dbj-ng#1492.

Edge direction

Four edges point the opposite way to intuition, and traversing them backwards returns an empty result rather than an error:

• RESOLVES_TO is forward only, HOSTNAME → IPV4. Reverse DNS is (ip)<-[:RESOLVES_TO]-(h).
• NAMESERVER_FOR and MAIL_FOR point server → domain. A domain's MX is (domain)<-[:MAIL_FOR]-(mx).
• LOCATED_IN is IPV4|IPV6 → CITY only. For the country, chain HAS_COUNTRY; an IPV4 → COUNTRY hop returns nothing.
• CHILD_OF runs child → parent (HOSTNAME → HOSTNAME → TLD).

Anchor feeds and categories on .id

.name carries a display form that varies, so a filter on it can silently return nothing. Filter and project on .id, the stable slug (c2, tor, ad-tracking). And never scan FEED_SOURCE or CATEGORY directly — rule 7 rejects it at any size; reach them via LISTED_IN from an anchored node.

CONTAINS at scale

STARTS WITH and ENDS WITH on .name are indexed and fast at any scale. CONTAINS on .name is allowed, but with no LIMIT or a low-selectivity substring it degrades to a whole-label scan and hits the execution deadline. On ASN.name specifically it times out — use STARTS WITH "AS…". Pair an unanchored CONTAINS with an anchoring predicate.

Virtual edges need one anchored endpoint

About two thirds of the 50 edge types are synthesized at query time — including ROUTES, HAS_NAME, CONFLICTS_WITH, ANNOUNCED_BY, LISTED_IN, TAGGED_AS, BGP_PATH, HAS_COUNTRY, LOCATED_IN, and the physical-infrastructure and RPKI edges. They traverse normally, including inside [*1..N], but a fully bare MATCH (a)-[:TYPE]->(b) is rejected (rule 5) rather than returned empty.

Labels that exist but have no edges

RDAP_ENTITY, DNS_ROOT_INSTANCE and DWI_DOMAIN are node-only: a traversal from them returns zero rows because there is nothing to traverse, not because your pattern is wrong. RIR is retired and nothing reaches it.

Beyond the dedicated tools, query accepts these procedures directly inside Cypher, so you can compose them into a larger query.

whisper.assess and whisper.walk are procedures, not tools — their tool-level equivalents were folded into explain_indicator and identify, but the CALL form is still live and still the right way to compose them inside a larger query.

whisper.variants() also works in expression position, not only as a top-level CALL — RETURN size(whisper.variants("paypal.com")) works. explain() and whisper.history() are CALL-only.

For a packaged, multi-step version of any of these, run a gallery workflow with run_workflow.

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