我的书签
添加书签
移除书签Vertex API
2.1 Vertex
顶点类型中的 Id 策略决定了顶点的 Id 类型，其对应的 id 类型如下：
| Id_Strategy | id type |
|---|---|
| AUTOMATIC | number |
| PRIMARY_KEY | string |
| CUSTOMIZE_STRING | string |
| CUSTOMIZE_NUMBER | number |
| CUSTOMIZE_UUID | uuid |
顶点的 GET/PUT/DELETE API 中 url 的 id 部分应该传入带有类型信息的 id 值，这个类型信息通过 json 串是否带引号来表示，也就是说：
- 当 id 类型为
number时，url 中的 id 不带引号，例如xxx/vertices/123456 - 当 id 类型为
string时，url 中的 id 带引号，例如xxx/vertices/"123456"
接下来的示例需要先根据以下 groovy 脚本创建图 schema
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 创建一个顶点
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 创建多个顶点
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 更新顶点属性
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. }
注意：属性的取值有三种类别，分别为single、set和list。single表示增加或更新属性值，set或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. "city": "Beijing"
9. }
10. }
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. }
通过以下命令新增顶点：
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. }
结果分析如下：
- 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
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. }
注意：这里会直接删除属性（删除key和所有value），无论其属性的取值是single、set或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 获取符合条件的顶点
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 为 29 且 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. }
分页查询所有顶点，获取第一页（page不带参数值），限定3条
通过以下命令新增顶点：
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. }
返回的 body 里面是带有下一页的页号信息的，"page": "CIYxOnBldGVyAAAAAAAAAAM="，在查询下一页的时候将该值赋给 page 参数。
分页查询所有顶点，获取下一页（page带上上一页返回的page值），限定3条
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. }
当"page": null时，表示已经没有下一页了（注：如果后端使用的是 Cassandra ，为了提高性能，当返回的页数刚好是最后一页时，返回的 page 值可能不为空，但是如果用这个 page 值再请求下一页数据时，就会返回 空数据 和 page = null，其他情况也类似）
2.1.7 根据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 根据Id删除顶点
Params
- label: 顶点类型，可选参数
仅根据Id删除顶点
Method & Url
1. DELETE http://localhost:8080/graphs/hugegraph/graph/vertices/"1:marko"
Response Status
1. 204
根据Label+Id删除顶点
通过指定Label参数和Id来删除顶点时，一般来说其性能比仅根据Id删除会更好。
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)
