CompassQL

CompassQL is Compass's deterministic, read-only structural query language. It is a documented subset of openCypher that executes directly over an immutable Compass graph snapshot. It does not invoke a model, access a network, mutate the graph, or copy data into another database.

Commands

Natural-language discovery and structural queries are explicit modes:

compass query "where is authentication enforced?"
compass query --cql 'MATCH (f:Function)-[:CALLS]->(a) RETURN f.id, a.id'
compass query --cql --file queries/auth.cypher --param target=authorize
compass query --cql --file query.cypher --params-file params.json
compass query --cql --stdin --format json
compass query --cql --repl

Compass never guesses the mode from query text. There is no alternate legacy frontend; compass query --cql is the only command contract.

Exactly one query source is required: one positional argument, --file, --stdin, or --repl. Files and stdin are limited to 1 MiB. A parameter file must be a JSON object no larger than 16 MiB. --param name=value parses JSON scalars/lists/maps and otherwise uses a string.

Output formats are table, json, and jsonl. --output PATH writes the completed rendering atomically. A limit, timeout, cancellation, or execution error produces no successful partial result.

JSON uses the version tag compass.cql.result/1, explicit typed values, columns, rows, and optional plan/profile objects. JSONL uses compass.cql.jsonl/1: one header, one object per row, then one summary. These tags are compatibility boundaries; consumers should reject unknown major versions.

Graph mapping

• Each Compass node is a Cypher node. Stable id, display label, name, and qualified_name are logical properties; stored attributes retain their names.
• The single Cypher label is derived from the typed kind (for example Function, Class, or Route). Legacy file_type is a compatibility alias, not the source of truth; a missing or unusable kind falls back to :Entity.
• Each stored edge is a directed relationship. Its type is the normalized uppercase relation; missing values become RELATES_TO.
• Relationship attributes retain their names. Typed source/relationshipSite fields project to source_file, source_location, line_start, and line_end. Missing confidence reads as EXTRACTED; when evidence contains multiple claims, the most conservative confidence wins (AMBIGUOUS > INFERRED > EXTRACTED).
• Parallel relationships stay distinct.

properties(n) and properties(r) use the same logical projection as direct property access and indexes. This makes a query independent of whether it is reading the typed compass.graph/1 artifact or a legacy node-link fixture. Use n.kind, n.id, n.source_file, and r.relation for portable queries; do not depend on the nested wire names (source, relationshipSite, or evidence) unless you are intentionally inspecting raw JSON.

Use n.id for the portable stable Compass string ID. id(n) and id(r) return snapshot-local integer indexes and must not be persisted or compared across graph snapshots.

Supported language

CompassQL supports MATCH, multiple patterns and repeated-variable joins, OPTIONAL MATCH, WHERE, correlated one-level EXISTS { MATCH ... } and openCypher's EXISTS { (...)-->() } shorthand, UNWIND, WITH, RETURN, projection wildcards, DISTINCT, UNION, UNION ALL, ORDER BY, SKIP, and LIMIT.

Expressions include scalar/list/map literals, parameters, property and label access, boolean and comparison operators, three-valued null logic, IN, safe regex/string predicates, arithmetic, simple/searched CASE, and list indexing/slicing.

Functions include:

• Graph: id, labels, type, nodes, relationships, length, properties, keys.
• Lists: any, all, none, single, size, head, last.
• Conditional/string: coalesce, toLower, toUpper, trim, split, replace.
• Conversion: toInteger, toFloat, toString, toBoolean.
• Aggregation: count, min, max, sum, avg, collect, including accepted DISTINCT forms.

Fixed, bounded variable-length, shortestPath, and allShortestPaths patterns are supported. Every variable-length relationship needs an explicit upper bound, and no bound may exceed 32. A relationship cannot repeat within one matched path.

MATCH p=shortestPath(
  (endpoint:Function)-[:CALLS|IMPORTS_FROM*1..8]->(authorization:Function)
)
WHERE authorization.label = $target
  AND all(edge IN relationships(p) WHERE edge.confidence = 'EXTRACTED')
RETURN endpoint.id, p, length(p) AS hops
ORDER BY hops
LIMIT 100

Planning and profiling

Prefix a query with EXPLAIN to compile and show its operator/optimization plan without execution. PROFILE executes and returns per-clause input/output rows, candidate nodes, expanded relationships, peak working-memory estimates, elapsed time, and cancellation checkpoints.

Compiler cache keys include exact source, CompassQL/planner versions, ordered parameter types, planning limits, and graph schema fingerprint. Cached plans contain no graph values, parameters, deadlines, cancellation state, or result rows.

Limits

Interactive defaults are:

The corresponding flags are --timeout-ms, --max-rows, --max-path-depth, --max-expanded-relationships, and --max-memory-bytes. Values may lower but never raise the language path ceiling.

Diagnostics and exits

Diagnostics carry stable codes and byte spans. The main families are:

CLI exit 2 means source/options/compile failure, exit 3 means graph loading failure, and exit 4 means execution, limit, cancellation, or output failure. No diagnostic includes parameter values or credentials.

Portability and unsupported syntax

CompassQL is not full openCypher, Neo4j Cypher, or ISO GQL. Mutation (CREATE, MERGE, DELETE, SET, REMOVE, FOREACH), procedures/CALL, LOAD CSV, schema/administration commands, dynamic execution, arbitrary nested subqueries, user-defined functions, and unbounded paths are rejected with stable CQL1xxx–CQL4xxx diagnostics. Unsupported constructs are never approximated.

See COMPASSQL_SUPPORT.md for the checked feature matrix.