Skip to content

Version 1.0 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Vertex API

2.1 Vertex

顶点类型中的 Id 策略决定了顶点的 Id 类型，其对应关系如下：

Id_Strategyid type
AUTOMATICnumber
PRIMARY_KEYstring
CUSTOMIZE_STRINGstring
CUSTOMIZE_NUMBERnumber
CUSTOMIZE_UUIDuuid

顶点的 GET/PUT/DELETE API 中 url 的 id 部分传入的应是带有类型信息的 id 值，这个类型信息用 json 串是否带引号表示，也就是说：

  • 当 id 类型为 number 时，url 中的 id 不带引号，形如 xxx/vertices/123456
  • 当 id 类型为 string 时，url 中的 id 带引号，形如 xxx/vertices/“123456”

接下来的示例均假设已经创建好了前述的各种 schema 信息

2.1.1 创建一个顶点

Method & Url
1POST 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
1201
Response Body
 1{
 2    "id": "1:marko",
 3    "label": "person",
 4    "type": "vertex",
 5    "properties": {
 6        "name": [
 7            {
 8                "id": "1:marko>name",
 9                "value": "marko"
10            }
11        ],
12        "age": [
13            {
14                "id": "1:marko>age",
15                "value": 29
16            }
17        ]
18    }
19}

2.1.2 创建多个顶点

Method & Url
1POST 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
1201
Response Body
1[
2    "1:marko",
3    "2:ripple"
4]

2.1.3 更新顶点属性

Method & Url
1PUT 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}

注意：属性的取值是有三种类别的，分别是single、set和list。如果是single，表示增加或更新属性值；如果是set或list，则表示追加属性值。

Response Status
1200
Response Body
 1{
 2    "id": "1:marko",
 3    "label": "person",
 4    "type": "vertex",
 5    "properties": {
 6        "city": [
 7            {
 8                "id": "1:marko>city",
 9                "value": "Beijing"
10            }
11        ],
12        "name": [
13            {
14                "id": "1:marko>name",
15                "value": "marko"
16            }
17        ],
18        "age": [
19            {
20                "id": "1:marko>age",
21                "value": 30
22            }
23        ]
24    }
25}

2.1.4 批量更新顶点属性

功能说明

批量更新顶点的属性，并支持多种更新策略，包括

  • SUM: 数值累加
  • BIGGER: 两个数字/日期取更大的
  • SMALLER: 两个数字/日期取更小的
  • UNION: Set属性取并集
  • INTERSECTION: Set属性取交集
  • APPEND: List属性追加元素
  • ELIMINATE: List/Set属性删除元素
  • OVERRIDE: 覆盖已有属性，如果新属性为null，则仍然使用旧属性

假设原顶点及属性为：

 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}
Method & Url
1PUT 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                    "swiming"
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
1200
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                    "swiming",
24                    "reading",
25                    "football"
26                ]
27            }
28        }
29    ]
30}

结果分析：

  • lang 属性未指定更新策略，直接用新值覆盖旧值，无论新值是否为null；
  • price 属性指定 BIGGER 的更新策略，旧属性值为328，新属性值为299，所以仍然保留了旧属性值328；
  • age 属性指定 OVERRIDE 更新策略，而新属性值中未传入age，相当于age为null，所以仍然保留了原属性值32；
  • city 属性也指定了 OVERRIDE 更新策略，且新属性值不为null，所以覆盖了旧值；
  • weight 属性指定了 SUM 更新策略，旧属性值为0.1，新属性值为0.2，最后的值为0.3；
  • hobby 属性（基数为Set）指定了 UNION 更新策略，所以新值与旧值取了并集；

其他的更新策略使用方式可以类推，不再赘述。

2.1.5 删除顶点属性

Method & Url
1PUT 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}

注意：这里会直接删除属性（删除key和所有value），无论其属性的取值是single、set或list。

Response Status
1200
Response Body
 1{
 2    "id": "1:marko",
 3    "label": "person",
 4    "type": "vertex",
 5    "properties": {
 6        "name": [
 7            {
 8                "id": "1:marko>name",
 9                "value": "marko"
10            }
11        ],
12        "age": [
13            {
14                "id": "1:marko>age",
15                "value": 30
16            }
17        ]
18    }
19}

2.1.6 获取符合条件的顶点

Params
  • label: 顶点类型
  • properties: 属性键值对(根据属性查询的前提是预先建立了索引)
  • limit: 查询最大数目
  • page: 页号

以上参数都是可选的，如果提供page参数，必须提供limit参数，不允许带其他参数。label, properties和limit可以任意组合。

属性键值对由JSON格式的属性名称和属性值组成，允许多个属性键值对作为查询条件，属性值支持精确匹配和范围匹配，精确匹配时形如properties={"age":29}，范围匹配时形如properties={"age":"P.gt(29)"},范围匹配支持的表达式如下：

表达式说明
P.eq(number)属性值等于number的顶点
P.neq(number)属性值不等于number的顶点
P.lt(number)属性值小于number的顶点
P.lte(number)属性值小于等于number的顶点
P.gt(number)属性值大于number的顶点
P.gte(number)属性值大于等于number的顶点
P.between(number1,number2)属性值大于等于number1且小于number2的顶点
P.inside(number1,number2)属性值大于number1且小于number2的顶点
P.outside(number1,number2)属性值小于number1且大于number2的顶点
P.within(value1,value2,value3,…)属性值等于任何一个给定value的顶点

查询所有 age 为 20 且 label 为 person 的顶点

