HugeGraph Cypher

Overview

HugeGraph supports Cypher, the declarative graph query language originally created by Neo4j and standardized as openCypher. While Gremlin is an imperative traversal language, Cypher lets you describe the graph pattern you want (MATCH, WHERE, RETURN) and lets the engine decide how to execute it.

HugeGraph supports the openCypher 9 syntax subset, parsing declarative pattern queries directly and bridging them seamlessly to the underlying TinkerPop graph traversal engine. For complete coverage and boundaries, see Cypher Compatibility.

When to use Cypher vs Gremlin

Use Cypher when	Use Gremlin when
You are migrating from Neo4j or already know Cypher	You need the full HugeGraph feature surface
You want declarative pattern matching (`MATCH (a)-[:KNOWS]->(b)`)	You need fine-grained traversal control, custom steps, or lambdas
Your queries are read-mostly patterns and projections	You need graph algorithms, OLAP, or features Cypher does not expose

For anything Cypher cannot express, the equivalent Gremlin query always works — examples below show both.

Calling the Cypher API

Cypher statements are submitted to the HugeGraph Server through the REST endpoint:

1GET  /graphspaces/{graphspace}/graphs/{graph}/cypher?cypher={statement}
2POST /graphspaces/{graphspace}/graphs/{graph}/cypher

When server authentication is disabled, no Authorization header is required; when authentication is enabled, standard Basic (RFC 4648 Base64, e.g. curl -u) or Bearer <token> credentials are supported. See the Cypher REST API reference for the full request and response format.

Example:

1curl -H "Authorization: Bearer $TOKEN" \
2  "http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/cypher?cypher=MATCH%20(n:person)%20RETURN%20n.name%20LIMIT%2010"

From the Java client, use CypherManager (see hugegraph-client):

1ResultSet resultSet = hugeClient.cypher().execute("MATCH (n:person) RETURN n.name LIMIT 10");

Basic examples

The examples below assume a graph with person vertices (name, age, city properties) and knows edges. Before running them, note:

Property predicates in WHERE (such as WHERE n.age > 30) require covering indexes (e.g. a RANGE index on person.age).
On schemas with non-nullable properties or PRIMARY_KEY strategy, create statements must provide required attributes and primary keys; create vertices with complete properties separately before creating connecting edges.

Read — MATCH / WHERE / RETURN

1// All persons named "marko"
2MATCH (n:person) WHERE n.name = 'marko' RETURN n

1// Projection with ordering and limit
2MATCH (n:person)
3WHERE n.age > 30
4RETURN n.name AS name, n.age AS age
5ORDER BY age DESC
6LIMIT 10

1// Relationship pattern
2MATCH (a:person)-[:knows]->(b:person)
3WHERE a.name = 'marko'
4RETURN b.name AS friend

Create — CREATE

1// Create a vertex
2CREATE (n:person {name: 'alice', age: 32, city: 'beijing'})

1// Create two vertices, then an edge between them (send each statement as its own request)
2CREATE (:person {name: 'bob'})
3CREATE (:person {name: 'carol'})
4MATCH (a:person), (b:person)
5WHERE a.name = 'bob' AND b.name = 'carol'
6CREATE (a)-[:knows]->(b)

Update — SET / REMOVE

1MATCH (n:person) WHERE n.name = 'alice'
2SET n.age = 33
3REMOVE n.city

Delete — DELETE / DETACH DELETE

1// Delete an edge
2MATCH (a:person)-[r:knows]->(b:person)
3WHERE a.name = 'bob' AND b.name = 'carol'
4DELETE r

1// Delete a vertex and all its edges
2MATCH (n:person) WHERE n.name = 'alice'
3DETACH DELETE n

Aggregation

1// Total count
2MATCH (n:person) RETURN count(n) AS total

1// Grouped count
2MATCH (n:person) RETURN n.city AS city, count(*) AS cnt ORDER BY cnt DESC

Gremlin equivalents

Every Cypher statement is translated to Gremlin internally. When a Cypher feature is unsupported, write the traversal directly:

Cypher	Gremlin equivalent
`MATCH (n:person) WHERE n.name='marko' RETURN n`	`g.V().hasLabel('person').has('name','marko')`
`MATCH (a)-[:knows]->(b) RETURN b`	`g.V().out('knows')`
`CREATE (n:person {name:'x'})`	`g.addV('person').property('name','x')`
`MATCH (n) DETACH DELETE n`	`g.V().drop()`
`MATCH (n:person) RETURN count(n)`	`g.V().hasLabel('person').count()`

Tip: You can inspect generated underlying Gremlin traversals via EXPLAIN MATCH (n:person) RETURN n (in the translation field of the response) to draft equivalent traversals. PROFILE is not supported.

Limitations

Parameterized query rules: Parameter bindings are supported via JSON request bodies ({"cypher": "...", "parameters": {...}}, up to 16 top-level parameters; group additional properties into a nested Map and reference fields explicitly). Referencing an undeclared $param results in an execution error; explicit null is supported.
Partial clause coverage: Certain advanced openCypher constructs (such as map projections and complex functions) are currently unsupported and fail during parsing and validation.
No CALL procedures: Graph algorithms (shortest path, k-out, personalrank, etc.) are available via the traverser REST APIs or Gremlin instead of Cypher CALL procedures.
Single statement per request: Multi-statement scripts are not supported; submit one statement per call.

When a statement fails validation or execution, the server returns structured error details under status.attributes.errors with code, message, and hint. The Gremlin equivalent is the recommended fallback.