# What Subset of openCypher Queries Does query_graph Support?

> Explore the openCypher query subset supported by query_graph. Understand limitations and capabilities for read-only operations like MATCH, WHERE, RETURN, LIMIT, and ORDER BY.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: api-reference
- Published: 2026-07-28

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.

```c
/* 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cypher/cypher.c), label alternation is handled around line 2959, while label testing in `WHERE` clauses appears near line 1149.

```c
/* 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.

```c
/* 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.

```c
/* 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`).

```c
/* 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.