Skip to content

Graphs API

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

6.1 Graphs

Important Reminder: Since HugeGraph 1.7.0, dynamic graph creation must enable authentication mode. For non-authentication mode, please refer to Graph Configuration File to statically create graphs through configuration files.

6.1.1 List all graphs in the graphspace

Params

Path parameters

  • graphspace: Graphspace name
Method & Url
GET http://localhost:8080/graphspaces/DEFAULT/graphs
Response Status
200
Response Body
{
  "graphs": [
    "hugegraph",
    "hugegraph1"
  ]
}

6.1.2 Get details of the graph

Params

Path parameters

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

6.1.3 Clear all data of a graph, include: schema, vertex, edge and index, This operation requires administrator privileges

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
DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_message=I%27m+sure+to+delete+all+data
Response Status
204

6.1.4 Clone graph, this operation requires administrator privileges

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
POST 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)

{
  "gremlin.graph": "org.apache.hugegraph.HugeFactory",
  "backend": "rocksdb",
  "serializer": "binary",
  "store": "cloneGraph",
  "rocksdb.data_path": "./rks-data-xx",
  "rocksdb.wal_path": "./rks-data-xx"
}

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
201
Response Body
{
    "name": "cloneGraph",
    "nickname": "cloneGraph",
    "backend": "rocksdb",
    "description": ""
}

6.1.5 Create graph, this operation requires administrator privileges

Params

Path parameters

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

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

gremlin.graph Configuration:

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

Note!!

  1. In version 1.7.0, dynamic graph creation would cause a NPE. This issue has been fixed in PR#2912. The current master version and versions after 1.7.0 do not have this problem.
  2. If the backend is hstore, ensure HugeGraph-Server is properly configured with PD, see HStore Configuration. On 1.7.0 and earlier the request body also had to set "task.scheduler_type": "distributed". That key is now deprecated and ignored: the scheduler is selected from the backend type, hstore uses the distributed scheduler and other backends use the local one.

Optional fields and their defaults:

  • gremlin.graph defaults to org.apache.hugegraph.HugeFactory
  • backend defaults to hstore when the server runs in PD mode, and to rocksdb otherwise
  • serializer defaults to binary
  • store defaults to the graph name
  • nickname sets a display name for the graph, it must be unique inside the graphspace
  • schema names a schema template to initialize the graph with, it is stored as schema.init_template
  • description is returned as-is in the response

RocksDB Example:

{
  "gremlin.graph": "org.apache.hugegraph.auth.HugeFactoryAuthProxy",
  "backend": "rocksdb",
  "serializer": "binary",
  "store": "hugegraph2",
  "rocksdb.data_path": "./rks-data-xx",
  "rocksdb.wal_path": "./rks-data-xx"
}

HStore Example:

{
  "gremlin.graph": "org.apache.hugegraph.auth.HugeFactoryAuthProxy",
  "backend": "hstore",
  "serializer": "binary",
  "store": "hugegraph2",
  "pd.peers": "127.0.0.1:8686"
}

Note: The data/wal_path can’t be the same as the existing graph (use separate directories)

Response Status
201
Response Body
{
  "name": "hugegraph2",
  "nickname": "hugegraph2",
  "backend": "rocksdb",
  "description": ""
}

6.1.6 Delete graph and its data

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
DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/graphA?confirm_message=I%27m%20sure%20to%20drop%20the%20graph
Response Status
204

Note: For HugeGraph 1.5.0 and earlier versions, if you need to create or drop a graph, please still use the legacy text/plain (properties) style request body instead of JSON.

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
GET http://localhost:8080/graphspaces/DEFAULT/graphs/profile
Response Status
200
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.

[
  {
    "backend": "rocksdb",
    "serializer": "binary",
    "store": "hugegraph",
    "name": "hugegraph",
    "nickname": "hugegraph",
    "graphspace_nickname": "DEFAULT",
    "default": true,
    "default_update_time": "2024-05-01 12:30:00",
    "create_time": "2024-05-01 12:00:00"
  }
]

6.1.8 Update the nickname of a graph, this operation requires administrator privileges

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
PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph
Request Body
{
  "action": "update",
  "update": {
    "name": "hugegraph",
    "nickname": "MyGraph"
  }
}
Response Status
200
Response Body
{
  "hugegraph": "updated"
}

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
POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default
Response Status
200
Response Body
{
  "default_graph": [
    "hugegraph"
  ]
}
Unset a default graph
Method & Url
DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/default
Response Status
200
Response Body
{
  "default_graph": []
}
Get the default graphs
Method & Url
GET http://localhost:8080/graphspaces/DEFAULT/graphs/default
Response Status
200
Response Body
{
  "default_graph": [
    "hugegraph"
  ]
}

6.1.10 Reload the graphs of the graphspace

Reloads the graphs the server holds, which is useful after the graph configuration has changed outside the server.

Params

Path parameters

  • graphspace: Graphspace name

Request parameters

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

6.2 Conf

6.2.1 Get configuration for a graph, This operation requires administrator privileges

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/conf
Response Status
200
Response Body
# gremlin entrence to create graph
gremlin.graph=org.apache.hugegraph.HugeFactory
# cache config
#schema.cache_capacity=1048576
#graph.cache_capacity=10485760
#graph.cache_expire=600

# schema illegal name template
#schema.illegal_name_regex=\s+|~.*

#vertex.default_label=vertex

backend=rocksdb
serializer=binary

store=hugegraph
...=

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

Params

Path parameters

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

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

6.3.2 Modify graph mode. This operation requires administrator privileges

Params

Path parameters

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

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

Response Status
200
Response Body
{
  "mode": "RESTORING"
}

6.3.3 Get graph’s read mode

Params

Path parameters

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

6.3.4 Modify graph’s read mode. This operation requires administrator privileges

Params

Path parameters

  • graphspace: Graphspace name
  • graph: Graph name
Method & Url
PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode
Request Body
"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
200
Response Body
{
  "graph_read_mode": "OLTP_ONLY"
}

6.4 Snapshot

6.4.1 Create a snapshot

Params

Path parameters

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

6.4.2 Resume a snapshot

Params

Path parameters

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

6.5 Compact

6.5.1 Manually compact graph, This operation requires administrator privileges

Params

Path parameters

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

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

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

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

{
  "default": [
    "127.0.0.1:8281",
    "127.0.0.1:8282",
    "127.0.0.1:8283"
  ]
}

6.6.2 Get the leader of a raft group

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

6.6.3 Transfer the leadership of a raft group

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

6.6.4 Set the leader of a raft group

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

6.6.5 Add a peer to a raft group

This schedules an asynchronous task, see Task API.

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

6.6.6 Remove a peer from a raft group

This schedules an asynchronous task, see Task API.

Method & Url
POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/raft/remove_peer?endpoint=127.0.0.1:8284
Response Status
200
Response Body
{
  "task_id": 2
}
Last modified 2026-09-06 · doc(server): sync server-api with master (#490) (f001c1d7f)