跳转到主要内容

Edge API

Edge(边)REST 接口:创建、查询、更新和删除顶点之间的关系数据,支持批量操作和方向查询。

2.2 Edge

顶点 id 格式的修改也影响到了边的 id 以及源顶点和目标顶点 id 的格式

EdgeId 是由 src-vertex-id + direction + label + sort-values + tgt-vertex-id 拼接而成,但是这里的顶点 id 类型不是通过引号区分的,而是根据前缀区分:

  • 当 id 类型为 number 时,EdgeId 的顶点 id 前有一个前缀 L ,形如 “L123456>1»L987654”
  • 当 id 类型为 string 时,EdgeId 的顶点 id 前有一个前缀 S ,形如 “S1:peter>1»S2:lop”

边 ID 使用 Server 的原始边 ID 格式,转义 URL 保留字符时不要额外加 JSON 引号。不能把顶点 ID 编码规则直接套到边 ID 上。 追加属性使用 PUT .../edges/{id}?action=append 并提交对应 JSON 属性体。 删除边时按后端要求提供 DELETE .../edges/{id}?label={label} 的标签参数。


接下来的示例需要先根据以下 groovy 脚本创建图 schema

 1import org.apache.hugegraph.HugeFactory
 2import org.apache.tinkerpop.gremlin.structure.T
 3
 4conf = "conf/graphs/hugegraph.properties"
 5graph = HugeFactory.open(conf)
 6schema = graph.schema()
 7
 8schema.propertyKey("name").asText().ifNotExist().create()
 9schema.propertyKey("age").asInt().ifNotExist().create()
10schema.propertyKey("city").asText().ifNotExist().create()
11schema.propertyKey("weight").asDouble().ifNotExist().create()
12schema.propertyKey("lang").asText().ifNotExist().create()
13schema.propertyKey("date").asText().ifNotExist().create()
14schema.propertyKey("price").asInt().ifNotExist().create()
15
16schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").ifNotExist().create()
17schema.vertexLabel("software").properties("name", "lang", "price").primaryKeys("name").ifNotExist().create()
18schema.indexLabel("personByCity").onV("person").by("city").secondary().ifNotExist().create()
19schema.indexLabel("personByAgeAndCity").onV("person").by("age", "city").secondary().ifNotExist().create()
20schema.indexLabel("softwareByPrice").onV("software").by("price").range().ifNotExist().create()
21schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").properties("date", "weight").ifNotExist().create()
22schema.edgeLabel("created").sourceLabel("person").targetLabel("software").properties("date", "weight").ifNotExist().create()
23schema.indexLabel("createdByDate").onE("created").by("date").secondary().ifNotExist().create()
24schema.indexLabel("createdByWeight").onE("created").by("weight").range().ifNotExist().create()
25schema.indexLabel("knowsByWeight").onE("knows").by("weight").range().ifNotExist().create()
26
27marko = graph.addVertex(T.label, "person", "name", "marko", "age", 29, "city", "Beijing")
28vadas = graph.addVertex(T.label, "person", "name", "vadas", "age", 27, "city", "Hongkong")
29lop = graph.addVertex(T.label, "software", "name", "lop", "lang", "java", "price", 328)
30josh = graph.addVertex(T.label, "person", "name", "josh", "age", 32, "city", "Beijing")
31ripple = graph.addVertex(T.label, "software", "name", "ripple", "lang", "java", "price", 199)
32peter = graph.addVertex(T.label, "person", "name", "peter", "age", 35, "city", "Shanghai")
33
34graph.tx().commit()
35g = graph.traversal()

2.2.1 创建一条边

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图

请求体说明:

  • label:边类型名称,必填
  • outV:源顶点 id,必填
  • inV:目标顶点 id,必填
  • outVLabel:源顶点类型,必填
  • inVLabel:目标顶点类型,必填
  • properties: 边关联的属性,对象内部结构为:
    1. name:属性名称
    2. value:属性值
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges
Request Body
 1{
 2    "label": "created",
 3    "outV": "1:marko",
 4    "inV": "2:lop",
 5    "outVLabel": "person",
 6    "inVLabel": "software",
 7    "properties": {
 8        "date": "20171210",
 9        "weight": 0.4
10    }
11}
Response Status
1201
Response Body
 1{
 2    "id": "S1:marko>2>>S2:lop",
 3    "label": "created",
 4    "type": "edge",
 5    "outV": "1:marko",
 6    "outVLabel": "person",
 7    "inV": "2:lop",
 8    "inVLabel": "software",
 9    "properties": {
10        "weight": 0.4,
11        "date": "20171210"
12    }
13}

2.2.2 创建多条边

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图

请求参数说明:

  • check_vertex:是否检查顶点存在 (true | false),当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错,默认为 true

请求体说明:

  • 边信息的列表
