Cypher Query Features Supported vs Unsupported in QueryGraph: A Complete Guide

The QueryGraph engine in DeusData/codebase-memory-mcp supports a read-only subset of Cypher including MATCH, WHERE, RETURN, and basic aggregations, while explicitly rejecting UNION, graph mutations, subqueries, and advanced functions.

The query_graph component serves as the read-only Cypher query engine for the DeusData/codebase-memory-mcp repository, enabling developers to navigate code relationships without mutating the underlying graph. Understanding which Cypher query features are supported versus unsupported ensures you write compatible queries that execute against the cbm_cypher_parse and cbm_cypher_execute functions. This guide derives its technical specifications directly from the test suite in tests/test_cypher.c and the parser implementation in cypher/cypher.c.

Supported Cypher Query Features

Pattern Matching with MATCH Clauses

The engine supports MATCH clauses for node patterns with optional labels and inline property maps. Variable names and label filters work as expected.

MATCH (f:Function)

Node patterns can include properties directly in the pattern:

MATCH (f:Function {name: "Foo"})

Relationship Patterns and Directionality

You can specify relationship direction using ->, <-, or undirected -. The parser handles single or multiple relationship types separated by the pipe operator |.

MATCH (f)-[:CALLS]->(g)
MATCH (f)-[:CALLS|HTTP_CALLS]->(g)

Variable-Length Relationships

The engine supports variable-length relationships using the * operator, including bounded ranges.

MATCH (f)-[:CALLS*1..3]->(g)
MATCH (f)-[:DEPENDS*]->(g)

WHERE Clause Filtering

The WHERE clause supports equality checks, regular expressions with =~, the CONTAINS and STARTS WITH predicates, and logical AND operators.

MATCH (f:Function)
WHERE f.name = "Foo" AND f.path =~ "/src/.*"
RETURN f

RETURN Clause and Aggregations

The RETURN clause supports property projections, aliases using AS, DISTINCT, ORDER BY, and LIMIT. The only aggregation function currently implemented is COUNT.

MATCH (f:Function)-[:CALLS]->(g)
RETURN f.name, COUNT(g) AS call_count
ORDER BY call_count DESC
LIMIT 5

Unsupported Cypher Query Features

Set Operations and Subqueries

The engine explicitly rejects UNION and UNION ALL operations. As evidenced in tests/test_cypher.c, injection attempts using UNION SELECT are blocked to prevent query manipulation. Subqueries using CALL or nested MATCH statements are not supported.

Graph Mutation Commands

As a read-only engine, QueryGraph does not implement CREATE, MERGE, DELETE, or SET clauses. Any attempt to mutate the graph structure or node properties will result in a parse error.

Advanced Functions and Pattern Comprehensions

The engine lacks support for path variables, pattern comprehensions, and OPTIONAL MATCH clauses. Additionally, aggregation functions beyond COUNT—such as SUM, AVG, MIN, and MAX—are not implemented. Advanced string functions like ENDS WITH or TRIM are also unavailable.

Implementation Architecture

The supported feature set is enforced by the parser defined in cypher/cypher.h and implemented in cypher/cypher.c. The cbm_cypher_parse function tokenizes input and builds an AST limited to the constructs above, while cbm_cypher_execute runs the read-only evaluation against the in-memory code graph. The comprehensive test suite in tests/test_cypher.c serves as the canonical specification, with each test case demonstrating both valid syntax acceptance and strict rejection of unsupported operations.

Summary

• The QueryGraph engine supports MATCH, WHERE, RETURN, and COUNT for read-only graph traversal.
• Relationship patterns support directionality, multiple types, and variable-length paths.
• Filtering works with equality, regex, CONTAINS, STARTS WITH, and logical AND.
• UNION, subqueries, mutations (CREATE, DELETE, SET), and advanced aggregations are explicitly unsupported.
• Reference tests/test_cypher.c for the definitive syntax boundary and cypher/cypher.c for implementation details.

Frequently Asked Questions

Does QueryGraph support the UNION clause in Cypher queries?

No. The parser explicitly rejects UNION operations to prevent query injection attacks and because the engine is designed for simple read-only traversal rather than set-based result combination. The test suite in tests/test_cypher.c validates that UNION injection attempts are properly blocked.

Can I use CREATE or MERGE to modify the code graph?

No. QueryGraph is strictly read-only. Implementation files cypher/cypher.c and cypher/cypher.h expose only cbm_cypher_parse and cbm_cypher_execute functions that lack mutation capabilities, and the test suite confirms that graph modification commands are not recognized by the parser.

What aggregation functions are available besides COUNT?

Only COUNT is supported. The test expectations in tests/test_cypher.c demonstrate COUNT usage with aliases, but functions like SUM, AVG, MIN, and MAX are not implemented in the current parser grammar.

Are variable-length relationships with unbounded depth supported?

Yes. You can use the * operator without bounds (e.g., -[:CALLS*]->) or specify ranges like *1..3. The parser handles these patterns as documented in the test cases for relationship traversal against the code graph.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}