What Subset of openCypher Queries Does query_graph Support?

The query_graph function supports a read-only subset of openCypher that includes MATCH patterns, label alternation, WHERE clauses with property filters, RETURN, LIMIT, and ORDER BY, while explicitly rejecting all write operations such as CREATE, DELETE, SET, and MERGE.

The query_graph function serves as the primary interface for executing graph queries against the DeusData/codebase-memory-mcp repository's SQLite-backed knowledge graph. According to the parser implementation in src/cypher/cypher.c, this interface deliberately restricts the openCypher grammar to safe, read-only operations that translate directly into SQL SELECT statements. This design ensures that the underlying codebase representation remains immutable while allowing complex graph traversals and filtering.

Supported openCypher Features in query_graph

The implementation specifically enables pattern-based read operations. Any query submitted through the query_graph RPC must conform to the following supported constructs.

Pattern Matching with MATCH

The core of the supported subset is the MATCH clause for node and relationship patterns. The parser accepts simple node patterns, directed relationship arrows (-> and <-), and variable-length path specifications.

/* Simple node lookup */
query_graph("{\"query\":\"MATCH (n) RETURN n LIMIT 5\"}");

/* Directed relationship traversal */
query_graph("{\"query\":\"MATCH (a)-[:CALLS]->(b) RETURN a.name, b.name\"}");

Label Alternation and Type Testing

The parser supports openCypher label alternation syntax (:A|B|C) to match nodes with any of several labels. Additionally, WHERE clause label tests (WHERE n:Label) are implemented to filter nodes by type after initial matching.

According to the source in src/cypher/cypher.c, label alternation is handled around line 2959, while label testing in WHERE clauses appears near line 1149.

/* Label alternation: match Functions OR Methods */
query_graph("{\"query\":\"MATCH (n:Func|Method) RETURN n.name\"}");

/* Label test in WHERE clause */
query_graph("{\"query\":\"MATCH (n) WHERE n:Class RETURN n.name\"}");

Filtering with WHERE Clauses

The supported WHERE syntax includes property comparisons (equality, inequality, range), string matching operators (STARTS WITH, ENDS WITH, CONTAINS), and logical operators (AND, OR, NOT). These predicates translate into SQL WHERE conditions during query compilation.

/* Property and logical filtering */
query_graph("{\"query\":\"MATCH (n) WHERE n.lang = 'C' AND n.size > 100 RETURN n.name\"}");

/* String containment */
query_graph("{\"query\":\"MATCH (n) WHERE n.name CONTAINS 'Test' RETURN n\"}");

Result Shaping with RETURN, LIMIT, and ORDER BY

Queries can project specific properties via RETURN, sort results using ORDER BY (ascending or descending), and limit row counts with LIMIT. The implementation enforces a default maximum row limit of 100,000 to prevent resource exhaustion.

/* Ordering and limiting results */
query_graph("{\"query\":\"MATCH (n) RETURN n.name ORDER BY n.name DESC LIMIT 10\"}");

Multi-Hop Traversal

Variable-length path patterns are supported for multi-hop graph traversals, enabling queries that follow relationship chains across arbitrary depths (e.g., *1..3).

/* Multi-hop traversal: follow CALLS relationships 1 to 3 levels deep */
query_graph("{\"query\":\"MATCH (a)-[:CALLS*1..3]->(b) RETURN a.name, b.name\"}");

Explicitly Unsupported Cypher Features

The parser explicitly rejects write-oriented and schema-manipulation clauses. In src/cypher/cypher.c (lines 817-839), the code returns "unsupported Cypher feature" errors for the following operations:

• Data Modification: CREATE, DELETE, DETACH DELETE, SET, REMOVE, MERGE
• Procedure Calls: CALL, YIELD
• Control Flow: FOREACH
• Schema Operations: DROP, CONSTRAINT
• Advanced Matching: MANDATORY MATCH

Any query containing these clauses is rejected at the parsing stage before SQL generation occurs, ensuring the underlying SQLite database remains read-only through this interface.

Implementation Details and Source References

The query processing pipeline spans several key files:

• src/cypher/cypher.c: Contains the parser and translator. Lines 817-839 define the unsupported feature whitelist, while lines around 1149 and 2959 handle label testing and alternation respectively.
• src/mcp/mcp.c: Implements the query_graph RPC handler that receives JSON payloads, validates them, and invokes the Cypher engine.
• tests/test_incremental.c: Validates the supported subset through integration tests covering WHERE clause parsing, multi-hop traversal, and LIMIT enforcement.

Summary

• query_graph supports read-only openCypher: Only MATCH, WHERE, RETURN, LIMIT, and ORDER BY clauses are permitted.
• Label flexibility is included: Label alternation (:A|B) and WHERE clause label tests (WHERE n:Label) work as expected.
• All write operations are blocked: CREATE, DELETE, SET, MERGE, and schema modifications return parser errors.
• Multi-hop patterns work: Variable-length relationship patterns enable deep traversal queries.
• Safety limits are enforced: Results are capped at 100,000 rows by default to prevent resource exhaustion.

Frequently Asked Questions

Does query_graph support CREATE or DELETE operations?

No. According to the parser in src/cypher/cypher.c, both CREATE and DELETE clauses trigger an "unsupported Cypher feature" error. The interface is explicitly read-only to protect the integrity of the codebase knowledge graph.

Can I use openCypher functions like coalesce or size in query_graph?

Basic scalar functions such as coalesce and size are supported within RETURN and WHERE clauses, provided they operate on node or relationship properties. However, aggregate functions and user-defined functions accessed via CALL are blocked.

How does query_graph handle multi-hop relationship traversal?

The implementation supports variable-length path patterns using the *min..max syntax (e.g., [:CALLS*1..3]). These patterns translate into recursive SQL CTEs (Common Table Expressions) that traverse the relationship table to the specified depth.

What happens when I submit an unsupported Cypher clause to query_graph?

The parser in src/cypher/cypher.c performs early validation. If it encounters unsupported keywords like MERGE, SET, or CALL, it immediately returns an error response indicating the specific unsupported feature, and no SQL is executed against the database.

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