Skip to content

VertexLabel API

VertexLabel REST API: Define vertex types, ID strategies, and associated properties that determine vertex structure and constraints.

1.3 VertexLabel

Assuming that the PropertyKeys listed in 1.1.3 have already been created.

Params Description:

  • id: The ID value of the vertex type.
  • name: The name of the vertex type, required.
  • id_strategy: The ID strategy for the vertex type, including primary key ID, auto-generated, custom string, custom number, custom UUID. The default strategy is primary key ID.
  • properties: The property types associated with the vertex type.
  • primary_keys: The primary key properties. This field must have a value when the ID strategy is PRIMARY_KEY, and must be empty for other ID strategies.
  • enable_label_index: Whether to enable label indexing. It is disabled by default.
  • index_names: The indexes created for the vertex type. See details in section 3.4.
  • nullable_keys: Nullable properties.
  • user_data: Setting the common information of the vertex type, similar to the property type.

1.3.1 Create a VertexLabel

Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels
Request Body
 1{
 2    "name": "person",
 3    "id_strategy": "DEFAULT",
 4    "properties": [
 5        "name",
 6        "age"
 7    ],
 8    "primary_keys": [
 9        "name"
10    ],
11    "nullable_keys": [],
12    "enable_label_index": true
13}
Response Status
1201
Response Body
 1{
 2    "id": 1,
 3    "primary_keys": [
 4        "name"
 5    ],
 6    "id_strategy": "PRIMARY_KEY",
 7    "name": "person2",
 8    "index_names": [
 9    ],
10    "properties": [
11        "name",
12        "age"
13    ],
14    "nullable_keys": [
15    ],
16    "enable_label_index": true,
17    "user_data": {}
18}

Starting from version v0.11.2, hugegraph-server supports Time-to-Live (TTL) functionality for vertices. The TTL for vertices is set through VertexLabel. For example, if you want the vertices of type “person” to have a lifespan of one day, you need to set the TTL field to 86400000 (in milliseconds) when creating the “person” VertexLabel.

 1{
 2    "name": "person",
 3    "id_strategy": "DEFAULT",
 4    "properties": [
 5        "name",
 6        "age"
 7    ],
 8    "primary_keys": [
 9        "name"
10    ],
11    "nullable_keys": [],
12    "ttl": 86400000,
13    "enable_label_index": true
14}

Additionally, if the vertex has a property called “createdTime” and you want to use it as the starting point for calculating the vertex’s lifespan, you can set the ttl_start_time field in the VertexLabel. For example, if the “person” VertexLabel has a property called “createdTime” of type Date, and you want the vertices of type “person” to live for one day starting from the creation time, the Request Body for creating the “person” VertexLabel would be as follows:

 1{
 2    "name": "person",
 3    "id_strategy": "DEFAULT",
 4    "properties": [
 5        "name",
 6        "age",
 7        "createdTime"
 8    ],
 9    "primary_keys": [
10        "name"
11    ],
12    "nullable_keys": [],
13    "ttl": 86400000,
14    "ttl_start_time": "createdTime",
15    "enable_label_index": true
16}

1.3.2 Add properties or userdata to an existing VertexLabel, or remove userdata (removing properties is currently not supported)

Params
  • action: Indicates whether the current action is to add or remove. Possible values are append (add) and eliminate (remove).
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels/person?action=append
Request Body
 1{
 2    "name": "person",
 3    "properties": [
 4        "city"
 5    ],
 6    "nullable_keys": ["city"],
 7    "user_data": {
 8        "super": "animal"
 9    }
10}
Response Status
1200
Response Body
 1{
 2    "id": 1,
 3    "primary_keys": [
 4        "name"
 5    ],
 6    "id_strategy": "PRIMARY_KEY",
 7    "name": "person",
 8    "index_names": [
 9    ],
10    "properties": [
11        "city",
12        "name",
13        "age"
14    ],
15    "nullable_keys": [
16        "city"
17    ],
18    "enable_label_index": true,
19    "user_data": {
20        "super": "animal"
21    }
22}

1.3.3 Get all VertexLabels

Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels
Response Status
1200
Response Body
 1{
 2    "vertexlabels": [
 3        {
 4            "id": 1,
 5            "primary_keys": [
 6                "name"
 7            ],
 8            "id_strategy": "PRIMARY_KEY",
 9            "name": "person",
10            "index_names": [
11            ],
12            "properties": [
13                "city",
14                "name",
15                "age"
16            ],
17            "nullable_keys": [
18                "city"
19            ],
20            "enable_label_index": true,
21            "user_data": {
22                "super": "animal"
23            }
24        },
25        {
26            "id": 2,
27            "primary_keys": [
28                "name"
29            ],
30            "id_strategy": "PRIMARY_KEY",
31            "name": "software",
32            "index_names": [
33            ],
34            "properties": [
35                "price",
36                "name",
37                "lang"
38            ],
39            "nullable_keys": [
40                "price"
41            ],
42            "enable_label_index": false,
43            "user_data": {}
44        }
45    ]
46}

1.3.4 Get VertexLabel by name

Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels/person
Response Status
1200
Response Body
 1{
 2    "id": 1,
 3    "primary_keys": [
 4        "name"
 5    ],
 6    "id_strategy": "PRIMARY_KEY",
 7    "name": "person",
 8    "index_names": [
 9    ],
10    "properties": [
11        "city",
12        "name",
13        "age"
14    ],
15    "nullable_keys": [
16        "city"
17    ],
18    "enable_label_index": true,
19    "user_data": {
20        "super": "animal"
21    }
22}

1.3.5 Delete VertexLabel by name

Deleting a VertexLabel will result in the removal of corresponding vertices and related index data. This operation will generate an asynchronous task.

Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels/person
Response Status
1202
Response Body
1{
2    "task_id": 1
3}

Note:

You can use GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/1 (where “1” is the task_id) to query the execution status of the asynchronous task. For more information, refer to the Asynchronous Task RESTful API.

Last modified 2026-10-12 · feat: upgrade OINK to 1.2.0 and improve docs UX (#514) (6181c8705)