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
1 import org.apache.hugegraph.HugeFactory
2 import org.apache.tinkerpop.gremlin.structure.T
3
4 conf = "conf/graphs/hugegraph.properties"
5 graph = HugeFactory . open ( conf )
6 schema = graph . schema ()
7
8 schema . propertyKey ( "name" ). asText (). ifNotExist (). create ()
9 schema . propertyKey ( "age" ). asInt (). ifNotExist (). create ()
10 schema . propertyKey ( "city" ). asText (). ifNotExist (). create ()
11 schema . propertyKey ( "weight" ). asDouble (). ifNotExist (). create ()
12 schema . propertyKey ( "lang" ). asText (). ifNotExist (). create ()
13 schema . propertyKey ( "date" ). asText (). ifNotExist (). create ()
14 schema . propertyKey ( "price" ). asInt (). ifNotExist (). create ()
15
16 schema . vertexLabel ( "person" ). properties ( "name" , "age" , "city" ). primaryKeys ( "name" ). ifNotExist (). create ()
17 schema . vertexLabel ( "software" ). properties ( "name" , "lang" , "price" ). primaryKeys ( "name" ). ifNotExist (). create ()
18 schema . indexLabel ( "personByCity" ). onV ( "person" ). by ( "city" ). secondary (). ifNotExist (). create ()
19 schema . indexLabel ( "personByAgeAndCity" ). onV ( "person" ). by ( "age" , "city" ). secondary (). ifNotExist (). create ()
20 schema . indexLabel ( "softwareByPrice" ). onV ( "software" ). by ( "price" ). range (). ifNotExist (). create ()
21 schema . edgeLabel ( "knows" ). sourceLabel ( "person" ). targetLabel ( "person" ). properties ( "date" , "weight" ). ifNotExist (). create ()
22 schema . edgeLabel ( "created" ). sourceLabel ( "person" ). targetLabel ( "software" ). properties ( "date" , "weight" ). ifNotExist (). create ()
23 schema . indexLabel ( "createdByDate" ). onE ( "created" ). by ( "date" ). secondary (). ifNotExist (). create ()
24 schema . indexLabel ( "createdByWeight" ). onE ( "created" ). by ( "weight" ). range (). ifNotExist (). create ()
25 schema . indexLabel ( "knowsByWeight" ). onE ( "knows" ). by ( "weight" ). range (). ifNotExist (). create ()
26
27 marko = graph . addVertex ( T . label , "person" , "name" , "marko" , "age" , 29 , "city" , "Beijing" )
28 vadas = graph . addVertex ( T . label , "person" , "name" , "vadas" , "age" , 27 , "city" , "Hongkong" )
29 lop = graph . addVertex ( T . label , "software" , "name" , "lop" , "lang" , "java" , "price" , 328 )
30 josh = graph . addVertex ( T . label , "person" , "name" , "josh" , "age" , 32 , "city" , "Beijing" )
31 ripple = graph . addVertex ( T . label , "software" , "name" , "ripple" , "lang" , "java" , "price" , 199 )
32 peter = graph . addVertex ( T . label , "person" , "name" , "peter" , "age" , 35 , "city" , "Shanghai" )
33
34 graph . tx (). commit ()
35 g = graph . traversal () 2.2.1 创建一条边 Params 路径参数说明:
graphspace: 图空间名称 graph:待操作的图 请求体说明:
label:边类型名称,必填 outV:源顶点 id,必填 inV:目标顶点 id,必填 outVLabel:源顶点类型,必填 inVLabel:目标顶点类型,必填 properties: 边关联的属性,对象内部结构为:name:属性名称 value:属性值 Method & Url
1 POST 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 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
1 POST 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 Response Body
1 [
2 "S1:marko>1>>S1:vadas" ,
3 "S1:marko>1>>S1:josh"
4 ] 2.2.3 更新边属性 Params 路径参数说明:
graphspace: 图空间名称 graph:待操作的图 id:待操作的边 id 请求参数说明:
请求体说明:
Method & Url
1 PUT 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 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
1 PUT 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 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 请求参数说明:
请求体说明:
Method & Url
1 PUT 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 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)"},范围匹配支持的表达式如下:
查询与顶点 person:marko(vertex_id=“1:marko”) 相连且 label 为 knows 的且 date 属性等于 “20160111” 的边
Method & Url
1 GET 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 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
1 GET http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges?page&limit=2 Response Status 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
1 GET http://127.0.0.1:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges?page=EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC&limit=2 Response Status 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
1 GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop Response Status 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 请求参数说明:
仅根据 id 删除边
Method & Url
1 DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop Response Status 根据 label + id 删除边
通过指定 label 参数和 id 来删除边时,一般来说其性能比仅根据 id 删除会更好
Method & Url
1 DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>1>>S1:vadas?label=knows Response Status