Vertex API

2.1 Vertex

In vertex types, the Id strategy determines the type of the vertex Id, with the corresponding relationships as follows:

Id_Strategyid type
AUTOMATICnumber
PRIMARY_KEYstring
CUSTOMIZE_STRINGstring
CUSTOMIZE_NUMBERnumber
CUSTOMIZE_UUIDuuid

For the GET/PUT/DELETE API of a vertex, the id part in the URL should be passed as the id value with type information. This type information is indicated by whether the JSON string is enclosed in quotes, meaning:

  • When the id type is number, the id in the URL is without quotes, for example: xxx/vertices/123456.
  • When the id type is string, the id in the URL is enclosed in quotes, for example: xxx/vertices/"123456".

The next example requires first creating the graph schema from the following groovy script

  1. schema.propertyKey("name").asText().ifNotExist().create();
  2. schema.propertyKey("age").asInt().ifNotExist().create();
  3. schema.propertyKey("city").asText().ifNotExist().create();
  4. schema.propertyKey("weight").asDouble().ifNotExist().create();
  5. schema.propertyKey("lang").asText().ifNotExist().create();
  6. schema.propertyKey("price").asDouble().ifNotExist().create();
  7. schema.propertyKey("hobby").asText().valueList().ifNotExist().create();
  9. schema.vertexLabel("person").properties("name", "age", "city", "weight", "hobby").primaryKeys("name").nullableKeys("age", "city", "weight", "hobby").ifNotExist().create();
  10. schema.vertexLabel("software").properties("name", "lang", "price").primaryKeys("name").nullableKeys("lang", "price").ifNotExist().create();
  12. schema.indexLabel("personByAge").onV("person").by("age").range().ifNotExist().create();

2.1.1 Create a vertex

Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/graph/vertices
Request Body
  1. {
  2.     "label": "person",
  3.     "properties": {
  4.         "name": "marko",
  5.         "age": 29
  6.     }
  7. }
Response Status
  1. 201
Response Body
  1. {
  2.     "id": "1:marko",
  3.     "label": "person",
  4.     "type": "vertex",
  5.     "properties": {
  6.         "name": "marko",
  7.         "age": 29
  8.     }
  9. }

2.1.2 Create multiple vertices

Method & Url
  1. POST http://localhost:8080/graphs/hugegraph/graph/vertices/batch
Request Body
  1. [
  2.     {
  3.         "label": "person",
  4.         "properties": {
  5.             "name": "marko",
  6.             "age": 29
  7.         }
  8.     },
  9.     {
  10.         "label": "software",
  11.         "properties": {
  12.             "name": "ripple",
  13.             "lang": "java",
  14.             "price": 199
  15.         }
  16.     }
  17. ]
Response Status
  1. 201
Response Body
  1. [
  2.     "1:marko",
  3.     "2:ripple"
  4. ]

2.1.3 Update vertex properties

Method & Url
  1. PUT http://127.0.0.1:8080/graphs/hugegraph/graph/vertices/"1:marko"?action=append
Request Body
  1. {
  2.     "label": "person",
  3.     "properties": {
  4.         "age": 30,
  5.         "city": "Beijing"
  6.     }
  7. }

Note: There are three categories for property values: single, set, and list. If it is single, it means adding or updating the property value. If it is set or list, it means appending the property value.

Response Status
  1. 200
Response Body
  1. {
  2.     "id": "1:marko",
  3.     "label": "person",
  4.     "type": "vertex",
  5.     "properties": {
  6.         "name": "marko",
  7.         "age": 30,
  8.         "city": "Beijing"
  9.     }
  10. }

2.1.4 Batch Update Vertex Properties

Function Description

Batch update properties of vertices and support various update strategies, including:

  • SUM: Numeric accumulation
  • BIGGER: Take the larger value between two numbers/dates
  • SMALLER: Take the smaller value between two numbers/dates
  • UNION: Take the union of set properties
  • INTERSECTION: Take the intersection of set properties
  • APPEND: Append elements to list properties
  • ELIMINATE: Remove elements from list/set properties
  • OVERRIDE: Override existing properties, if the new property is null, the old property is still used

Assuming the original vertex and properties are:

  1. {
  2.     "vertices": [
  3.         {
  4.             "id": "2:lop",
  5.             "label": "software",
  6.             "type": "vertex",
  7.             "properties": {
  8.                 "name": "lop",
  9.                 "lang": "java",
  10.                 "price": 328
  11.             }
  12.         },
  13.         {
  14.             "id": "1:josh",
  15.             "label": "person",
  16.             "type": "vertex",
  17.             "properties": {
  18.                 "name": "josh",
  19.                 "age": 32,
  20.                 "city": "Beijing",
  21.                 "weight": 0.1,
  22.                 "hobby": [
  23.                     "reading",
  24.                     "football"
  25.                 ]
  26.             }
  27.         }
  28.     ]
  29. }

