Skip to content

rest-api-usage.md

Latest commit

 

History

History
60 lines (48 loc) · 2.89 KB

rest-api-usage.md

File metadata and controls

60 lines (48 loc) · 2.89 KB
Raw

REST paths and Gremlin requests

The REST listener uses paths such as /versions, /graphspaces and /gremlin. GET /apis lists resource paths and methods. Each url starts with / and includes the application path configured in restserver.url: a root installation lists /gremlin, while http://localhost:8080/hg lists /hg/gremlin. Call the listed path on the Server origin, without prepending /apis. A gateway's additional external prefix may still need to be retained.

Select a graph for synchronous Gremlin

GraphSpace names and graph names are case-sensitive. In a GraphSpace-enabled Server, the graph binding is <graphspace>-<graph>, and its traversal-source binding is __g_<graphspace>-<graph>. There is no implicit global g: a Server can host multiple graphs. Supply aliases for the names used by the query:

curl -X POST 'http://localhost:8080/gremlin' \
  -H 'Content-Type: application/json' \
  -d '{"gremlin":"g.V().count()","aliases":{"graph":"DEFAULT-hugegraph","g":"__g_DEFAULT-hugegraph"}}'

For an authenticated Server, also supply its configured HTTP authentication credentials, for example curl -u "$HG_USER:$HG_PASSWORD". Request bindings are query variables; they do not create graph bindings. An alias target must be an existing graph or traversal-source binding, rather than a Gremlin expression such as graph.traversal().

For a standalone legacy graph with no GraphSpace, use <graph> and __g_<graph> instead. The Java client builds the appropriate aliases from its configured GraphSpace and graph. Verify the configured names before treating a Could not rebind response as a graph-registration failure.

Run long queries as tasks

Synchronous execution has a configured timeout (evaluationTimeout in gremlin-server.yaml, 30000 milliseconds by default). Large label counts may scan substantial data even when a whole-graph count is fast. Use an asynchronous job when a query can exceed this limit:

curl -X POST 'http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/gremlin' \
  -H 'Content-Type: application/json' \
  -d '{"gremlin":"g.V().hasLabel(\"person\").count()"}'

The response contains task_id. Poll GET /graphspaces/DEFAULT/graphs/hugegraph/tasks/{task_id} until the task reports a terminal status, then inspect task_result. A running task has not completed its count. The job binds graph and g for the graph selected in its path. Use the same authentication as for the other Server APIs.

Create another graph

In PD mode, list graph spaces with GET /graphspaces. This listing is not supported in standalone mode; skip it and use GET /graphs to list configured graphs. Create a graph using POST /graphspaces/DEFAULT/graphs/{graph} with the graph configuration expected by the backend. POST /graphs is not the graph-creation contract. Creating a graph requires the corresponding Server permissions and backend configuration.