Method & Url
1POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/batch
Request Body
 1[
 2    {
 3        "label": "knows",
 4        "outV": "1:marko",
 5        "inV": "1:vadas",
 6        "outVLabel": "person",
 7        "inVLabel": "person",
 8        "properties": {
 9            "date": "20160110",
10            "weight": 0.5
11        }
12    },
13    {
14        "label": "knows",
15        "outV": "1:marko",
16        "inV": "1:josh",
17        "outVLabel": "person",
18        "inVLabel": "person",
19        "properties": {
20            "date": "20130220",
21            "weight": 1.0
22        }
23    }
24]
Response Status
1201
Response Body
1[
2    "S1:marko>1>>S1:vadas",
3    "S1:marko>1>>S1:josh"
4]

2.2.3 更新边属性

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图
  • id:待操作的边 id

请求参数说明:

  • action:append 操作

请求体说明:

  • 边信息
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=append
Request Body
1{
2    "properties": {
3        "weight": 1.0
4    }
5}

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

Response Status
1200
Response Body
 1{
 2    "id": "S1:marko>2>>S2:lop",
 3    "label": "created",
 4    "type": "edge",
 5    "outV": "1:marko",
 6    "outVLabel": "person",
 7    "inV": "2:lop",
 8    "inVLabel": "software",
 9    "properties": {
10        "weight": 1.0,
11        "date": "20171210"
12    }
13}

2.2.4 批量更新边属性

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图

请求体说明:

  • edges:边信息的列表
  • update_strategies:对于每个属性,可以单独设置其更新策略,包括:
    • SUM:仅支持 number 类型
    • BIGGER/SMALLER:仅支持 date/number 类型
    • UNION/INTERSECTION:仅支持 set 类型
    • APPEND/ELIMINATE:仅支持 collection 类型
    • OVERRIDE
  • check_vertex:是否检查顶点存在 (true | false),当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错,默认为 true
  • create_if_not_exist:目前只支持设定为 true
Method & Url
1PUT http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/batch
Request Body
 1{
 2    "edges": [
 3        {
 4            "label": "knows",
 5            "outV": "1:marko",
 6            "inV": "1:vadas",
 7            "outVLabel": "person",
 8            "inVLabel": "person",
 9            "properties": {
10                "date": "20160111",
11                "weight": 1.0
12            }
13        },
14        {
15            "label": "knows",
16            "outV": "1:marko",
17            "inV": "1:josh",
18            "outVLabel": "person",
19            "inVLabel": "person",
20            "properties": {
21                "date": "20130221",
22                "weight": 0.5
23            }
24        }
25    ],
26    "update_strategies": {
27        "weight": "SUM",
28        "date": "OVERRIDE"
29    },
30    "check_vertex": false,
31    "create_if_not_exist": true
32}
Response Status
1200
Response Body
 1{
 2    "edges": [
 3        {
 4            "id": "S1:marko>1>>S1:vadas",
 5            "label": "knows",
 6            "type": "edge",
 7            "outV": "1:marko",
 8            "outVLabel": "person",
 9            "inV": "1:vadas",
10            "inVLabel": "person",
11            "properties": {
12                "weight": 1.5,
13                "date": "20160111"
14            }
15        },
16        {
17            "id": "S1:marko>1>>S1:josh",
18            "label": "knows",
19            "type": "edge",
20            "outV": "1:marko",
21            "outVLabel": "person",
22            "inV": "1:josh",
23            "inVLabel": "person",
24            "properties": {
25                "weight": 1.5,
26                "date": "20130221"
27            }
28        }
29    ]
30}

2.2.5 删除边属性

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图
  • id:待操作的边 id

请求参数说明:

  • action:eliminate 操作

请求体说明:

  • 边信息
Method & Url
1PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=eliminate
Request Body
1{
2    "properties": {
3        "weight": 1.0
4    }
5}

注意:这里会直接删除属性(删除 key 和所有 value),无论其属性的取值是 single、set 或 list

Response Status
1400
Response Body

无法删除未设置为 nullable 的属性

1{
2    "exception": "class java.lang.IllegalArgumentException",
3    "message": "Can't remove non-null edge property 'p[weight->1.0]'",
4    "cause": ""
5}

2.2.6 获取符合条件的边

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图

请求参数说明:

  • vertex_id: 顶点 id
  • direction: 边的方向 (OUT | IN | BOTH),默认为 BOTH
  • label: 边的标签
  • properties: 属性键值对(索引覆盖要求见下文)
  • keep_start_p: 默认为 false,当设置为 true 后,不会自动转义范围匹配输入的表达式,例如此时 properties={"age":"P.gt(0.8)"} 会被理解为精确匹配,即 age 属性等于 “P.gt(0.8)”
  • offset:偏移,默认为 0
  • limit: 查询数目,默认为 100
  • page: 页号

未指定 vertex_id 时,properties 在全图范围内查询边。指定 label 时,该标签需有与查询条件匹配的属性索引;若指定的是未单独建索引的子边标签,可以使用其父标签(查询可见的)上的匹配索引,同级其他子标签的边会被自动过滤。

候选标签是可直接存边且声明了全部待查非 OLAP 属性的边标签(包括当前没有边的标签)。普通查询不可见的标签(包括正在删除的标签)不计入候选集,不需要索引覆盖。若所有候选标签均不可见或正在删除(或指定的 label 本身不可见或正在删除),查询返回空结果,不报索引错误。若没有任何 Schema 标签声明待查属性,仍会报索引错误。

