Cypher API

9.1 Cypher

When authentication is disabled, no Authorization header is required and credentials are not evaluated; when enabled, Basic (standard RFC 4648 Base64) or Bearer tokens are supported (requests without credentials return 401), and queries execute under the caller’s verified permissions. On 1.2.0 to 1.7.0, an Authorization header was always required even without authentication.

9.1.1 Sending a cypher statement (GET) to HugeGraphServer for synchronous execution

Method & Url

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

Params

Path parameters

• graphspace: Graphspace name
• graph: Graph name

Query parameters

• cypher: Cypher statement

Example

1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugecypher1/cypher?cypher=match(n:person) return n.name as name order by n.name limit 1

Response Status

1200

Response Body

 1{
 2    "requestId": "766b9f48-2f10-40d9-951a-3027d0748ab7",
 3    "status": {
 4        "message": "",
 5        "code": 200,
 6        "attributes": {
 7        }
 8    },
 9    "result": {
10        "data": [
11            {
12                "name": "hello"
13            }
14        ],
15        "meta": {
16        }
17    }
18}

9.1.2 Sending a cypher statement (POST raw text) to HugeGraphServer for synchronous execution

Method & Url

1POST /graphspaces/{graphspace}/graphs/{graph}/cypher

Params

Path parameters

• graphspace: Graphspace name
• graph: Graph name

Body

{cypher}

• cypher: Cypher statement

Note:

The request body contains a raw Cypher string (a JSON object body is also accepted; see 9.1.3). However, because the server endpoint uses @Consumes(APPLICATION_JSON), requests must include -H "Content-Type: application/json" (requests sent with text/plain are rejected with HTTP 415).

Example

1curl -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugecypher1/cypher \
2  -H "Authorization: Bearer $TOKEN" \
3  -H "Content-Type: application/json" \
4  -d 'match(n:person) return n.name as name order by n.name limit 1'

Response Status

1200

Response Body

 1{
 2    "requestId": "f096bee0-e249-498f-b5a3-ea684fc84f57",
 3    "status": {
 4        "message": "",
 5        "code": 200,
 6        "attributes": {
 7        }
 8    },
 9    "result": {
10        "data": [
11            {
12                "name": "hello"
13            }
14        ],
15        "meta": {
16        }
17    }
18}

9.1.3 Sending a parameterized cypher statement (POST JSON, recommended) to HugeGraphServer for synchronous execution

Method & Url

1POST /graphspaces/{graphspace}/graphs/{graph}/cypher

Params

Path parameters

• graphspace: Graphspace name
• graph: Graph name

Body

1{
2    "cypher": "match(n:person) where n.name = $name return n.name as name order by n.name limit 1",
3    "parameters": {
4        "name": "hello"
5    }
6}

• cypher: Cypher statement (reference bound parameters using $param)
• parameters: Parameter map (JSON object, up to 16 top-level keys; group additional properties into a nested Map)

Example

1curl -X POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugecypher1/cypher \
2  -H "Content-Type: application/json" \
3  -d '{"cypher":"match(n:person) where n.name = $name return n.name as name order by n.name limit 1","parameters":{"name":"hello"}}'

Response Status

1200

Response Body

 1{
 2    "requestId": "f096bee0-e249-498f-b5a3-ea684fc84f57",
 3    "status": {
 4        "message": "",
 5        "code": 200,
 6        "attributes": {
 7        }
 8    },
 9    "result": {
10        "data": [
11            {
12                "name": "hello"
13            }
14        ],
15        "meta": {
16        }
17    }
18}

9.1.4 Cypher Error Response Envelope and Error Codes

When query submission, translation, or execution fails inside the Cypher processing pipeline, HugeGraphServer returns a Gremlin-compatible response envelope with HTTP status 200 and status.code = 400. Structured error details are provided under status.attributes.errors.

Error Response Structure

Each entry in status.attributes.errors contains:

• code: Stable error code string.
• message: Detailed failure message from the translator or execution engine (wording is not a frozen contract).
• hint: Actionable guidance to resolve the issue (empty string when no specific hint is available).

 1{
 2  "requestId": "example-request-id",
 3  "status": {
 4    "message": "Expected exactly one statement per query but got: 2",
 5    "code": 400,
 6    "attributes": {
 7      "errors": [
 8        {
 9          "code": "HugeGraph.Cypher.SyntaxError",
10          "message": "Expected exactly one statement per query but got: 2",
11          "hint": "Submit exactly one Cypher statement per request"
12        }
13      ]
14    }
15  },
16  "result": {
17    "data": null,
18    "meta": {}
19  }
20}

Error Codes

• SyntaxError: Triggered by parser syntax rejections, unknown functions, semantic errors with position offsets, multiple statements per request, or variables referenced without prior definition in MATCH, UNWIND, or WITH.
• ExecutionError: Triggered by undefined vertex/edge labels, property keys, or index labels. Also serves as the fallback for unclassified translation or runtime failures; it does not imply traversal execution actually started.
• UnsupportedFeature: Triggered by clauses, patterns, property types, or predicates unsupported by the translator.