Skip to main content

KQL Syntax

This page is the curated narrative reference for KQL. It has been refreshed against the live HELP registry exposed by KFDB.

For exhaustive HELP-backed coverage, including audit status and function families, see KQL HELP Audit.

Start with Discovery​

Before writing graph queries, use the live schema/discovery commands:

HELP
SHOW LABELS
SHOW EDGE_TYPES
SHOW PROPERTIES
SHOW PROPERTIES File
SHOW SCHEMA

Try it live:

KQL Query
Sign in with Privy to open a live bearer session and sign-to-derive key for your database. The playground will attach the correct auth headers automatically.
Loading...
Press Ctrl+Enter to run

Core Clause Order​

Live HELP currently documents the core shape as:

MATCH <pattern>
[WHERE <condition>]
[WITH <projection>]
RETURN <expressions>
[ORDER BY ...]
[LIMIT n]
[OFFSET n]

KQL also supports:

  • OPTIONAL MATCH
  • GROUP BY
  • HAVING
  • UNWIND
  • UNION / UNION ALL
  • AT TIMESTAMP
  • HISTORY FROM ... TO ...
  • RETURN *
  • RETURN n.*

MATCH and OPTIONAL MATCH​

MATCH (f:File)-[:DEFINES]->(fn:Function)
RETURN f.path, fn.name
LIMIT 10
KQL Query
Sign in with Privy to open a live bearer session and sign-to-derive key for your database. The playground will attach the correct auth headers automatically.
Loading...
Press Ctrl+Enter to run

Optional patterns return NULL columns when the relationship does not exist:

OPTIONAL MATCH (r:Repository)-[:CONTAINS]->(f:File)
RETURN r.name, f.path
LIMIT 10

WHERE, Operators, and Parameters​

KQL supports comparison, logical, string, null, list, arithmetic, and vector-similarity operators.

Examples:

MATCH (f:File)
WHERE f.path ENDS WITH '.rs'
  AND f.language = 'Rust'
  AND f.size >= 1000
RETURN f.path, f.size
ORDER BY f.size DESC
LIMIT 10
MATCH (n:Snippet)
WHERE n.embedding SIMILAR TO vector([0.1, 0.2])
RETURN n.path
MATCH (n:File)
WHERE n.language = $language
RETURN n.path
ORDER BY n.path

RETURN, RETURN *, and RETURN n.*​

MATCH (n:File)
RETURN n.path AS path, n.language AS language
LIMIT 5
MATCH (n:File)
RETURN n.*
LIMIT 5
MATCH (r:Repository)-[:CONTAINS]->(f:File)
RETURN *
LIMIT 5

WITH for Multi-Stage Queries​

Use WITH to pipe variables between stages:

MATCH (f:File)
WHERE f.language = 'Rust'
WITH f
MATCH (f)-[:DEFINES]->(fn:Function)
RETURN f.path, COUNT(fn) AS fn_count
GROUP BY f.path
ORDER BY fn_count DESC
LIMIT 10
KQL Query
Sign in with Privy to open a live bearer session and sign-to-derive key for your database. The playground will attach the correct auth headers automatically.
Loading...
Press Ctrl+Enter to run

Aggregation, GROUP BY, and HAVING​

MATCH (n:File)
RETURN n.language, COUNT(n) AS count
GROUP BY n.language
HAVING COUNT(n) > 5
ORDER BY count DESC

UNWIND​

Use UNWIND to expand arrays into rows:

MATCH (r:Repository)
UNWIND ['README.md', 'Cargo.toml'] AS file_name
RETURN r.name AS repo, file_name
LIMIT 10

UNION and UNION ALL​

MATCH (r:Repository)
RETURN r.name AS value
LIMIT 5
UNION ALL
MATCH (f:File)
RETURN f.path AS value
LIMIT 5

Window Functions​

Live HELP exposes:

  • ROW_NUMBER()
  • RANK()
  • DENSE_RANK()
  • LAG()
  • LEAD()

Example:

MATCH (r:Repository)
RETURN r.language AS lang,
       ROW_NUMBER() OVER (PARTITION BY r.language ORDER BY r.name) AS language_rank
LIMIT 20

Temporal Queries​

Point-in-time snapshot​

MATCH (n:File)
AT TIMESTAMP '2025-06-15T12:00:00Z'
WHERE n.path CONTAINS 'src'
RETURN n.path
ORDER BY n.path
LIMIT 20

Historical range​

MATCH (n:File)
HISTORY FROM '2025-01-01' TO '2025-12-31'
WHERE n.path ENDS WITH '.rs'
RETURN n.path, n.size
LIMIT 20

AI Expressions​

KQL HELP currently exposes two AI expressions:

  • AI.IF(prompt => ..., model => ...)
  • AI.SIMILARITY(expr1, expr2)

Examples:

MATCH (r:Review)
WHERE AI.IF(
  prompt => 'Is this review actionable? ' + r.text,
  model => 'gemini-3-flash-preview'
)
RETURN r.title
LIMIT 10
MATCH (a:Issue), (b:Fix)
WHERE AI.SIMILARITY(a.description, b.content) > 0.82
RETURN a.title, b.title
LIMIT 20

Common Function Families​

The live HELP registry currently includes:

  • graph: labels, id, type, properties, keys
  • string: toString, toUpper, toLower, trim, substring, replace, split, reverse
  • numeric: abs, round, sqrt, pow, trig functions, rand
  • type conversion: toInteger, toFloat, toBoolean
  • list and collection: head, tail, last, range, any, all, none, single
  • full-text search helpers: search, match, highlight, snippet, score
  • vector helpers: vector, cosine_similarity, euclidean_distance, dot_product
  • path helpers: shortestPath, shortestPathLength
  • aggregate: COUNT, SUM, AVG, MIN, MAX, COLLECT
  • temporal: timestamp

See KQL HELP Audit for the exhaustive matrix.

Live Playground​

KQL Query
Sign in with Privy to open a live bearer session and sign-to-derive key for your database. The playground will attach the correct auth headers automatically.
Loading...
Press Ctrl+Enter to run

Next Steps​