Method & Url
1GET http://localhost:8080/graphs/hugegraph/graph/vertices?label=person&properties={"age":29}&limit=1
Response Status
1200
Response Body
 1{
 2    "vertices": [
 3        {
 4            "id": "1:marko",
 5            "label": "person",
 6            "type": "vertex",
 7            "properties": {
 8                "city": [
 9                    {
10                        "id": "1:marko>city",
11                        "value": "Beijing"
12                    }
13                ],
14                "name": [
15                    {
16                        "id": "1:marko>name",
17                        "value": "marko"
18                    }
19                ],
20                "age": [
21                    {
22                        "id": "1:marko>age",
23                        "value": 29
24                    }
25                ]
26            }
27        }
28    ]
29}

分页查询所有顶点，获取第一页（page不带参数值），限定3条

Method & Url
1GET http://localhost:8080/graphs/hugegraph/graph/vertices?page&limit=3
Response Status
1200
Response Body
 1{
 2	"vertices": [{
 3			"id": "2:ripple",
 4			"label": "software",
 5			"type": "vertex",
 6			"properties": {
 7				"price": [{
 8					"id": "2:ripple>price",
 9					"value": 199
10				}],
11				"name": [{
12					"id": "2:ripple>name",
13					"value": "ripple"
14				}],
15				"lang": [{
16					"id": "2:ripple>lang",
17					"value": "java"
18				}]
19			}
20		},
21		{
22			"id": "1:vadas",
23			"label": "person",
24			"type": "vertex",
25			"properties": {
26				"city": [{
27					"id": "1:vadas>city",
28					"value": "Hongkong"
29				}],
30				"name": [{
31					"id": "1:vadas>name",
32					"value": "vadas"
33				}],
34				"age": [{
35					"id": "1:vadas>age",
36					"value": 27
37				}]
38			}
39		},
40		{
41			"id": "1:peter",
42			"label": "person",
43			"type": "vertex",
44			"properties": {
45				"city": [{
46					"id": "1:peter>city",
47					"value": "Shanghai"
48				}],
49				"name": [{
50					"id": "1:peter>name",
51					"value": "peter"
52				}],
53				"age": [{
54					"id": "1:peter>age",
55					"value": 35
56				}]
57			}
58		}
59	],
60	"page": "001000100853313a706574657200f07ffffffc00e797c6349be736fffc8699e8a502efe10004"
61}

返回的body里面是带有下一页的页号信息的，"page": "001000100853313a706574657200f07ffffffc00e797c6349be736fffc8699e8a502efe10004"， 在查询下一页的时候将该值赋给page参数。

分页查询所有顶点，获取下一页（page带上上一页返回的page值），限定3条

Method & Url
1GET http://localhost:8080/graphs/hugegraph/graph/vertices?page=001000100853313a706574657200f07ffffffc00e797c6349be736fffc8699e8a502efe10004&limit=3
Response Status
1200
Response Body
 1{
 2	"vertices": [{
 3			"id": "1:josh",
 4			"label": "person",
 5			"type": "vertex",
 6			"properties": {
 7				"city": [{
 8					"id": "1:josh>city",
 9					"value": "Beijing"
10				}],
11				"name": [{
12					"id": "1:josh>name",
13					"value": "josh"
14				}],
15				"age": [{
16					"id": "1:josh>age",
17					"value": 32
18				}]
19			}
20		},
21		{
22			"id": "1:marko",
23			"label": "person",
24			"type": "vertex",
25			"properties": {
26				"city": [{
27					"id": "1:marko>city",
28					"value": "Beijing"
29				}],
30				"name": [{
31					"id": "1:marko>name",
32					"value": "marko"
33				}],
34				"age": [{
35					"id": "1:marko>age",
36					"value": 29
37				}]
38			}
39		},
40		{
41			"id": "2:lop",
42			"label": "software",
43			"type": "vertex",
44			"properties": {
45				"price": [{
46					"id": "2:lop>price",
47					"value": 328
48				}],
49				"name": [{
50					"id": "2:lop>name",
51					"value": "lop"
52				}],
53				"lang": [{
54					"id": "2:lop>lang",
55					"value": "java"
56				}]
57			}
58		}
59	],
60	"page": null
61}

此时"page": null表示已经没有下一页了 (注: 后端为 Cassandra 时，为了性能考虑，返回页恰好为最后一页时，返回 page 值可能非空，通过该 page 再请求下一页数据时则返回 空数据 及 page = null，其他情况类似)

2.1.7 根据Id获取顶点

Method & Url
1GET http://localhost:8080/graphs/hugegraph/graph/vertices/"1:marko"
Response Status
1200
Response Body
 1{
 2    "id": "1:marko",
 3    "label": "person",
 4    "type": "vertex",
 5    "properties": {
 6        "name": [
 7            {
 8                "id": "1:marko>name",
 9                "value": "marko"
10            }
11        ],
12        "age": [
13            {
14                "id": "1:marko>age",
15                "value": 29
16            }
17        ]
18    }
19}

2.1.8 根据Id删除顶点

Params
  • label: 顶点类型，可选参数

仅根据Id删除顶点

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

根据Label+Id删除顶点

通过指定Label参数和Id来删除顶点时，一般来说其性能比仅根据Id删除会更好。

Method & Url
1DELETE http://localhost:8080/graphs/hugegraph/graph/vertices/"1:marko"?label=person
Response Status
1204
Last modified 2022-09-15 · cn: format table & fix typo (#150) (53bf0aafc)