Cypher Compatibility

Scope and Overview

HugeGraph supports declarative openCypher 9 queries on top of the TinkerPop engine. This page summarizes supported request forms, parameter binding rules, syntax coverage, and behavioral boundaries.

The endpoint is /graphspaces/{graphspace}/graphs/{graph}/cypher. For query examples and Gremlin equivalents, see the HugeGraph Cypher Guide.

Request Forms and Parameter Bindings

Request Form	Content-Type	Description
`POST` (Recommended)	`application/json`	JSON body `{"cypher": "...", "parameters": {...}}`, supports parameter bindings
`POST`	`application/json`	Raw Cypher text string body (for unparameterized raw statements)
`GET`	—	Query parameter `?cypher=<URL-encoded statement>`, suitable for simple read queries

Example JSON parameterized request:

1{
2  "cypher": "MATCH (n:person) WHERE n.name = $name RETURN n.name",
3  "parameters": {"name": "marko"}
4}

Parameter Binding Rules

Parameter Format: The cypher field must be a non-empty string; parameters, if provided, must be a JSON object (omitted means an empty map).
Parameter Count: The top-level parameters object accepts at most 16 keys. For more properties, group them into a nested Map and reference fields explicitly in the statement (e.g. $props.name).
Unbound Variables: Referencing an undeclared $param raises an execution error and is rejected (explicit null is supported).
Reserved Marker: The exact string " cypher.null" (two leading spaces) is reserved by the engine as an internal sentinel and is rejected in parameter values.
Error Response: On validation or execution errors, the server returns HTTP 400 (or status.code 400 with null result), with structured details (code, message, hint) in status.attributes.errors.

Syntax and Feature Support Matrix

Category	Supported Features	Notes
Reads & Patterns	Label scans, equality and range predicates, boolean logic (AND/OR/NOT), directed 1-hop and multi-hop patterns, regex matching (`=~` full match)	Range comparisons require corresponding indexes
Results & Projection	Node and scalar projections, aliases (`AS`), property access, nested structures, relationship IDs, path expressions, null handling	Results are mapped to standard JSON structures
Aggregation & Ordering	`count`, `sum`, `min`, `max`, `avg`, `DISTINCT`, `ORDER BY`, `SKIP`, `LIMIT`	Mapped to underlying graph traversal steps
Data Writes	Vertex and edge `CREATE`, property `SET` / `REMOVE`, edge and vertex `DELETE` / `DETACH DELETE`	Create vertices with required properties before creating connecting edges

Write Constraints and Considerations

On schemas with non-nullable properties or PRIMARY_KEY strategy, the shorthand CREATE (a)-[:knows]->(b) fails due to non-null property validation (checkNonnullProperty) or missing primary keys. Execute vertex and edge creations separately, ensuring required vertex attributes are fully specified.

Unsupported Features

The following advanced features are currently unsupported; use Gremlin or the respective REST APIs:

Complex Clauses: MERGE, OPTIONAL MATCH, WITH, UNWIND, UNION, variable-length paths (*1..3);
Procedures: CALL dbms.* / CALL algo.* (use the Traverser REST API);
Schema Management: Cypher Schema DDL (use the Schema REST API);
Protocols & Drivers: Bolt protocol and drivers (use the HTTP REST API or HugeGraph Client).