Cypher Language Reference

Schema guide

Node labels

Edge types

DNS resolution

BGP and routing

WHOIS and registration

GeoIP

Threat intelligence

Web

SPF

Other

Entity relationship diagram

Entity Relationship Diagram

Solid lines are physical edges stored on disk. Dashed lines are virtual edges computed at query time from live infrastructure and threat intelligence data.

Solid lines are physical edges stored on disk. Dashed lines are virtual edges computed at query time from live infrastructure and threat intelligence data.

Multi-hop path patterns

These are the most common traversal chains through the graph.

Domain to network owner:

HOSTNAME -[:RESOLVES_TO]-> IPV4 -[:ANNOUNCED_BY]-> ANNOUNCED_PREFIX -[:ROUTES]-> ASN -[:HAS_NAME]-> ASN_NAME

Domain to nameservers:

HOSTNAME(ns) -[:NAMESERVER_FOR]-> HOSTNAME(domain)

Domain to mail servers:

HOSTNAME(mx) -[:MAIL_FOR]-> HOSTNAME(domain)

IP to GeoIP location:

IPV4 -[:LOCATED_IN]-> CITY -[:LOCATED_IN]-> COUNTRY

IP to threat feeds:

IPV4 -[:LISTED_IN]-> FEED_SOURCE -[:BELONGS_TO]-> CATEGORY

Domain WHOIS chain:

HOSTNAME -[:HAS_REGISTRAR]-> REGISTRAR
HOSTNAME -[:HAS_EMAIL]-> EMAIL
HOSTNAME -[:REGISTERED_BY]-> ORGANIZATION

DNS hierarchy:

HOSTNAME -[:CHILD_OF]-> HOSTNAME(parent) -[:CHILD_OF]-> TLD

RIR allocation chain:

IPV4 -[:BELONGS_TO]-> REGISTERED_PREFIX -[:REGISTERED_BY]-> ORGANIZATION

Language reference

MATCH

Basic pattern matching. Always anchor your starting node with {name: "value"} on large labels like HOSTNAME and IPV4.

MATCH (n:HOSTNAME {name: "www.google.com"}) RETURN n.name

MATCH (h:HOSTNAME {name: "www.google.com"})-[:RESOLVES_TO]->(ip:IPV4)
RETURN h.name, ip.name LIMIT 10

OPTIONAL MATCH

Returns null for unmatched patterns instead of dropping the row. Use this for WHOIS fields and other sparse data where not every node has every relationship.

MATCH (h:HOSTNAME {name: "www.google.com"})
OPTIONAL MATCH (h)-[:HAS_CERTIFICATE]->(c)
RETURN h.name, c.name

This returns one row with c.name as null, rather than zero rows.

WHERE clause

Comparison operators:

=, <>, <, >, <=, >=

MATCH (n:TLD) WHERE n.name <> "com" RETURN n.name LIMIT 3

String predicates:

-- Prefix search (fast, uses index)
MATCH (n:HOSTNAME) WHERE n.name STARTS WITH "www.googl" RETURN n.name LIMIT 5

-- Substring search (fast)
MATCH (n:HOSTNAME) WHERE n.name CONTAINS "cloudflare" RETURN n.name LIMIT 5

-- Suffix search (fast on HOSTNAME and TLD, slow on other labels)
MATCH (n:HOSTNAME) WHERE n.name ENDS WITH ".google.com" RETURN n.name LIMIT 5

Regular expressions:

MATCH (n:HOSTNAME) WHERE n.name =~ "www\\.google\\.com" RETURN n.name LIMIT 1

Regex uses full-match semantics (not substring). Nested quantifiers are rejected for safety. Maximum pattern length is 1000 characters. Prefer STARTS WITH, ENDS WITH, or CONTAINS instead of regex when possible.

Logical operators: AND, OR, NOT, XOR

WITH 5 AS x WHERE x > 3 AND x < 10 RETURN x

NULL checks: IS NULL, IS NOT NULL

WITH null AS x RETURN x IS NULL AS result

List membership: IN

MATCH (n:ASN) WHERE n.name IN ["AS13335", "AS15169"] RETURN n.name

