Skip to content

Graphs API

Graphs REST API: Manage graph instance lifecycle including creating, querying, cloning, clearing, and deleting graph databases.

6.1 Graphs

Warning

In production, enable Server authentication and authorization, restrict graph management with an IP allowlist and minimum permissions, and retain audit-*.log audit records. Unauthenticated settings below are only for isolated local tests.

This page documents the Graphs API on current master. For historical paths and request bodies, use the 1.7 Graphs API or 1.5 Graphs API.

With authentication enabled, creation, cloning, deletion, clearing, display-name changes, graph-configuration reads, read-mode changes, and manual compaction require graph-space management permission (space); administrators can satisfy it through permission inheritance. Snapshot creation/restoration and data-mode changes allow graph-space managers or the graph owner. Listing, details, and data/read-mode queries use graph read permissions. Raft APIs additionally require graph-space membership.

6.1.1 List all graphs in the graphspace

Params

Path parameters

  • graphspace: Graphspace name
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs
Response Status
1200
Response Body
1{
2    "graphs": [
3        "hugegraph",
4        "hugegraph1"
5    ]
6}

6.1.2 Get details of the graph

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph
Response Status
1200
Response Body
1{
2    "name": "hugegraph",
3    "backend": "rocksdb"
4}

6.1.3 Clear all data of a graph, include: schema, vertex, edge and index

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name

Query parameters

Since emptying the graph is a dangerous operation, we have added parameters for confirmation to the API to avoid false calls by users:

  • confirm_message: default by I'm sure to delete all data
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_message=I%27m+sure+to+delete+all+data
Response Status
1204

6.1.4 Clone graph

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Name of the new graph to create

Query parameters

  • clone_graph_name: name of an existed graph. To clone from an existing graph, the user can choose to transfer the configuration file, which will replace the configuration in the existing graph
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_name=hugegraph
Request Body [Optional]

Clone a non-auth mode graph (set Content-Type: application/json)

1{
2  "gremlin.graph": "org.apache.hugegraph.HugeFactory",
3  "backend": "rocksdb",
4  "serializer": "binary",
5  "store": "cloneGraph",
6  "rocksdb.data_path": "./rks-data-xx",
7  "rocksdb.wal_path": "./rks-data-xx"
8}

Note:

  1. The data/wal_path can’t be the same as the existing graph (use separate directories)
  2. Replace “gremlin.graph=org.apache.hugegraph.auth.HugeFactoryAuthProxy” to enable auth mode
Response Status
1201
Response Body
1{
2    "name": "cloneGraph",
3    "nickname": "cloneGraph",
4    "backend": "rocksdb",
5    "description": ""
6}

6.1.5 Create graph

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx
Request Body

Create a graph (set Content-Type: application/json)

gremlin.graph Configuration:

  • Auth mode: "gremlin.graph": "org.apache.hugegraph.auth.HugeFactoryAuthProxy" (required in production)
  • Non-auth mode: "gremlin.graph": "org.apache.hugegraph.HugeFactory"

Note: For HStore, configure PD correctly in HugeGraph Server; see HStore configuration. The backend selects the scheduler: HStore uses the distributed scheduler; other backends use the local scheduler.

1{
2  "gremlin.graph": "org.apache.hugegraph.auth.HugeFactoryAuthProxy",
3  "backend": "rocksdb",
4  "serializer": "binary",
5  "store": "hugegraph",
6  "rocksdb.data_path": "./rks-data-xx",
7  "rocksdb.wal_path": "./rks-data-xx"
8}
Response Status
1201
Response Body
1{
2    "name": "hugegraph2",
3    "nickname": "hugegraph2",
4    "backend": "rocksdb",
5    "description": ""
6}

6.1.6 Delete graph and its data

Graph-space management permission (space) is required when authentication is enabled.

Stop writes and tasks on every Server that uses the graph before deletion, and keep them stopped during failures and retries. Do not recreate the same graph name until deletion has completed and been confirmed on every Server. Notifications are not a cluster-wide barrier.

