Graph Query Languages

• 1: HugeGraph Gremlin
• 2: HugeGraph Cypher
• 3: Cypher Compatibility
• 4: Migrating from Neo4j
• 5: HugeGraph Examples

1 - HugeGraph Gremlin

Overview

HugeGraph supports Gremlin, a graph traversal query language of Apache TinkerPop3. While SQL is a query language for relational databases, Gremlin is a general-purpose query language for graph databases, enabling entity creation, property modification, deletion, and traversal queries.

For developers seeking declarative pattern matching (similar to SQL or Neo4j style), HugeGraph also supports Cypher.

TinkerPop Features

HugeGraph implements the TinkerPop framework, but not all TinkerPop features are implemented.

The table below lists the support status of various TinkerPop features in HugeGraph:

Graph Features

Vertex Features

Edge Features

Data Type Features

Gremlin Steps

HugeGraph supports all steps of Gremlin. For complete reference information about Gremlin, please refer to the Apache TinkerPop 3.8.1 official documentation.

2 - 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

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 authentication is enabled, Cypher requests require an Authorization header, supporting Basic (standard RFC 4648 Base64, e.g. curl -u) or Bearer <token> (requests without credentials return 401). When authentication is disabled, no Authorization header is required. 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:

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.

Further reading

• Cypher REST API reference
• Cypher compatibility notes
• Gremlin Query Language
• openCypher specification

3 - 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

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: A malformed request body returns HTTP 400 with the standard error body. Translation and execution errors return HTTP 200 with status.code 400 (and null result), with structured details (code, message, hint) in status.attributes.errors.

Syntax and Feature Support Matrix

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, 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).

4 - Migrating from Neo4j

Overview

For developers migrating from Neo4j or evaluating HugeGraph. HugeGraph supports openCypher declarative query syntax, but differences exist in the graph model, schema rules, parameter bindings, and indexing. For language usage and compatibility references, see HugeGraph Cypher and Cypher Compatibility.

What carries over directly

Habits you need to change

On PRIMARY_KEY labels, a UNIQUE index cannot include all primary-key fields (the server rejects it). To keep duplicate-rejection behavior, use a CUSTOMIZE_STRING label keyed on the Neo4j node id and add a UNIQUE index on the business key.

Suggested migration path

1. Inventory your queries: Review your application’s Cypher queries against the Cypher Compatibility Notes and Limitations to classify them into “works as-is”, “rewrite as Gremlin”, or “switch to a REST API”.

2. Create the schema first: define VertexLabel / EdgeLabel / PropertyKey and indexes through the schema API — HugeGraph requires the schema to exist before data is written.

3. Import data: the preferred path is Apache SeaTunnel 3.0.0 (released 2026-09-29) running Neo4j Source → HugeGraph Sink directly — no intermediate file export. REST remains fine for small datasets; the HugeGraph Loader stays an alternative for file-based imports. HugeGraph-side setup (environment, mappings, vertex/edge import examples) is covered in the Import Graph Data with SeaTunnel Sink guide.

   The SeaTunnel 3.0.0 connector docs document what to rely on:

   • Neo4j Source reads Cypher query results with explicit field schemas; 3.0.0 adds multi-table reads via tables_configs.
   • HugeGraph Sink is refactored in 3.0.0 with multi-mapping support — use the recommended mappings configuration for vertices/edges and follow its schema-creation behavior. By default, the Sink fails fast on errors (batch_failure_fallback=false and max_insert_errors=0). Record skipping is opt-in via batch_failure_fallback=true; if enabled, capture and reconcile skipped records and compare row counts before cutover.
   • HugeGraph Source is new in 3.0.0 (schema auto-discovery, multi-label/parallel reads), enabling HugeGraph export and migration workflows.

   Map Neo4j properties to HugeGraph PropertyKeys and pick the vertex ID strategy before importing. The Sink requires idFields for every vertex strategy other than AUTOMATIC, and edge mappings need separate sourceConfig.idFields and targetConfig.idFields, so the Neo4j query must return the field that carries the ID:

   • idStrategy = "PRIMARY_KEY": put a Neo4j business key in idFields and express edge endpoints through those same key fields.
   • idStrategy = "CUSTOMIZE_STRING": this alone does not keep the Neo4j node id. Make the Neo4j query return the id you want to keep as its own column (aliased, for example AS node_id), declare that field in the Source schema.fields (it must match the fields the query returns), set the vertex idFields to it, and map the matching edge endpoint fields in sourceConfig.idFields and targetConfig.idFields.

   Labels you pre-created in step 2 must use that same strategy — automatic creation does not convert an existing PRIMARY_KEY label into CUSTOMIZE_STRING. The Sink mappings configuration can create the missing PropertyKey, VertexLabel and EdgeLabel definitions, so those three parts of step 2 are optional when you use it; it does not create IndexLabels, so create any index your queries rely on (see the habits table above) separately. When SeaTunnel auto-creates EdgeLabels, omitting frequency defaults to SINGLE, which collapses parallel Neo4j relationships between the same endpoints into a single edge. To preserve parallel relationships, explicitly specify frequency = "MULTIPLE" and provide stable relationship discriminator fields as sortKeys in the edge mapping (HugeGraph uses sort keys to distinguish parallel edges). Load vertices before edges. We recommend thoroughly testing the import pipeline with a representative data sample before cutover.