RETURN

Projects columns from matched patterns. Supports aliases with AS and DISTINCT.

MATCH (h:HOSTNAME {name: "www.google.com"})-[:RESOLVES_TO]->(ip)
RETURN DISTINCT ip.name AS address

MATCH (h:HOSTNAME {name: "www.google.com"})-[:RESOLVES_TO]->(ip)
WITH h.name AS host, collect(ip.name) AS ips
RETURN host, ips

WITH

Pipes results between query stages. You can aggregate, filter, and reshape data mid-query.

MATCH (h:HOSTNAME {name: "www.google.com"})-[:RESOLVES_TO]->(ip)
WITH h.name AS host, count(ip) AS ipCount
RETURN host, ipCount

MATCH (sub:HOSTNAME)-[:CHILD_OF]->(h:HOSTNAME {name: "github.com"})
WITH sub LIMIT 5000
MATCH (sub)-[:RESOLVES_TO]->(ip:IPV4)
RETURN DISTINCT ip.name LIMIT 30

ORDER BY, LIMIT, SKIP

Sort results and paginate. Always use LIMIT on queries against large labels.

MATCH (n:TLD) RETURN n.name ORDER BY n.name ASC LIMIT 5

MATCH (n:COUNTRY) RETURN n.name ORDER BY n.name SKIP 2 LIMIT 3

Both SKIP N LIMIT M and LIMIT M SKIP N orderings are supported.

UNWIND

Turns a list into individual rows. This is the batch lookup pattern.

UNWIND ["google.com", "cloudflare.com", "microsoft.com"] AS domain
MATCH (h:HOSTNAME {name: domain})
OPTIONAL MATCH (h)-[:HAS_REGISTRAR]->(r:REGISTRAR)
RETURN domain, collect(DISTINCT r.name) AS registrars

You can pass dozens or hundreds of indicators in a single UNWIND list.

UNION

Combines results from multiple MATCH clauses. UNION deduplicates; UNION ALL keeps duplicates.

MATCH (n:TLD {name: "com"}) RETURN n.name
UNION
MATCH (n:TLD {name: "net"}) RETURN n.name

CALL subqueries

Correlated subqueries import variables with WITH.

MATCH (h:HOSTNAME {name: "www.google.com"})
CALL { WITH h MATCH (h)-[:RESOLVES_TO]->(ip) RETURN count(ip) AS ipCount }
RETURN h.name, ipCount

CALL is also used to invoke procedures:

CALL explain("185.220.101.1")

CALL whisper.history("cloudflare.com")

CALL whisper.quota()

CALL db.labels()

CALL db.relationshipTypes()

EXPLAIN

Shows the query plan without executing the query.

EXPLAIN MATCH (h:HOSTNAME {name: "www.google.com"})-[:RESOLVES_TO]->(ip) RETURN ip.name

ProduceResult([ip.name])
  Project([ip.name])
    Expand(h-[RESOLVES_TO]->ip)
      NodeLookup(h={name:'www.google.com'}:HOSTNAME)

Use EXPLAIN to verify the engine is using an indexed lookup rather than a label scan. PROFILE returns the same plan plus row counts per operator.

CASE / WHEN

Conditional expressions.

RETURN CASE WHEN 1 > 0 THEN "positive" ELSE "negative" END AS result

MATCH (h:HOSTNAME {name: "cloudflare.com"})-[:RESOLVES_TO]->(ip:IPV4)
OPTIONAL MATCH (ip)-[:LISTED_IN]->(f:FEED_SOURCE)
RETURN ip.name,
       CASE WHEN f IS NOT NULL THEN "listed" ELSE "clean" END AS status
LIMIT 5

Nested CASE expressions are supported.

shortestPath

Finds the minimum-hop path between two nodes.

MATCH (a:HOSTNAME {name: "cloudflare.com"}), (b:HOSTNAME {name: "google.com"})
MATCH p = shortestPath((a)-[*1..6]-(b))
RETURN length(p) AS hops, [n IN nodes(p) | n.name] AS path