On the deleting Server, scheduler shutdown fences new task admission and waits for actual executions, cancellation callbacks and transaction cleanup. If the configured task-drain wait times out (task.wait_timeout, seconds), deletion is refused before data, configuration or metadata removal; retry after the owners exit. Task admission stays closed after this refusal. To resume ordinary graph use before destructive cleanup, keep writes and task producers stopped; wait for all admitted tasks and cancellation cleanup to finish, then restart Server. A restart does not restore data or metadata already removed. Closing the scheduler alone retains persistent work that has not started.

Deletion is not transactional. A failure after destructive cleanup does not restore removed data or metadata. An uncertain owner or native-resource cleanup needs manual inspection; do not force-remove the scheduler or resume writes just because a task Future is done. In PD deployments with graph.load_from_local_config=true, if deletion is refused because the graph uses local configuration, removing its configuration file and restarting Server stops Server from loading the graph, but leaves its backend data in place.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name

Query parameters

Since deleting a graph is a dangerous operation, we have added parameters for confirmation to the API to avoid false calls by users:

  • confirm_message: default by I'm sure to drop the graph
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/graphA?confirm_message=I%27m%20sure%20to%20drop%20the%20graph
Response Status
1204

6.1.7 List the graphs of the graphspace with their configuration

Returns one entry per graph the current user can read, each carrying the graph configuration (keys that look like passwords, secrets, tokens, credentials or private keys are left out) plus the fields below. Graphs marked as default for the current user come first.

Params

Path parameters

  • graphspace: Graphspace name

Query parameters

  • prefix: Return only the graphs whose name or nickname starts with this prefix
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/profile
Response Status
1200
Response Body

default_update_time is only present when the graph is a default graph of the current user, and create_time only when the graph records one.

 1[
 2  {
 3    "backend": "rocksdb",
 4    "serializer": "binary",
 5    "store": "hugegraph",
 6    "name": "hugegraph",
 7    "nickname": "hugegraph",
 8    "graphspace_nickname": "DEFAULT",
 9    "default": true,
10    "default_update_time": "2024-05-01 12:30:00",
11    "create_time": "2024-05-01 12:00:00"
12  }
13]

6.1.8 Update the nickname of a graph

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name

Request parameters

  • action: Must be update
  • update: Container for the fields to update. name is required and must match the graph name in the path, nickname is the new display name and must be unique inside the graphspace.
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph
Request Body
1{
2  "action": "update",
3  "update": {
4    "name": "hugegraph",
5    "nickname": "MyGraph"
6  }
7}
Response Status
1200
Response Body
1{
2  "hugegraph": "updated"
3}

6.1.9 Manage the default graphs of the current user

A default graph is recorded per user, so the endpoints below act on behalf of the calling user. They need the authentication system, a server started in standalone mode without it answers 400 with GraphSpace management is not supported in standalone mode.

Set a graph as default
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default
Response Status
1200
Response Body
1{
2  "default_graph": [
3    "hugegraph"
4  ]
5}
Unset a default graph
Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default
Response Status
1200
Response Body
1{
2  "default_graph": []
3}
Get the default graphs
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/default
Response Status
1200
Response Body
1{
2  "default_graph": [
3    "hugegraph"
4  ]
5}

6.1.10 Reload the graphs of the graphspace

Apply graph configuration changes by restarting Server. Hot-reload recovery is deferred; do not use this endpoint for configuration maintenance. In the current non-PD path, reload invokes graph deletion and can clear backend data. Keep writes and tasks stopped until Server has restarted and the intended graphs have been verified. The request and response below document the API shape, not a maintenance or recovery guarantee.

Params

Path parameters

  • graphspace: Graphspace name

Request parameters

  • action: Must be reload
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage
Request Body
1{
2  "action": "reload"
3}
Response Status
1200
Response Body
1{
2  "graphs": "reloaded"
3}

6.2 Conf

6.2.1 Get configuration for a graph

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1GET
2http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/conf
Response Status
1200
Response Body
 1# gremlin entrence to create graph
 2gremlin.graph=org.apache.hugegraph.HugeFactory
 3# cache config
 4#schema.cache_capacity=1048576
 5#graph.cache_capacity=10485760
 6#graph.cache_expire=600
 7
 8# schema illegal name template
 9#schema.illegal_name_regex=\s+|~.*