Add vertices with the following command:

  1. curl -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"josh","age":32,"city":"Beijing","weight":0.1,"hobby":["reading","football"]}},{"label":"software","properties":{"name":"lop","lang":"java","price":328}}]' http:///127.0.0.1:8080/graphs/hugegraph/graph/vertices/batch
Method & Url
  1. PUT http://127.0.0.1:8080/graphs/hugegraph/graph/vertices/batch
Request Body
  1. {
  2.     "vertices": [
  3.         {
  4.             "label": "software",
  5.             "type": "vertex",
  6.             "properties": {
  7.                 "name": "lop",
  8.                 "lang": "c++",
  9.                 "price": 299
  10.             }
  11.         },
  12.         {
  13.             "label": "person",
  14.             "type": "vertex",
  15.             "properties": {
  16.                 "name": "josh",
  17.                 "city": "Shanghai",
  18.                 "weight": 0.2,
  19.                 "hobby": [
  20.                     "swimming"
  21.                 ]
  22.             }
  23.         }
  24.     ],
  25.     "update_strategies": {
  26.         "price": "BIGGER",
  27.         "age": "OVERRIDE",
  28.         "city": "OVERRIDE",
  29.         "weight": "SUM",
  30.         "hobby": "UNION"
  31.     },
  32.     "create_if_not_exist": true
  33. }
Response Status
  1. 200
Response Body
  1. {
  2.     "vertices": [
  3.         {
  4.             "id": "2:lop",
  5.             "label": "software",
  6.             "type": "vertex",
  7.             "properties": {
  8.                 "name": "lop",
  9.                 "lang": "c++",
  10.                 "price": 328
  11.             }
  12.         },
  13.         {
  14.             "id": "1:josh",
  15.             "label": "person",
  16.             "type": "vertex",
  17.             "properties": {
  18.                 "name": "josh",
  19.                 "age": 32,
  20.                 "city": "Shanghai",
  21.                 "weight": 0.3,
  22.                 "hobby": [
  23.                     "reading",
  24.                     "football",
  25.                     "swimming"
  26.                 ]
  27.             }
  28.         }
  29.     ]
  30. }

Result Analysis:

  • The lang property does not specify an update strategy and is directly overwritten by the new value, regardless of whether the new value is null.
  • The price property specifies the BIGGER update strategy. The old property value is 328, and the new property value is 299, so the old property value of 328 is retained.
  • The age property specifies the OVERRIDE update strategy, but the new property value does not include age, which is equivalent to age being null. Therefore, the original property value of 32 is still retained.
  • The city property also specifies the OVERRIDE update strategy, and the new property value is not null, so it overrides the old value.
  • The weight property specifies the SUM update strategy. The old property value is 0.1, and the new property value is 0.2. The final value is 0.3.
  • The hobby property (cardinality is Set) specifies the UNION update strategy, so the new value is taken as the union with the old value.

The usage of other update strategies can be inferred in a similar manner and will not be further elaborated.

2.1.5 Delete Vertex Properties

Method & Url
  1. PUT http://127.0.0.1:8080/graphs/hugegraph/graph/vertices/"1:marko"?action=eliminate
Request Body
  1. {
  2.     "label": "person",
  3.     "properties": {
  4.         "city": "Beijing"
  5.     }
  6. }

Note: Here, the properties (keys and all values) will be directly deleted, regardless of whether the property values are single, set, or list.

Response Status
  1. 200
Response Body
  1. {
  2.     "id": "1:marko",
  3.     "label": "person",
  4.     "type": "vertex",
  5.     "properties": {
  6.         "name": "marko",
  7.         "age": 30
  8.     }
  9. }

2.1.6 Get Vertices that Meet the Criteria

Params
  • label: Vertex type
  • properties: Property key-value pairs (precondition: indexes are created for property queries)
  • limit: Maximum number of results
  • page: Page number

All of the above parameters are optional. If the page parameter is provided, the limit parameter must also be provided, and no other parameters are allowed. label, properties, and limit can be combined in any way.