Always specify a bounded path length like [*1..6]. Unbounded paths may be slow or time out. allShortestPaths() is also supported and returns all paths of the shortest length.

EXISTS subqueries

MATCH (h:HOSTNAME {name: "www.google.com"})
WHERE EXISTS { (h)-[:RESOLVES_TO]->() }
RETURN h.name

The function-style EXISTS(expr) predicate is also supported. It returns true if the expression is non-null:

MATCH (h:HOSTNAME {name: "google.com"}) RETURN EXISTS(h.name) AS has_name

COUNT subqueries

MATCH (h:HOSTNAME {name: "www.google.com"})
RETURN h.name, COUNT { (h)-[:RESOLVES_TO]->() } AS ipCount

Note: COUNT{}, COLLECT{}, and EXISTS{} subqueries cannot be used directly in ORDER BY. Pre-compute in a WITH clause, then sort by the alias.

COLLECT subqueries

MATCH (h:HOSTNAME {name: "www.google.com"})
RETURN h.name, COLLECT { MATCH (h)-[:RESOLVES_TO]->(ip) RETURN ip.name } AS ips

List comprehensions

RETURN [x IN range(1, 10) WHERE x % 2 = 0] AS evens

WITH [1, 2, 3, 4, 5] AS nums
RETURN [x IN nums WHERE x > 2 | x * 10] AS filtered

Pattern comprehensions

MATCH (h:HOSTNAME {name: "www.google.com"})
RETURN h.name, [(h)-[:RESOLVES_TO]->(ip) | ip.name] AS ips

Function reference

Aggregation

Note: min() and max() work on both aggregated rows and list literals.

String

Numeric

Arithmetic operators: +, -, *, /, %, ^ (exponent), + (string concatenation).

Trigonometric

sin(), cos(), tan(), asin(), acos(), atan(), atan2(), degrees(), radians()

All accept and return radians, except degrees() which converts radians to degrees, and radians() which converts degrees to radians.

Geospatial

Collection

List predicates

Node and relationship

Type conversion

Date and time

Property access on datetime values: .year, .month, .day, .hour, .minute, .second, .epochMillis, .epochSeconds.

Features

Threat intelligence

Whisper Graph indexes 40+ threat intelligence feeds across 18 categories. This data comes from whisper-feeds, a companion service that aggregates live threat feed data from public and commercial sources, with hourly incremental and daily full refresh cycles.

The threat intelligence layer works like this:

• IPs and hostnames that appear in threat feeds are connected to FEED_SOURCE nodes via LISTED_IN virtual edges.
• Each FEED_SOURCE belongs to one or more CATEGORYs (e.g., "C2 Servers", "Phishing", "General Blacklists").
• ASN nodes may carry threat properties like maxThreatScore and overallThreatLevel.
• The explain() procedure computes a composite score that factors in feed count, feed weights, recency, and network density.

Querying threat feeds directly:

MATCH (ip:IPV4 {name: "185.220.101.1"})-[:LISTED_IN]->(f:FEED_SOURCE)
RETURN ip.name, f.name

[
  {"ip.name": "185.220.101.1", "f.name": "Dan Tor Exit"},
  {"ip.name": "185.220.101.1", "f.name": "FireHOL Level 2"},
  {"ip.name": "185.220.101.1", "f.name": "Spamhaus DROP"}
]

Scored threat assessment with explain():

explain() accepts IPs, domains, ASNs, and CIDR ranges.

CALL explain("185.220.101.1")

[{
  "indicator": "185.220.101.1",
  "type": "ip",
  "found": true,
  "score": 5.28,
  "level": "INFO",
  "explanation": "185.220.101.1 is listed in 3 threat feed(s). Score 5.3 (Informational - minimal risk).",
  "factors": [
    "Listed in 3 source(s) with combined weight 2.20",
    "Base score: 2.20 x log2(3 + 1) = 4.40",
    "Recency boost: x1.2 (last seen just now)"
  ]
}]

CALL explain("cloudflare.com")

[{
  "indicator": "cloudflare.com",
  "type": "domain",
  "found": true,
  "score": 0.0,
  "level": "NONE",
  "explanation": "Not listed in any threat intelligence feed"
}]

