2.1 Vertex

0.4 版本对顶点 Id 做了比较大的改动,VertexLabel 中的 Id 策略决定了顶点的 Id 类型,其对应关系如下:

Id_Strategy id type
AUTOMATIC number
PRIMARY_KEY string
CUSTOMIZE_STRING string
CUSTOMIZE_NUMBER number

顶点的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
  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": [
  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
  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. "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
  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. "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
  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. "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
  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": [
  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, propertieslimit可以任意组合。

属性键值对由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
  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. "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
  1. GET http://localhost:8080/graphs/hugegraph/graph/vertices?page&limit=3
Response Status
  1. 200
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
  1. GET http://localhost:8080/graphs/hugegraph/graph/vertices?page=001000100853313a706574657200f07ffffffc00e797c6349be736fffc8699e8a502efe10004&limit=3
Response Status
  1. 200
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
  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": [
  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
  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