4. Switch incrementally: keep queries Cypher supports, and rewrite unsupported constructs as Gremlin — the equivalents table shows the mapping.

Limitations at a glance

• Statements and parameters: Multi-statement scripts and CALL procedures are not supported; parameter binding supports up to 16 top-level parameters (pass a nested Map for additional properties).
• Unverified syntax: Advanced openCypher constructs not covered in the compatibility matrix are unverified and may fail during query validation; established limitations are listed above.
• Fallback path: Unsupported query constructs can typically be rewritten as Gremlin traversals — see the equivalents table; schema DDL and procedures map to REST APIs instead.

5 - HugeGraph Examples

1 Overview

This example uses the TitanDB Getting Started guide as a template to demonstrate how to use HugeGraph. By comparing HugeGraph and TitanDB, you can understand the differences between them.

1.1 Similarities and Differences between HugeGraph and TitanDB

Both HugeGraph and TitanDB are graph databases based on the Apache TinkerPop3 framework. They both support the Gremlin graph query language and share many similarities in terms of usage and interfaces. However, HugeGraph is a completely new design and development, characterized by its clear code structure, richer features, and more user-friendly interfaces.

Compared to TitanDB, HugeGraph’s main features are as follows:

• HugeGraph currently offers a comprehensive suite of tools, including HugeGraph-API, HugeGraph-Client, HugeGraph-Loader, HugeGraph-Studio, and HugeGraph-Spark. These components facilitate system integration, data loading, visual graph querying, Spark connectivity, and other functionalities.
• HugeGraph incorporates the concepts of Server and Client, allowing third-party systems to connect via multiple methods such as JAR references, clients, and APIs. In contrast, TitanDB only supports connections via JAR references.
• HugeGraph requires explicit schema definition, and all insertions and queries must pass strict schema validation. Implicit schema creation is not supported at the moment.
• HugeGraph makes full use of the characteristics of the underlying storage system to achieve efficient data access, whereas TitanDB ignores the differences of the backend with a unified Kv structure.
• HugeGraph’s update operations can be performed on-demand (e.g., updating a specific attribute), offering better performance. TitanDB uses a read-and-update approach for updates.
• Both VertexId and EdgeId in HugeGraph support concatenation, allowing for automatic deduplication and better query performance. In TitanDB, all IDs are auto-generated and require indexing for queries.

1.2 Character Relationship Graph

This example uses the Property Graph Model to describe the relationships between characters in Greek mythology, also known as the character relationship graph. The specific relationships are shown in the diagram below.

In the diagram, circular nodes represent entities (Vertices), arrows represent relationships (Edges), and the content in the boxes represents attributes.

There are two types of vertices in this graph: characters and locations, as shown in the table below:

There are six types of relationships: father, mother, brother, battled, lives, and pet. The details of these relationships are as follows:

An edge label can be linked to more than one pair of source and target vertex labels: call link(sourceLabel, targetLabel) once per pair when creating it. The deprecated sourceLabel() and targetLabel() builder methods accept only a single pair.

In this example, the original TitanDB’s monster, god, human, and demigod are all represented using the same vertex label: character in HugeGraph, with an additional type attribute to indicate the type of character. The edge labels remain consistent with the original TitanDB.

2 Graph Schema and Data Ingest Examples

HugeGraph requires explicit schema creation, which involves creating PropertyKeys, VertexLabels, and EdgeLabels in sequence. If indexing is needed, IndexLabels must also be created.

2.1 Graph Schema

The snippets assume a local Groovy script has opened HugeGraph as graph and set g = graph.traversal(). Start with the Gremlin Console local-mode example, whose scripts/example.groovy creates both variables. In a remote Console, g is a Server-side traversal-source alias and there is no local graph object; use the Schema REST API for remote schema creation.

 1import org.apache.tinkerpop.gremlin.structure.T
 2import org.apache.tinkerpop.gremlin.structure.Vertex
 3
 4schema = graph.schema()
 5g = graph.traversal()
 6
 7schema.propertyKey("name").asText().ifNotExist().create()
 8schema.propertyKey("age").asInt().ifNotExist().create()
 9schema.propertyKey("time").asInt().ifNotExist().create()
10schema.propertyKey("reason").asText().ifNotExist().create()
11schema.propertyKey("type").asText().ifNotExist().create()
12
13schema.vertexLabel("character").properties("name", "age", "type").primaryKeys("name").nullableKeys("age").ifNotExist().create()
14schema.vertexLabel("location").properties("name").primaryKeys("name").ifNotExist().create()
15
16schema.edgeLabel("father").link("character", "character").ifNotExist().create()
17schema.edgeLabel("mother").link("character", "character").ifNotExist().create()
18schema.edgeLabel("battled").link("character", "character").properties("time").ifNotExist().create()
19schema.edgeLabel("lives").link("character", "location").properties("reason").nullableKeys("reason").ifNotExist().create()
20schema.edgeLabel("pet").link("character", "character").ifNotExist().create()
21schema.edgeLabel("brother").link("character", "character").ifNotExist().create()