10
11#vertex.default_label=vertex
12
13backend=rocksdb
14serializer=binary
15
16store=hugegraph
17...=

6.3 Mode

Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING

  • None mode is regular mode
    • Not allowed to create schema with specified id
    • Not support creating vertex with id for AUTOMATIC id strategy
  • LOADING mode used to load data via hugegraph-loader.
    • When adding vertices / edges, it is not checked whether the required attributes are passed in

Restore has two different modes: Restoring and Merging

  • Restoring mode is used to restore schema and graph data to a new graph.
    • Support create schema with specified id
    • Support create vertex with id for AUTOMATIC id strategy
  • Merging mode is used to merge schema and graph data to an existing graph.
    • Not allowed to create schema with specified id
    • Support create vertex with id for AUTOMATIC id strategy

Under normal circumstances, the graph mode is None. When you need to restore the graph, you need to temporarily modify the graph mode to Restoring or Merging as needed. When you complete the restore, change the graph mode to None.

6.3.1 Get graph mode

Graph read permission (space_member or the graph owner) is required when authentication is enabled.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode
Response Status
1200
Response Body
1{
2    "mode": "NONE"
3}

Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING

6.3.2 Modify graph mode.

Graph-space management permission (space) or graph ownership is required when authentication is enabled; administrators can satisfy it through permission inheritance.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode
Request Body
1"RESTORING"

Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING

While loading owners are active, this enum PUT rejects all mode changes, including "LOADING". Release the owners after their import workers stop.

Response Status
1200
Response Body
1{
2    "mode": "RESTORING"
3}

6.3.3 Get graph’s read mode

Graph read permission (space_member or the graph owner) is required when authentication is enabled.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode
Response Status
1200
Response Body
1{
2    "graph_read_mode": "ALL"
3}

6.3.4 Modify graph’s read mode.

Graph-space management permission (space) is required when authentication is enabled; administrators can satisfy it through permission inheritance.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode
Request Body
1"OLTP_ONLY"

Allowed read mode values are: ALL, OLTP_ONLY. The API rejects OLAP_ONLY with Graph-read-mode could be ALL or OLTP_ONLY.

Response Status
1200
Response Body
1{
2    "graph_read_mode": "OLTP_ONLY"
3}

6.3.5 LOADING ownership

Starting with HugeGraph 1.8.0, the Server provides the protocol 1 endpoints for LOADING ownership (requires a Server whose GET .../mode/owners returns protocol: 1 and a matching Loader; current master does not include it yet); Loader integration requires a matching 1.8.0 or newer client. Released packages, earlier 1.8 builds, and current master builds lack this protocol. Support for the LOADING enum alone does not imply support for it. With authentication enabled, both endpoints use the mode setter’s permissions: graph-space management (space) or graph ownership, with STATUS write authorization. Server binds the handle to the authenticated principal; a token grants no permission. Keep the same identity for acquire, release and retries.

1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners

The 200 capability response contains the graph-instance UUID, current nonnegative epoch, and state revision:

1{
2    "protocol": 1,
3    "instance": "<instance UUID>",
4    "epoch": 0,
5    "revision": 0
6}

Generate a new lowercase hyphenated UUID token for each import, retain the returned instance and epoch, and acquire with Content-Type: application/json:

1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners
1{
2    "action": "acquire",
3    "instance": "<instance UUID>",
4    "epoch": 0,
5    "token": "<import UUID>"
6}

An acquire succeeded only when the response returns 200 with state: "active", echoing protocol, instance, epoch, token, and mode: "LOADING". A 200 response with state: "released" means the handle is finished or was preemptively released; it does not grant ownership. In that case, stop and drain that import attempt, then start a new attempt with a fresh GET for instance and epoch and generate a new token. Release with action: "release" and the same handle; its response has state: "released" and the effective graph mode. Calling release before acquire is recorded and causes a subsequent acquire with that handle to return released. Keep one handle for retries; Server checks its principal, instance and epoch. A released handle cannot acquire again.

