Cypher Reference
The read-only Cypher dialect at a glance: supported clauses and functions, the five golden rules, and the full language reference pages.
Cypher Reference Documentation
WhisperGraph speaks a read-only dialect of Cypher, the graph query language, over HTTP. You POST a query to the Cypher API and get back columns and rows; there is no driver to install and no session to manage. If you have used Neo4j, you already know most of the language. Write clauses (CREATE, MERGE, SET, DELETE, REMOVE, FOREACH) are recognized by the parser and rejected.
This section is the language reference. Syntax & Clauses covers every supported clause with verified examples, Functions documents the full function library, Best Practices collects the habits that separate an instant answer from a timeout, and the Cheat Sheet fits the whole language on one page.
The shape of a query
Almost every WhisperGraph query is anchor, traverse, return: pin a node by its indexed name, walk the edges you care about, project columns, cap the rows.
MATCH (h:HOSTNAME {name: "google.com"})-[:RESOLVES_TO]->(ip:IPV4)
RETURN ip.name AS ip
LIMIT 5
On a graph with ~39 billion edges, the anchor is what makes this fast. The engine starts at one indexed node and touches only connected edges. Skip the anchor and you ask for a scan over billions of nodes, which is slow at best and rejected at worst.
For anything with more than one stage, narrow before you expand. WITH ... LIMIT bounds the intermediate set so the next stage starts from a handful of nodes:
MATCH (h:HOSTNAME {name: "google.com"})<-[:NAMESERVER_FOR]-(ns:HOSTNAME)
WITH ns LIMIT 3
MATCH (ns)-[:NAMESERVER_FOR]->(sibling:HOSTNAME)
RETURN ns.name AS nameserver, collect(DISTINCT sibling.name)[0..8] AS domains
LIMIT 3
The same building blocks shape results: UNWIND turns a list of indicators into one anchored lookup per element, and aggregation (count, collect) with ORDER BY ... LIMIT ranks a traversal. Both are covered with examples in Syntax & Clauses.
Labels and edge names must match the live schema exactly; the graph uses HOSTNAME (there is no Domain or FQDN label). When a query returns nothing, check CALL db.labels() and CALL db.relationshipTypes() first. Introspection calls don't count against quota. The full model is in the Graph Schema.
The five golden rules
- Anchor on an indexed
name. Pin at least one node with{name: "..."}. Unanchored scans on billion-node labels likeHOSTNAMEandIPV4do not finish. - Always
LIMIT. On every query, includingCALL ... YIELD ... RETURN. For graph-wide totals, use the precomputed stats endpoint instead of counting edges. - Bound every branch. Narrow intermediates with
WITH ... LIMITbefore expanding, and put per-branch work in a boundedCALL { ... }subquery so one high-fan-out hop can't blow up the whole query. - No
*1..Nvariable-length patterns. They are the most common cause of timeouts, and synthesized edges (ROUTES,ANNOUNCED_BY,LISTED_IN,PEERS_WITH,CONFLICTS_WITH) never expand inside[*..]. Write each hop explicitly. - Procedures first.
explain(),whisper.variants(),whisper.history(), andwhisper.origins()answer the hardest questions in one call, tuned to avoid the traversals that time out. Signatures are in Procedures.
Best Practices expands each rule into do-this-not-that pairs and the known limitations behind them.
Clauses at a glance
Every clause below is documented with runnable examples in Syntax & Clauses.
| Clause | What it does |
|---|---|
MATCH / OPTIONAL MATCH | Find graph patterns; OPTIONAL MATCH keeps rows and fills null for sparse data like WHOIS contacts. |
WHERE | Filter with comparisons, AND/OR/NOT/XOR, IN, IS NULL, and STARTS WITH / ENDS WITH / CONTAINS. |
RETURN | Project columns; AS aliases, DISTINCT deduplicates. |
WITH | Pipe one stage into the next; aggregate, filter, or bound (WITH ... LIMIT) mid-query. |
ORDER BY / LIMIT / SKIP | Sort, cap, and page results. |
UNWIND | Expand a list into rows; the batch-lookup pattern. |
UNION / UNION ALL | Combine branches that return the same column names. |
CALL | Run a procedure with YIELD, or scope a bounded CALL { ... } subquery. |
EXPLAIN | Return the query plan without executing; confirm the anchor hits the index (NodeLookup, never a label scan). |
CASE | Conditional expressions, simple and searched. |
shortestPath | Minimum-hop path between two anchored nodes; requires a bounded path length. |
Functions at a glance
Full signatures, examples, and return values are in Functions.
| Group | Functions |
|---|---|
| Aggregation | count, sum, avg, min, max, collect, each with DISTINCT |
| String | toUpper, toLower, trim, replace, substring, split, left, right, reverse, toString |
| Numeric & trig | abs, ceil, floor, round, sign, sqrt, log, log10, rand, sin, cos, atan2, degrees, radians |
| Collection | size, head, last, tail, range, reverse, keys, isEmpty |
| Node & relationship | id, labels, type, properties, startNode, endNode, nodes, relationships |
| Type conversion | toInteger, toFloat, toBoolean, toIntegerList, toFloatList, toStringList, toBooleanList |
| Date & time | timestamp, date, datetime, localdatetime, time, duration |
| Geo & misc | point, distance, coalesce, randomUUID |
Go deeper
- Syntax & Clauses — every supported clause, pattern and path syntax, and parameter binding.
- Functions — the full library with signatures and example results.
- Best Practices — do this, not that; known limitations and how to work around them.
- Cheat Sheet — the language on one page, ready to copy.
- Cypher API — the endpoint, auth tiers (anonymous runs 2 hops; a free key raises it to 3 via the
X-API-Keyheader), and the response envelope. - Use Cases — copy-paste recipes and runnable workflows organized by job.