未指定 label 时:base 父边标签不直接存边,子标签全部被覆盖时无需再为父标签单独建立索引。可以使用当前查询可见的父标签上的匹配索引覆盖子标签,也可以为每个候选子标签单独建立索引。父标签因隐藏或正在删除而被排除时,其索引不能用于覆盖子标签。仅有标签索引不等于属性已建立索引。

错误触发规则:查询值与属性类型兼容,但缺少匹配索引或只覆盖了部分候选标签,均会报索引错误;仅当所有候选标签均被完整覆盖时,查询才通过索引执行。查询值与属性类型不兼容时,若已找到匹配索引则可能返回空结果(跳过部分覆盖检查);若无任何匹配索引仍报索引错误。查询不会自动回退到全量扫描。

说明

部分覆盖检查、子边标签复用父标签索引,以及候选标签不可见时返回空结果的机制,自 1.8.0 起生效。早期版本仅使用指定标签自身建立的索引,未指定 label 时仅返回命中索引标签的匹配结果,且在无标签具备匹配索引时直接报索引错误。

指定 vertex_id 时,查询过滤该顶点的邻接边,不适用上述全图查询的索引覆盖要求。

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

表达式说明
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 的边
P.textcontains(value)属性值包含给定 value 的边 (string 类型)
P.contains(value)属性值包含给定 value 的边 (collection 类型)

查询与顶点 person:marko(vertex_id=“1:marko”) 相连且 label 为 knows 的且 date 属性等于 “20160111” 的边

Method & Url
1GET http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges?vertex_id="1:marko"&label=knows&properties={"date":"P.within(\"20160111\")"}
Response Status
1200
Response Body
 1{
 2    "edges": [
 3        {
 4            "id": "S1:marko>1>>S1:vadas",
 5            "label": "knows",
 6            "type": "edge",
 7            "outV": "1:marko",
 8            "outVLabel": "person",
 9            "inV": "1:vadas",
10            "inVLabel": "person",
11            "properties": {
12                "weight": 1.5,
13                "date": "20160111"
14            }
15        }
16    ]
17}

分页查询所有边,获取第一页(page 不带参数值),限定 2 条

Method & Url
1GET http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges?page&limit=2
Response Status
1200
Response Body
 1{
 2    "edges": [
 3        {
 4            "id": "S1:marko>1>>S1:josh",
 5            "label": "knows",
 6            "type": "edge",
 7            "outV": "1:marko",
 8            "outVLabel": "person",
 9            "inV": "1:josh",
10            "inVLabel": "person",
11            "properties": {
12                "weight": 1.5,
13                "date": "20130221"
14            }
15        },
16        {
17            "id": "S1:marko>1>>S1:vadas",
18            "label": "knows",
19            "type": "edge",
20            "outV": "1:marko",
21            "outVLabel": "person",
22            "inV": "1:vadas",
23            "inVLabel": "person",
24            "properties": {
25                "weight": 1.5,
26                "date": "20160111"
27            }
28        }
29    ],
30    "page": "EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC"
31}

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

分页查询所有边,获取下一页(page 带上上一页返回的 page 值),限定 2 条

Method & Url
1GET http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges?page=EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC&limit=2
Response Status
1200
Response Body
 1{
 2    "edges": [
 3        {
 4            "id": "S1:marko>2>>S2:lop",
 5            "label": "created",
 6            "type": "edge",
 7            "outV": "1:marko",
 8            "outVLabel": "person",
 9            "inV": "2:lop",
10            "inVLabel": "software",
11            "properties": {
12                "weight": 1.0,
13                "date": "20171210"
14            }
15        }
16    ],
17    "page": null
18}

此时 "page": null 表示已经没有下一页了

注:后端为 Cassandra 时,为了性能考虑,返回页恰好为最后一页时,返回 page 值可能非空,通过该 page 再请求下一页数据时则返回 空数据 及 page = null,其他情况类似

2.2.7 根据 id 获取边

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图
  • id:待操作的边 id
Method & Url
1GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop
Response Status
1200
Response Body
 1{
 2    "id": "S1:marko>2>>S2:lop",
 3    "label": "created",
 4    "type": "edge",
 5    "outV": "1:marko",
 6    "outVLabel": "person",
 7    "inV": "2:lop",
 8    "inVLabel": "software",
 9    "properties": {
10        "weight": 1.0,
11        "date": "20171210"
12    }
13}

2.2.8 根据 id 删除边

Params

路径参数说明:

  • graphspace: 图空间名称
  • graph:待操作的图
  • id:待操作的边 id

请求参数说明:

  • label: 边的标签

仅根据 id 删除边

Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop
Response Status
1204

根据 label + id 删除边

通过指定 label 参数和 id 来删除边时,一般来说其性能比仅根据 id 删除会更好

Method & Url
1DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>1>>S1:vadas?label=knows
Response Status
1204