Property key-value pairs consist of the property name and value in JSON format. Multiple property key-value pairs are allowed as query conditions. The property value supports exact matching, range matching, and fuzzy matching. For exact matching, use the format properties={"age":29}, for range matching, use the format properties={"age":"P.gt(29)"}, and for fuzzy matching, use the format properties={"city": "P.textcontains("ChengDu China")}. The following expressions are supported for range matching:

ExpressionExplanation
P.eq(number)Vertices with property value equal to number
P.neq(number)Vertices with property value not equal to number
P.lt(number)Vertices with property value less than number
P.lte(number)Vertices with property value less than or equal to number
P.gt(number)Vertices with property value greater than number
P.gte(number)Vertices with property value greater than or equal to number
P.between(number1,number2)Vertices with property value greater than or equal to number1 and less than number2
P.inside(number1,number2)Vertices with property value greater than number1 and less than number2
P.outside(number1,number2)Vertices with property value less than number1 and greater than number2
P.within(value1,value2,value3,…)Vertices with property value equal to any of the given values

Query all vertices with age 29 and label person

Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/graph/vertices?label=person&properties={"age":29}&limit=1
Response Status
  1. 200
Response Body
  1. {
  2.     "vertices": [
  3.         {
  4.             "id": "1:marko",
  5.             "label": "person",
  6.             "type": "vertex",
  7.             "properties": {
  8.                 "name": "marko",
  9.                 "age": 30
  10.             }
  11.         }
  12.     ]
  13. }

Paginate through all vertices, retrieve the first page (page without parameter value), limited to 3 records

Add vertices with the following command:

  1. curl -H "Content-Type: application/json" -d '[{"label":"person","properties":{"name":"peter","age":29,"city":"Shanghai"}},{"label":"person","properties":{"name":"vadas","age":27,"city":"Hongkong"}}]' http://localhost:8080/graphs/hugegraph/graph/vertices/batch
Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/graph/vertices?page&limit=3
Response Status
  1. 200
Response Body
  1. {
  2.     "vertices": [
  3.         {
  4.             "id": "2:lop",
  5.             "label": "software",
  6.             "type": "vertex",
  7.             "properties": {
  8.                 "name": "lop",
  9.                 "lang": "c++",
  10.                 "price": 328
  11.             }
  12.         },
  13.         {
  14.             "id": "1:josh",
  15.             "label": "person",
  16.             "type": "vertex",
  17.             "properties": {
  18.                 "name": "josh",
  19.                 "age": 32,
  20.                 "city": "Shanghai",
  21.                 "weight": 0.3,
  22.                 "hobby": [
  23.                     "reading",
  24.                     "football",
  25.                     "swimming"
  26.                 ]
  27.             }
  28.         },
  29.         {
  30.             "id": "1:marko",
  31.             "label": "person",
  32.             "type": "vertex",
  33.             "properties": {
  34.                 "name": "marko",
  35.                 "age": 30
  36.             }
  37.         }
  38.     ],
  39.     "page": "CIYxOnBldGVyAAAAAAAAAAM="
  40. }

The returned body contains information about the page number of the next page, "page": "CIYxOnBldGVyAAAAAAAAAAM". When querying the next page, assign this value to the page parameter.

Paginate and retrieve all vertices, including the next page (passing the page value returned from the previous page), limited to 3 items.

Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/graph/vertices?page=CIYxOnBldGVyAAAAAAAAAAM=&limit=3
Response Status
  1. 200
Response Body
  1. {
  2.     "vertices": [
  3.         {
  4.             "id": "1:peter",
  5.             "label": "person",
  6.             "type": "vertex",
  7.             "properties": {
  8.                 "name": "peter",
  9.                 "age": 29,
  10.                 "city": "Shanghai"
  11.             }
  12.         },
  13.         {
  14.             "id": "1:vadas",
  15.             "label": "person",
  16.             "type": "vertex",
  17.             "properties": {
  18.                 "name": "vadas",
  19.                 "age": 27,
  20.                 "city": "Hongkong"
  21.             }
  22.         },
  23.         {
  24.             "id": "2:ripple",
  25.             "label": "software",
  26.             "type": "vertex",
  27.             "properties": {
  28.                 "name": "ripple",
  29.                 "lang": "java",
  30.                 "price": 199
  31.             }
  32.         }
  33.     ],
  34.     "page": null
  35. }

At this point, "page": null indicates that there are no more pages available. (Note: When using Cassandra as the backend for performance reasons, if the returned page happens to be the last page, the page value may not be empty. When requesting the next page using that page value, it will return empty data and page = null. The same applies to other similar situations.)

2.1.7 Retrieve Vertex by ID

Method & Url
  1. GET http://localhost:8080/graphs/hugegraph/graph/vertices/"1:marko"
Response Status
  1. 200
Response Body
  1. {
  2.     "id": "1:marko",
  3.     "label": "person",
  4.     "type": "vertex",
  5.     "properties": {
  6.         "name": "marko",
  7.         "age": 30
  8.     }
  9. }

2.1.8 Delete Vertex by ID

Params
  • label: Vertex type, optional parameter

Delete the vertex based on ID only.

Method & Url
  1. DELETE http://localhost:8080/graphs/hugegraph/graph/vertices/"1:marko"
Response Status
  1. 204

Delete Vertex by Label+ID

When deleting a vertex by specifying both the Label parameter and the ID, it generally offers better performance compared to deleting by ID alone.

Method & Url
  1. DELETE http://localhost:8080/graphs/hugegraph/graph/vertices/"1:marko"?label=person
Response Status
  1. 204

Last modified June 4, 2023: docs: update outdated response in vertex api (#259) (37a1cb55)