CALL explain("AS60729")

[{
  "indicator": "AS60729",
  "type": "asn",
  "found": true,
  "score": 0.0,
  "level": "NONE",
  "explanation": "AS60729 (TORSERVERS-NET, DE) has a reputation score of 48.5 (Suspicious)."
}]

CALL explain("185.220.101.0/24")

[{
  "indicator": "185.220.101.0/24",
  "type": "network",
  "found": true,
  "score": 0.0,
  "level": "MEDIUM",
  "explanation": "Network 185.220.101.0/24 contains 167 listed IPs across multiple threat feeds."
}]

The level field returns one of: NONE, INFO, LOW, MEDIUM, HIGH, CRITICAL.

Feed sources (all 40):

Categories (all 18):

Ad/Tracking Blocklists, Anonymization Infrastructure, Attack Sources, Brute Force, C2 Servers, General Blacklists, Malicious Domains, Malicious Infrastructure, Malware Distribution, Phishing, Popularity/Trust, Proxies, Reference Data, Reputation, Spam, TOR Network, Threat Intelligence, VPNs.

Domain history

The whisper.history() procedure returns timestamped WHOIS and BGP snapshots for an indicator.

CALL whisper.history("cloudflare.com")

[
  {
    "indicator": "cloudflare.com",
    "type": "domain",
    "queryTime": "2024-06-13 18:31:16",
    "createDate": "2009-02-17",
    "updateDate": "2024-01-09",
    "expiryDate": "2033-02-17",
    "registrar": "CloudFlare, Inc.",
    "nameServers": "..."
  },
  {
    "indicator": "cloudflare.com",
    "type": "domain",
    "queryTime": "2020-05-01 07:03:56",
    "createDate": "2009-02-17",
    "registrar": "Cloudflare, Inc."
  }
]

Supported indicator types: domain, IP, ASN, CIDR, hash.

History works on registrable domains (e.g., google.com), not subdomains (www.google.com). Subdomains return empty results.

Quota and plan info

CALL whisper.quota()

Returns your current plan tier, hourly query limit, usage count, maximum traversal depth, and concurrent query count.

Schema introspection

Discover what is in the graph without knowing the schema up front.

-- All node labels with counts
CALL db.labels()

Returns every label in the graph with its count, including virtual labels (REGISTERED_PREFIX, ANNOUNCED_PREFIX, FEED_SOURCE, CATEGORY).

-- All edge types with counts
CALL db.relationshipTypes()

Returns every edge type with its count, including virtual edge types (LISTED_IN, ANNOUNCED_BY, OPERATES).

-- All property keys
CALL db.propertyKeys()

Returns all known property keys in the graph.

-- Full schema summary
CALL db.schema()

Returns labels, relationship types, and property keys in a single response.

These are all instant lookups, regardless of graph size.

Best practices

General rules

• Anchor your starting node. MATCH (n:HOSTNAME {name: "example.com"}) does an indexed lookup. MATCH (n:HOSTNAME) scans billions of nodes.
• Always use LIMIT. Especially on traversals that could fan out (LINKS_TO, RESOLVES_TO on CDN IPs). Start small and increase if needed.
• Use OPTIONAL MATCH for WHOIS fields. Not every domain has a registrar, email, or phone. A required MATCH on a missing field returns zero rows and hides other results.
• Use count() before pulling large result sets. Check cardinality first to avoid unexpectedly large responses.
• Use UNWIND for batch lookups. Pass lists of indicators in a single request rather than making one request per indicator.
• Specify edge types explicitly. [:RESOLVES_TO] is faster than [r] because the engine does not need to check all edge types.
• Use ANNOUNCED_BY for current BGP routing. Use BELONGS_TO for the registered RIR allocation. They return different prefix types and may give different results.
• Anchor LINKS_TO queries. The web link graph is one of the largest datasets. Queries without an anchored starting node will time out.
• Avoid CONTAINS with special characters. Characters like & cause slow full-text scans. Use STARTS WITH or exact match when possible.

Do this / not that