Skip to content

Gremlin API

Gremlin REST API: Execute Gremlin graph traversal language scripts via HTTP interface.

8.1 Gremlin

Note

For Gremlin traversal syntax, feature support, and upgrade notes, see the Gremlin Query Language guide.

Warning

Use native query APIs safely in production

The flexibility of graph query languages such as Gremlin and Cypher can introduce security risks. Do not expose native query endpoints directly to the public network. In production, enable authentication and authorization, maintain an IP allowlist, and grant minimum permissions. Standard Server configuration writes authentication-proxy authorization records to audit-*.log; retain these files and restrict read access. auth.audit_log_rate limits per-user output rather than serving as a dedicated audit-log on/off switch.

8.1.1 Send a Gremlin statement to HugeGraphServer (GET), synchronously

Params
  • gremlin: The Gremlin statement to execute on HugeGraphServer.
  • bindings: Parameter bindings with string keys and string or numeric values, similar to MySQL prepared statements, to speed up execution.
  • language: Statement language, defaulting to gremlin-groovy.
  • aliases: Adds aliases for existing variables in a graph space.

This REST proxy cannot reliably carry a JSON-braced aliases parameter in GET queries. Current graph binding names contain hyphens and cannot be used directly as Groovy variables. This GET example uses a simple expression; use the POST example with aliases below to select a graph for traversal.

Method & Url
1curl --compressed --get \
2  --data-urlencode "gremlin=1+1" \
3  http://127.0.0.1:8080/gremlin
Response Status
1200
Response Body
1{
2	"requestId": "<request_id>",
3	"status": {"message": "", "code": 200, "attributes": {}},
4	"result": {"data": [2], "meta": {}}
5}

8.1.2 Send a Gremlin statement to HugeGraphServer (POST), synchronously

Count vertices

Runnable request
1curl --compressed -sS -X POST http://127.0.0.1:8080/gremlin \
2  -H 'Content-Type: application/json' \
3  --data-binary '{"gremlin":"g.V().count()","aliases":{"g":"__g_DEFAULT-hugegraph"}}'

/gremlin is a top-level endpoint. The traversal source for graph hugegraph in graph space DEFAULT is __g_DEFAULT-hugegraph; aliases maps it to script variable g. Adjust the alias to the Server binding name for another graph or graph space. Batch responses can use gzip; curl --compressed decompresses them automatically.

Bindings are case-sensitive: <space>-<graph> selects the graph and __g_<space>-<graph> selects its traversal source. There is no implicit global g on a multi-graph Server. bindings supplies query variables; it does not register graphs, and an alias target cannot be the expression graph.traversal(). For a legacy standalone graph without a GraphSpace, the bindings are <graph> and __g_<graph>. For an authenticated Server, add its configured HTTP credentials, for example -u "$HG_USER:$HG_PASSWORD".

The default synchronous Gremlin evaluation timeout is 30000 milliseconds, configured by evaluationTimeout in gremlin-server.yaml. A whole-graph count can use a different execution path from a filtered label count. Do not infer label-scan latency from g.V().count(). Submit queries that may exceed the synchronous limit as Server asynchronous tasks (see section 8.1.3 below). Poll until task_status is terminal and inspect task_result; a task still marked running does not yet provide a completed count. A Hubble transport timeout is separate from the Server evaluation timeout; increasing only one does not remove the other.

Response Status
1200
Response Body
1{
2	"requestId": "<request_id>",
3	"status": {"message": "", "code": 200, "attributes": {}},
4	"result": {"data": [6], "meta": {}}
5}

Vertex count depends on current graph data; 6 above is an example result.

The response structure differs from the Vertex and Edge REST APIs; clients may need to parse it explicitly.

Query edges

Request Body
1{
2	"gremlin": "g.E().hasLabel('created').limit(1)",
3	"bindings": {},
4	"language": "gremlin-groovy",
5	"aliases": {
6		"g": "__g_DEFAULT-hugegraph"
7	}
8}
Response Status
1200
Response Body
 1{
 2	"requestId": "<request_id>",
 3	"status": {
 4		"message": "",
 5		"code": 200,
 6		"attributes": {}
 7	},
 8	"result": {
 9		"data": [{
10			"id": "<edge_id>",
11			"label": "created",
12			"type": "edge",
13			"outVLabel": "person",
14			"inVLabel": "software",
15			"outV": "<source_vertex_id>",
16			"inV": "<target_vertex_id>",
17			"properties": {
18				"weight": 0.4,
19				"date": "<date>"
20			}
21		}],
22		"meta": {}
23	}
24}

Edge IDs, endpoints, and properties depend on current graph data.

8.1.3 Send a Gremlin statement to HugeGraphServer (POST), asynchronously

Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/gremlin

Query vertices

Request Body
1{
2	"gremlin": "g.V('1:marko')",
3	"bindings": {},
4	"language": "gremlin-groovy",
5	"aliases": {}
6}

Note:

Asynchronous requests cannot supply aliases. Server automatically binds graph to the current graph and g to its traversal source, and adds the URL graph name as an alias for graph. Scripts can use graph, g, or that graph name.

Response Status
1201
Response Body
1{
2	"task_id": 1
3}

Note:

Query task status with GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/1, where 1 is the task ID. See the asynchronous task REST API.

Query edges

Request Body
1{
2	"gremlin": "g.E().hasLabel('created').limit(1)",
3	"bindings": {},
4	"language": "gremlin-groovy",
5	"aliases": {}
6}
Response Status
1201
Response Body
1{
2	"task_id": 2
3}

Note:

Query task status with GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2, where 2 is the task ID. See the asynchronous task REST API.