2.2 Graph Data

 1// add vertices
 2Vertex saturn = graph.addVertex(T.label, "character", "name", "saturn", "age", 10000, "type", "titan")
 3Vertex sky = graph.addVertex(T.label, "location", "name", "sky")
 4Vertex sea = graph.addVertex(T.label, "location", "name", "sea")
 5Vertex jupiter = graph.addVertex(T.label, "character", "name", "jupiter", "age", 5000, "type", "god")
 6Vertex neptune = graph.addVertex(T.label, "character", "name", "neptune", "age", 4500, "type", "god")
 7Vertex hercules = graph.addVertex(T.label, "character", "name", "hercules", "age", 30, "type", "demigod")
 8Vertex alcmene = graph.addVertex(T.label, "character", "name", "alcmene", "age", 45, "type", "human")
 9Vertex pluto = graph.addVertex(T.label, "character", "name", "pluto", "age", 4000, "type", "god")
10Vertex nemean = graph.addVertex(T.label, "character", "name", "nemean", "type", "monster")
11Vertex hydra = graph.addVertex(T.label, "character", "name", "hydra", "type", "monster")
12Vertex cerberus = graph.addVertex(T.label, "character", "name", "cerberus", "type", "monster")
13Vertex tartarus = graph.addVertex(T.label, "location", "name", "tartarus")
14
15// add edges
16jupiter.addEdge("father", saturn)
17jupiter.addEdge("lives", sky, "reason", "loves fresh breezes")
18jupiter.addEdge("brother", neptune)
19jupiter.addEdge("brother", pluto)
20neptune.addEdge("lives", sea, "reason", "loves waves")
21neptune.addEdge("brother", jupiter)
22neptune.addEdge("brother", pluto)
23hercules.addEdge("father", jupiter)
24hercules.addEdge("mother", alcmene)
25hercules.addEdge("battled", nemean, "time", 1)
26hercules.addEdge("battled", hydra, "time", 2)
27hercules.addEdge("battled", cerberus, "time", 12)
28pluto.addEdge("brother", jupiter)
29pluto.addEdge("brother", neptune)
30pluto.addEdge("lives", tartarus, "reason", "no fear of death")
31pluto.addEdge("pet", cerberus)
32cerberus.addEdge("lives", tartarus)
33
34graph.tx().commit()

2.3 Indices

HugeGraph by default automatically generates IDs. However, if a user specifies the primaryKeys field list for a VertexLabel through primaryKeys, the ID strategy for that VertexLabel will automatically switch to the primaryKeys strategy. Once the primaryKeys strategy is enabled, HugeGraph generates VertexId by concatenating vertexLabel+primaryKeys, which allows for automatic deduplication. Additionally, there is no need to create extra indexes to use the properties in primaryKeys for fast querying. For example, both “character” and “location” have the primaryKeys("name") attribute, so without creating additional indexes, vertices can be queried using g.V().hasLabel('character').has('name','hercules').

3 Graph Traversal Examples

3.1 Traversal Query

1. Find the grandfather of hercules

1g.V().hasLabel('character').has('name','hercules').out('father').out('father')

It can also be done using the repeat method:

1g.V().hasLabel('character').has('name','hercules').repeat(__.out('father')).times(2)

2. Find the name of Hercules’s father

1g.V().hasLabel('character').has('name','hercules').out('father').value('name')

3. Find the characters with age > 100

1g.V().hasLabel('character').has('age',gt(100))

4. Find who are pluto’s cohabitants

1g.V().hasLabel('character').has('name','pluto').out('lives').in('lives').values('name')

5. Find pluto can’t be his own cohabitant

1pluto = g.V().hasLabel('character').has('name', 'pluto')
2g.V(pluto).out('lives').in('lives').where(is(neq(pluto))).values('name')
3
4// use 'as'
5g.V().hasLabel('character').has('name', 'pluto').as('x').out('lives').in('lives').where(neq('x')).values('name')

6. Pluto’s Brothers

1pluto = g.V().hasLabel('character').has('name', 'pluto').next()
2// where do pluto's brothers live?
3g.V(pluto).out('brother').out('lives').values('name')
4
5// which brother lives in which place?
6g.V(pluto).out('brother').as('god').out('lives').as('place').select('god','place')
7
8// what is the name of the brother and the name of the place?
9g.V(pluto).out('brother').as('god').out('lives').as('place').select('god','place').by('name')

It is recommended to use HugeGraph-Hubble to execute the above code visually. Additionally, the code can be executed through various other methods such as HugeGraph-Client, HugeGraph-Api, GremlinConsole, and GremlinDriver.

3.2 Summary

HugeGraph currently supports Gremlin syntax, and users can implement various query requirements through Gremlin / REST-API.