Gremlin API
8.1 Gremlin
For Gremlin traversal syntax, feature support, and upgrade notes, see the Gremlin Query Language guide.
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
Response Status
Response Body
8.1.2 Send a Gremlin statement to HugeGraphServer (POST), synchronously
Count vertices
Runnable request
/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
Response Body
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
Response Status
Response Body
Edge IDs, endpoints, and properties depend on current graph data.
8.1.3 Send a Gremlin statement to HugeGraphServer (POST), asynchronously
Method & Url
Query vertices
Request Body
Note:
Asynchronous requests cannot supply
aliases. Server automatically bindsgraphto the current graph andgto its traversal source, and adds the URL graph name as an alias forgraph. Scripts can usegraph,g, or that graph name.
Response Status
Response Body
Note:
Query task status with
GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/1, where1is the task ID. See the asynchronous task REST API.
Query edges
Request Body
Response Status
Response Body
Note:
Query task status with
GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2, where2is the task ID. See the asynchronous task REST API.