To clear orphaned handles after an abnormal exit (e.g. kill -9), an administrator can execute an explicit recovery request:

1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners
1{
2    "action": "recover",
3    "instance": "<instance UUID>",
4    "epoch": 0,
5    "revision": 0,
6    "confirm": "I'm sure all imports have stopped"
7}

Administrator recovery requires the global administrator role (admin). Callers must supply the current revision, instance, and epoch obtained from GET /mode/owners, plus the confirmation string confirm: "I'm sure all imports have stopped". If the provided revision does not match the Server’s current state, the request is rejected with HTTP 409 Conflict. On success, the Server clears all active owners, resets graph mode to NONE, and increments the epoch, returning HTTP 200 with state: "recovered" and mode: "NONE".

The first owner requires NONE. Other owners share owner-managed LOADING; the last release restores NONE. Manually set LOADING, RESTORING and MERGING are not adopted. While owners are active, the legacy enum PUT rejects mode changes.

This protects ordinary imports on one live Server graph instance, with the handle bound to its authenticated principal, instance and epoch. It provides no cross-Server coordination, data-write isolation or automatic expiry. Use a fixed direct Server endpoint and release after the import stops. The upgraded Loader falls back to old behavior only for an unsupported-route 404 from its ownership probe; other errors remain failures. Graph-source and restore imports retain their original enum-mode behavior. See Loader compatibility and recovery.

6.4 Snapshot

6.4.1 Create a snapshot

Graph-space management permission (space) or graph ownership is required when authentication is enabled; administrators can satisfy it through permission inheritance.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/snapshot_create
Response Status
1200
Response Body
1{
2    "hugegraph": "snapshot_created"
3}

6.4.2 Resume a snapshot

Graph-space management permission (space) or graph ownership is required when authentication is enabled; administrators can satisfy it through permission inheritance.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/snapshot_resume
Response Status
1200
Response Body
1{
2    "hugegraph": "snapshot_resumed"
3}

6.5 Compact

6.5.1 Manually compact graph

Graph-space management permission (space) is required when authentication is enabled; administrators can satisfy it through permission inheritance.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/compact
Response Status
1200
Response Body
1{
2    "nodes": 1,
3    "cluster_id": "local",
4    "servers": {
5        "local": "OK"
6    }
7}

6.6 Raft

These endpoints only work when the graph runs in raft mode, see the raft.mode option in Config Options. On a graph that does not, they answer 400 with Allowed <operation> operation only when working on raft mode.

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name

Query parameters

  • group: Raft group name, default is default
  • endpoint: Address of the peer, in the host:port form. Required by transfer_leader, set_leader, add_peer and remove_peer.

6.6.1 List the peers of a raft group

Graph-space membership (space_member) is required when authentication is enabled; administrators can satisfy it through permission inheritance.

Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/list_peers
Response Status
1200
Response Body

The key of the returned object is the raft group name.

1{
2  "default": [
3    "127.0.0.1:8281",
4    "127.0.0.1:8282",
5    "127.0.0.1:8283"
6  ]
7}

6.6.2 Get the leader of a raft group

Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/get_leader
Response Status
1200
Response Body
1{
2  "default": "127.0.0.1:8281"
3}

6.6.3 Transfer the leadership of a raft group

Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/transfer_leader?endpoint=127.0.0.1:8282
Response Status
1200
Response Body
1{
2  "default": "127.0.0.1:8282"
3}

6.6.4 Set the leader of a raft group

Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/set_leader?endpoint=127.0.0.1:8282
Response Status
1200
Response Body
1{
2  "default": "127.0.0.1:8282"
3}

6.6.5 Add a peer to a raft group

This schedules an asynchronous task, see Task API.

Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/add_peer?endpoint=127.0.0.1:8284
Response Status
1200
Response Body
1{
2  "task_id": 1
3}

6.6.6 Remove a peer from a raft group

This schedules an asynchronous task, see Task API.

Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/remove_peer?endpoint=127.0.0.1:8284
Response Status
1200
Response Body
1{
2  "task_id": 2
3}
Last modified 2026-10-17 · docs: explain loader mode ownership (#525) (b4f07d7c9)