From ab3812abd92f0dadcbc45d3d0ae22e12deed6dd4 Mon Sep 17 00:00:00 2001 From: V_Galaxy <1904821183@qq.com> Date: Thu, 22 Jun 2023 01:02:20 +0800 Subject: [PATCH 1/4] doc: fix edge single, batch create and update api doc --- content/cn/docs/clients/restful-api/edge.md | 382 +++++++++++--------- 1 file changed, 218 insertions(+), 164 deletions(-) diff --git a/content/cn/docs/clients/restful-api/edge.md b/content/cn/docs/clients/restful-api/edge.md index 820744727..70d766160 100644 --- a/content/cn/docs/clients/restful-api/edge.md +++ b/content/cn/docs/clients/restful-api/edge.md @@ -8,30 +8,72 @@ weight: 8 顶点 id 格式的修改也影响到了边的 Id 以及源顶点和目标顶点 id 的格式。 -EdgeId是由 `src-vertex-id + direction + label + sort-values + tgt-vertex-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 类型为 number 时，EdgeId 的顶点 id 前有一个前缀 `L` ，形如 "L123456>1>>L987654" +- 当 id 类型为 string 时，EdgeId 的顶点 id 前有一个前缀 `S` ，形如 "S1:peter>1>>S2:lop" -------------------------------------------------------------------------------- -接下来的示例均假设已经创建好了前述的各种schema和vertex信息 +接下来的示例需要先根据以下 `groovy` 脚本创建图 `schema` + +```groovy +import org.apache.hugegraph.HugeFactory +import org.apache.tinkerpop.gremlin.structure.T + +conf = "conf/graphs/hugegraph.properties" +graph = HugeFactory.open(conf) +schema = graph.schema() + +schema.propertyKey("name").asText().ifNotExist().create() +schema.propertyKey("age").asInt().ifNotExist().create() +schema.propertyKey("city").asText().ifNotExist().create() +schema.propertyKey("weight").asDouble().ifNotExist().create() +schema.propertyKey("lang").asText().ifNotExist().create() +schema.propertyKey("date").asText().ifNotExist().create() +schema.propertyKey("price").asInt().ifNotExist().create() + +schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").ifNotExist().create() +schema.vertexLabel("software").properties("name", "lang", "price").primaryKeys("name").ifNotExist().create() +schema.indexLabel("personByCity").onV("person").by("city").secondary().ifNotExist().create() +schema.indexLabel("personByAgeAndCity").onV("person").by("age", "city").secondary().ifNotExist().create() +schema.indexLabel("softwareByPrice").onV("software").by("price").range().ifNotExist().create() +schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").properties("date", "weight").ifNotExist().create() +schema.edgeLabel("created").sourceLabel("person").targetLabel("software").properties("date", "weight").ifNotExist().create() +schema.indexLabel("createdByDate").onE("created").by("date").secondary().ifNotExist().create() +schema.indexLabel("createdByWeight").onE("created").by("weight").range().ifNotExist().create() +schema.indexLabel("knowsByWeight").onE("knows").by("weight").range().ifNotExist().create() + +marko = graph.addVertex(T.label, "person", "name", "marko", "age", 29, "city", "Beijing") +vadas = graph.addVertex(T.label, "person", "name", "vadas", "age", 27, "city", "Hongkong") +lop = graph.addVertex(T.label, "software", "name", "lop", "lang", "java", "price", 328) +josh = graph.addVertex(T.label, "person", "name", "josh", "age", 32, "city", "Beijing") +ripple = graph.addVertex(T.label, "software", "name", "ripple", "lang", "java", "price", 199) +peter = graph.addVertex(T.label, "person", "name", "peter", "age", 35, "city", "Shanghai") + +graph.tx().commit() +g = graph.traversal() +``` #### 2.2.1 创建一条边 -Params说明 +##### Params + +路径参数说明： + +- graph：待操作的图 + +请求体说明： - label：边类型名称，必填 -- outV：源顶点id，必填 -- inV：目标顶点id，必填 -- outVLabel：源顶点类型。必填 -- inVLabel：目标顶点类型。必填 +- outV：源顶点 id，必填 +- inV：目标顶点 id，必填 +- outVLabel：源顶点类型，必填 +- inVLabel：目标顶点类型，必填 - properties: 边关联的属性，对象内部结构为： 1. name：属性名称 2. value：属性值 - ##### Method & Url ``` @@ -43,13 +85,13 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges ```json { "label": "created", - "outV": "1:peter", + "outV": "1:marko", "inV": "2:lop", "outVLabel": "person", "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "date": "20171210", + "weight": 0.4 } } ``` @@ -64,16 +106,16 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges ```json { - "id": "S1:peter>1>>S2:lop", + "id": "S1:marko>2>>S2:lop", "label": "created", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", "inV": "2:lop", - "outV": "1:peter", + "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "weight": 0.4, + "date": "20171210" } } ``` @@ -82,7 +124,17 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges ##### Params -- check_vertex: 是否检查顶点存在(true | false)，当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错。 +路径参数说明： + +- graph：待操作的图 + +请求参数说明： + +- check_vertex：当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错，默认为 true + +请求体说明： + +- 边信息的列表 ##### Method & Url @@ -95,25 +147,25 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges/batch ```json [ { - "label": "created", - "outV": "1:peter", - "inV": "2:lop", + "label": "knows", + "outV": "1:marko", + "inV": "1:vadas", "outVLabel": "person", - "inVLabel": "software", + "inVLabel": "person", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "date": "20160110", + "weight": 0.5 } }, { "label": "knows", "outV": "1:marko", - "inV": "1:vadas", + "inV": "1:josh", "outVLabel": "person", "inVLabel": "person", "properties": { - "date": "2016-01-10", - "weight": 0.5 + "date": "20130220", + "weight": 1.0 } } ] @@ -129,17 +181,32 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges/batch ```json [ - "S1:peter>1>>S2:lop", - "S1:marko>2>>S1:vadas" + "S1:marko>1>>S1:vadas", + "S1:marko>1>>S1:josh" ] ``` #### 2.2.3 更新边属性 +##### Params + +路径参数说明： + +- graph：待操作的图 +- id：待操作的边 id + +请求参数说明： + +- action：append 操作 + +请求体说明： + +- 边信息 + ##### Method & Url ``` -PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action=append +PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=append ``` ##### Request Body @@ -152,7 +219,7 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action } ``` -> 注意：属性的取值是有三种类别的，分别是single、set和list。如果是single，表示增加或更新属性值；如果是set或list，则表示追加属性值。 +> 注意：属性的取值是有三种类别的，分别是 single、set 和 list。如果是 single，表示增加或更新属性值；如果是 set 或 list，则表示追加属性值。 ##### Response Status @@ -164,60 +231,39 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action ```json { - "id": "S1:peter>1>>S2:lop", + "id": "S1:marko>2>>S2:lop", "label": "created", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", "inV": "2:lop", - "outV": "1:peter", + "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 1 + "weight": 1.0, + "date": "20171210" } } ``` #### 2.2.4 批量更新边属性 -##### 功能说明 +##### Params -与批量更新顶点属性类似 +路径参数说明： -假设原边及属性为： +- graph：待操作的图 -```json -{ - "edges":[ - { - "id":"S1:josh>2>>S2:ripple", - "label":"created", - "type":"edge", - "outV":"1:josh", - "outVLabel":"person", - "inV":"2:ripple", - "inVLabel":"software", - "properties":{ - "weight":1, - "date":1512835200000 - } - }, - { - "id":"S1:marko>1>7JooBil0>S1:josh", - "label":"knows", - "type":"edge", - "outV":"1:marko", - "outVLabel":"person", - "inV":"1:josh", - "inVLabel":"person", - "properties":{ - "weight":1, - "date":1361289600000 - } - } - ] -} -``` +请求体说明： + +- edges：边信息的列表 +- update_strategies：对于每个属性，可以单独设置其更新策略，包括： + - SUM：仅支持 number 类型 + - BIGGER/SMALLER：仅支持 date/number 类型 + - UNION/INTERSECTION：仅支持 set 类型 + - APPEND/ELIMINATE：仅支持 collection 类型 + - OVERRIDE +- check_vertex：当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错，默认为 true +- create_if_not_exist：目前只支持设定为 true ##### Method & Url @@ -229,38 +275,36 @@ PUT http://127.0.0.1:8080/graphs/hugegraph/graph/edges/batch ```json { - "edges":[ + "edges": [ { - "id":"S1:josh>2>>S2:ripple", - "label":"created", - "outV":"1:josh", - "outVLabel":"person", - "inV":"2:ripple", - "inVLabel":"software", - "properties":{ - "weight":0.1, - "date":1522835200000 + "label": "knows", + "outV": "1:marko", + "inV": "1:vadas", + "outVLabel": "person", + "inVLabel": "person", + "properties": { + "date": "20160111", + "weight": 1.0 } }, { - "id":"S1:marko>1>7JooBil0>S1:josh", - "label":"knows", - "outV":"1:marko", - "outVLabel":"person", - "inV":"1:josh", - "inVLabel":"person", - "properties":{ - "weight":0.2, - "date":1301289600000 + "label": "knows", + "outV": "1:marko", + "inV": "1:josh", + "outVLabel": "person", + "inVLabel": "person", + "properties": { + "date": "20130221", + "weight": 0.5 } } ], - "update_strategies":{ - "weight":"SUM", - "date":"BIGGER" + "update_strategies": { + "weight": "SUM", + "date": "OVERRIDE" }, "check_vertex": false, - "create_if_not_exist":true + "create_if_not_exist": true } ``` @@ -274,31 +318,31 @@ PUT http://127.0.0.1:8080/graphs/hugegraph/graph/edges/batch ```json { - "edges":[ + "edges": [ { - "id":"S1:josh>2>>S2:ripple", - "label":"created", - "type":"edge", - "outV":"1:josh", - "outVLabel":"person", - "inV":"2:ripple", - "inVLabel":"software", - "properties":{ - "weight":1.1, - "date":1522835200000 + "id": "S1:marko>1>>S1:vadas", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:vadas", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20160111" } }, { - "id":"S1:marko>1>7JooBil0>S1:josh", - "label":"knows", - "type":"edge", - "outV":"1:marko", - "outVLabel":"person", - "inV":"1:josh", - "inVLabel":"person", - "properties":{ - "weight":1.2, - "date":1301289600000 + "id": "S1:marko>1>>S1:josh", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:josh", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20130221" } } ] @@ -307,10 +351,25 @@ PUT http://127.0.0.1:8080/graphs/hugegraph/graph/edges/batch #### 2.2.5 删除边属性 +##### Params + +路径参数说明： + +- graph：待操作的图 +- id：待操作的边 id + +请求参数说明： + +- action：eliminate 操作 + +请求体说明： + +- 边信息 + ##### Method & Url ``` -PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action=eliminate +PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=eliminate ``` ##### Request Body @@ -323,28 +382,23 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action } ``` -> 注意：这里会直接删除属性（删除key和所有value），无论其属性的取值是single、set或list。 +> 注意：这里会直接删除属性（删除 key 和所有 value），无论其属性的取值是 single、set 或 list。 ##### Response Status ```json -200 +400 ``` ##### Response Body +无法删除未设置为 nullable 的属性 + ```json { - "id": "S1:peter>1>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:peter", - "properties": { - "date": "20170324" - } + "exception": "class java.lang.IllegalArgumentException", + "message": "Can't remove non-null edge property 'p[weight->1.0]'", + "cause": "" } ``` @@ -352,36 +406,36 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action ##### Params -- vertex_id: 顶点id -- direction: 边的方向(OUT | IN | BOTH) +- vertex_id: 顶点 id +- direction: 边的方向 (OUT | IN | BOTH) - label: 边的标签 -- properties: 属性键值对(根据属性查询的前提是预先建立了索引) -- offset：偏移，默认为0 -- limit: 查询数目，默认为100 +- properties: 属性键值对 (根据属性查询的前提是预先建立了索引) +- offset：偏移，默认为 0 +- limit: 查询数目，默认为 100 - page: 页号 支持的查询有以下几种： -- 提供vertex_id参数时，不可以使用参数page，direction、label、properties可选，offset和limit可以 +- 提供 vertex_id 参数时，不可以使用参数 page，direction、label、properties 可选，offset 和 limit 可以 限制结果范围 -- 不提供vertex_id参数时，label和properties可选 - - 如果使用page参数，则：offset参数不可用（不填或者为0），direction不可用，properties最多只能有一个 - - 如果不使用page参数，则：offset和limit可以用来限制结果范围，direction参数忽略 - -属性键值对由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的边 | +- 不提供 vertex_id 参数时，label 和 properties 可选 + - 如果使用 page 参数，则：offset 参数不可用（不填或者为 0），direction 不可用，properties 最多只能有一个 + - 如果不使用 page 参数，则：offset 和 limit 可以用来限制结果范围，direction 参数忽略 + +属性键值对由 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 的边 | **查询与顶点 person:josh(vertex_id="1:josh") 相连且 label 为 created 的边** @@ -432,7 +486,7 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:josh"&direct } ``` -**分页查询所有边，获取第一页（page不带参数值），限定3条** +**分页查询所有边，获取第一页（page 不带参数值），限定 3 条** ##### Method & Url @@ -494,10 +548,10 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=3 } ``` -返回的body里面是带有下一页的页号信息的，`"page": "002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004"`， -在查询下一页的时候将该值赋给page参数。 +返回的 body 里面是带有下一页的页号信息的，`"page": "002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004"`， +在查询下一页的时候将该值赋给 page 参数。 -**分页查询所有边，获取下一页（page带上上一页返回的page值），限定3条** +**分页查询所有边，获取下一页（page 带上上一页返回的 page 值），限定 3 条** ##### Method & Url @@ -559,9 +613,9 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=002500100753313a6a6f } ``` -此时`"page": null`表示已经没有下一页了 (注: 后端为 Cassandra 时，为了性能考虑，返回页恰好为最后一页时，返回 `page` 值可能非空，通过该 `page` 再请求下一页数据时则返回 `空数据` 及 `page = null`，其他情况类似) +此时`"page": null`表示已经没有下一页了 (注：后端为 Cassandra 时，为了性能考虑，返回页恰好为最后一页时，返回 `page` 值可能非空，通过该 `page` 再请求下一页数据时则返回 `空数据` 及 `page = null`，其他情况类似) -#### 2.2.7 根据Id获取边 +#### 2.2.7 根据 Id 获取边 ##### Method & Url @@ -593,13 +647,13 @@ GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop } ``` -#### 2.2.8 根据Id删除边 +#### 2.2.8 根据 Id 删除边 ##### Params - label: 边类型，可选参数 -**仅根据Id删除边** +**仅根据 Id 删除边** ##### Method & Url @@ -613,9 +667,9 @@ DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop 204 ``` -**根据Label+Id删除边** +**根据 Label + Id 删除边** -通过指定Label参数和Id来删除边时，一般来说其性能比仅根据Id删除会更好。 +通过指定 Label 参数和 Id 来删除边时，一般来说其性能比仅根据 Id 删除会更好。 ##### Method & Url From 13448b08c416c458a60f7f1368b12786ac3d3110 Mon Sep 17 00:00:00 2001 From: V_Galaxy <1904821183@qq.com> Date: Thu, 22 Jun 2023 01:34:03 +0800 Subject: [PATCH 2/4] doc: fix edge api doc --- content/cn/docs/clients/restful-api/edge.md | 283 +++++++++----------- 1 file changed, 130 insertions(+), 153 deletions(-) diff --git a/content/cn/docs/clients/restful-api/edge.md b/content/cn/docs/clients/restful-api/edge.md index 70d766160..46fe745ed 100644 --- a/content/cn/docs/clients/restful-api/edge.md +++ b/content/cn/docs/clients/restful-api/edge.md @@ -6,7 +6,7 @@ weight: 8 ### 2.2 Edge -顶点 id 格式的修改也影响到了边的 Id 以及源顶点和目标顶点 id 的格式。 +顶点 id 格式的修改也影响到了边的 Id 以及源顶点和目标顶点 id 的格式 EdgeId 是由 `src-vertex-id + direction + label + sort-values + tgt-vertex-id` 拼接而成，但是这里的顶点 id 类型不是通过引号区分的，而是根据前缀区分： @@ -59,11 +59,11 @@ g = graph.traversal() ##### Params -路径参数说明： +**路径参数说明：** - graph：待操作的图 -请求体说明： +**请求体说明：** - label：边类型名称，必填 - outV：源顶点 id，必填 @@ -124,15 +124,15 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges ##### Params -路径参数说明： +**路径参数说明：** - graph：待操作的图 -请求参数说明： +**请求参数说明：** - check_vertex：当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错，默认为 true -请求体说明： +**请求体说明：** - 边信息的列表 @@ -190,16 +190,16 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges/batch ##### Params -路径参数说明： +**路径参数说明：** - graph：待操作的图 - id：待操作的边 id -请求参数说明： +**请求参数说明：** - action：append 操作 -请求体说明： +**请求体说明：** - 边信息 @@ -219,7 +219,7 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action } ``` -> 注意：属性的取值是有三种类别的，分别是 single、set 和 list。如果是 single，表示增加或更新属性值；如果是 set 或 list，则表示追加属性值。 +> 注意：属性的取值是有三种类别的，分别是 single、set 和 list。如果是 single，表示增加或更新属性值；如果是 set 或 list，则表示追加属性值 ##### Response Status @@ -249,11 +249,11 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action ##### Params -路径参数说明： +**路径参数说明：** - graph：待操作的图 -请求体说明： +**请求体说明：** - edges：边信息的列表 - update_strategies：对于每个属性，可以单独设置其更新策略，包括： @@ -353,16 +353,16 @@ PUT http://127.0.0.1:8080/graphs/hugegraph/graph/edges/batch ##### Params -路径参数说明： +**路径参数说明：** - graph：待操作的图 - id：待操作的边 id -请求参数说明： +**请求参数说明：** - action：eliminate 操作 -请求体说明： +**请求体说明：** - 边信息 @@ -382,7 +382,7 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action } ``` -> 注意：这里会直接删除属性（删除 key 和所有 value），无论其属性的取值是 single、set 或 list。 +> 注意：这里会直接删除属性（删除 key 和所有 value），无论其属性的取值是 single、set 或 list ##### Response Status @@ -406,43 +406,44 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action ##### Params +**路径参数说明：** + +- graph：待操作的图 + +**请求参数说明：** + - vertex_id: 顶点 id -- direction: 边的方向 (OUT | IN | BOTH) +- direction: 边的方向 (OUT | IN | BOTH)，默认为 BOTH - label: 边的标签 - properties: 属性键值对 (根据属性查询的前提是预先建立了索引) +- keep_start_p: 是否支持范围匹配，默认为 false - offset：偏移，默认为 0 - limit: 查询数目，默认为 100 - page: 页号 -支持的查询有以下几种： - -- 提供 vertex_id 参数时，不可以使用参数 page，direction、label、properties 可选，offset 和 limit 可以 -限制结果范围 -- 不提供 vertex_id 参数时，label 和 properties 可选 - - 如果使用 page 参数，则：offset 参数不可用（不填或者为 0），direction 不可用，properties 最多只能有一个 - - 如果不使用 page 参数，则：offset 和 limit 可以用来限制结果范围，direction 参数忽略 - 属性键值对由 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 的边 | - -**查询与顶点 person:josh(vertex_id="1:josh") 相连且 label 为 created 的边** +| 表达式 | 说明 | +|------------------------------------|----------------------------------| +| 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 的边** ##### Method & Url ``` -GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:josh"&direction=BOTH&label=created&properties={} +GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:marko"&label=knows ``` ##### Response Status @@ -457,41 +458,41 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:josh"&direct { "edges": [ { - "id": "S1:josh>1>>S2:lop", - "label": "created", + "id": "S1:marko>1>>S1:josh", + "label": "knows", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", - "inV": "2:lop", - "outV": "1:josh", + "inV": "1:josh", + "inVLabel": "person", "properties": { - "date": "20091111", - "weight": 0.4 + "weight": 1.5, + "date": "20130221" } }, { - "id": "S1:josh>1>>S2:ripple", - "label": "created", + "id": "S1:marko>1>>S1:vadas", + "label": "knows", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", - "inV": "2:ripple", - "outV": "1:josh", + "inV": "1:vadas", + "inVLabel": "person", "properties": { - "date": "20171210", - "weight": 1 + "weight": 1.5, + "date": "20160111" } } ] } ``` -**分页查询所有边，获取第一页（page 不带参数值），限定 3 条** +**分页查询所有边，获取第一页（page 不带参数值），限定 2 条** ##### Method & Url ``` -GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=3 +GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=2 ``` ##### Response Status @@ -504,59 +505,46 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=3 ```json { - "edges": [{ - "id": "S1:peter>2>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:peter", - "properties": { - "weight": 0.2, - "date": "20170324" - } - }, - { - "id": "S1:josh>2>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:josh", - "properties": { - "weight": 0.4, - "date": "20091111" - } - }, - { - "id": "S1:josh>2>>S2:ripple", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:ripple", - "outV": "1:josh", - "properties": { - "weight": 1, - "date": "20171210" - } - } - ], - "page": "002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004" + "edges": [ + { + "id": "S1:marko>1>>S1:josh", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:josh", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20130221" + } + }, + { + "id": "S1:marko>1>>S1:vadas", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:vadas", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20160111" + } + } + ], + "page": "EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC" } ``` -返回的 body 里面是带有下一页的页号信息的，`"page": "002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004"`， -在查询下一页的时候将该值赋给 page 参数。 +返回的 body 里面是带有下一页的页号信息的，`"page": "EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC"`，在查询下一页的时候将该值赋给 page 参数 -**分页查询所有边，获取下一页（page 带上上一页返回的 page 值），限定 3 条** +**分页查询所有边，获取下一页（page 带上上一页返回的 page 值），限定 2 条** ##### Method & Url ``` -GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004&limit=3 +GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC&limit=2 ``` ##### Response Status @@ -569,58 +557,40 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=002500100753313a6a6f ```json { - "edges": [{ - "id": "S1:marko>1>20130220>S1:josh", - "label": "knows", - "type": "edge", - "inVLabel": "person", - "outVLabel": "person", - "inV": "1:josh", - "outV": "1:marko", - "properties": { - "weight": 1, - "date": "20130220" - } - }, - { - "id": "S1:marko>1>20160110>S1:vadas", - "label": "knows", - "type": "edge", - "inVLabel": "person", - "outVLabel": "person", - "inV": "1:vadas", - "outV": "1:marko", - "properties": { - "weight": 0.5, - "date": "20160110" - } - }, - { - "id": "S1:marko>2>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:marko", - "properties": { - "weight": 0.4, - "date": "20171210" - } - } - ], - "page": null + "edges": [ + { + "id": "S1:marko>2>>S2:lop", + "label": "created", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "2:lop", + "inVLabel": "software", + "properties": { + "weight": 1.0, + "date": "20171210" + } + } + ], + "page": null } ``` -此时`"page": null`表示已经没有下一页了 (注：后端为 Cassandra 时，为了性能考虑，返回页恰好为最后一页时，返回 `page` 值可能非空，通过该 `page` 再请求下一页数据时则返回 `空数据` 及 `page = null`，其他情况类似) +此时 `"page": null` 表示已经没有下一页了 + +> 注：后端为 Cassandra 时，为了性能考虑，返回页恰好为最后一页时，返回 `page` 值可能非空，通过该 `page` 再请求下一页数据时则返回 `空数据` 及 `page = null`，其他情况类似 #### 2.2.7 根据 Id 获取边 +**路径参数说明：** + +- graph：待操作的图 +- id：待操作的边 id + ##### Method & Url ``` -GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop +GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop ``` ##### Response Status @@ -633,16 +603,16 @@ GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop ```json { - "id": "S1:peter>1>>S2:lop", + "id": "S1:marko>2>>S2:lop", "label": "created", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", "inV": "2:lop", - "outV": "1:peter", + "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "weight": 1.0, + "date": "20171210" } } ``` @@ -651,14 +621,21 @@ GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop ##### Params -- label: 边类型，可选参数 +**路径参数说明：** + +- graph：待操作的图 +- id：待操作的边 id + +**请求参数说明：** + +- label: 边的标签 **仅根据 Id 删除边** ##### Method & Url ``` -DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop +DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop ``` ##### Response Status @@ -669,12 +646,12 @@ DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop **根据 Label + Id 删除边** -通过指定 Label 参数和 Id 来删除边时，一般来说其性能比仅根据 Id 删除会更好。 +通过指定 Label 参数和 Id 来删除边时，一般来说其性能比仅根据 Id 删除会更好 ##### Method & Url ``` -DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?label=person +DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>1>>S1:vadas?label=knows ``` ##### Response Status From 663b43024ab1376e35125d2dab63616a5d32c61e Mon Sep 17 00:00:00 2001 From: V_Galaxy <1904821183@qq.com> Date: Mon, 26 Jun 2023 14:22:34 +0800 Subject: [PATCH 3/4] doc: add example for edge properties query --- content/cn/docs/clients/restful-api/edge.md | 35 +++++++-------------- 1 file changed, 11 insertions(+), 24 deletions(-) diff --git a/content/cn/docs/clients/restful-api/edge.md b/content/cn/docs/clients/restful-api/edge.md index 46fe745ed..4af89f613 100644 --- a/content/cn/docs/clients/restful-api/edge.md +++ b/content/cn/docs/clients/restful-api/edge.md @@ -6,7 +6,7 @@ weight: 8 ### 2.2 Edge -顶点 id 格式的修改也影响到了边的 Id 以及源顶点和目标顶点 id 的格式 +顶点 id 格式的修改也影响到了边的 id 以及源顶点和目标顶点 id 的格式 EdgeId 是由 `src-vertex-id + direction + label + sort-values + tgt-vertex-id` 拼接而成，但是这里的顶点 id 类型不是通过引号区分的，而是根据前缀区分： @@ -130,7 +130,7 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges **请求参数说明：** -- check_vertex：当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错，默认为 true +- check_vertex：是否检查顶点存在 (true | false)，当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错，默认为 true **请求体说明：** @@ -262,7 +262,7 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action - UNION/INTERSECTION：仅支持 set 类型 - APPEND/ELIMINATE：仅支持 collection 类型 - OVERRIDE -- check_vertex：当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错，默认为 true +- check_vertex：是否检查顶点存在 (true | false)，当设置为 true 而待插入边的源顶点或目标顶点不存在时会报错，默认为 true - create_if_not_exist：目前只支持设定为 true ##### Method & Url @@ -416,7 +416,7 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action - direction: 边的方向 (OUT | IN | BOTH)，默认为 BOTH - label: 边的标签 - properties: 属性键值对 (根据属性查询的前提是预先建立了索引) -- keep_start_p: 是否支持范围匹配，默认为 false +- keep_start_p: 默认为 false，当设置为 true 后，不会自动转义范围匹配输入的表达式，例如此时 `properties={"age":"P.gt(0.8)"}` 会被理解为精确匹配，即 age 属性等于 "P.gt(0.8)" - offset：偏移，默认为 0 - limit: 查询数目，默认为 100 - page: 页号 @@ -438,12 +438,12 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action | P.textcontains(value) | 属性值包含给定 value 的边 (string 类型) | | P.contains(value) | 属性值包含给定 value 的边 (collection 类型) | -**查询与顶点 person:marko(vertex_id="1:marko") 相连且 label 为 knows 的边** +**查询与顶点 person:marko(vertex_id="1:marko") 相连且 label 为 knows 的且 date 属性等于 "20160111" 的边** ##### Method & Url ``` -GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:marko"&label=knows +GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:marko"&label=knows&properties={"date":"P.within(\"20160111\")"} ``` ##### Response Status @@ -457,19 +457,6 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:marko"&label ```json { "edges": [ - { - "id": "S1:marko>1>>S1:josh", - "label": "knows", - "type": "edge", - "outV": "1:marko", - "outVLabel": "person", - "inV": "1:josh", - "inVLabel": "person", - "properties": { - "weight": 1.5, - "date": "20130221" - } - }, { "id": "S1:marko>1>>S1:vadas", "label": "knows", @@ -580,7 +567,7 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=EoYxOm1hcmtvgggCAIQy > 注：后端为 Cassandra 时，为了性能考虑，返回页恰好为最后一页时，返回 `page` 值可能非空，通过该 `page` 再请求下一页数据时则返回 `空数据` 及 `page = null`，其他情况类似 -#### 2.2.7 根据 Id 获取边 +#### 2.2.7 根据 id 获取边 **路径参数说明：** @@ -617,7 +604,7 @@ GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop } ``` -#### 2.2.8 根据 Id 删除边 +#### 2.2.8 根据 id 删除边 ##### Params @@ -630,7 +617,7 @@ GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop - label: 边的标签 -**仅根据 Id 删除边** +**仅根据 id 删除边** ##### Method & Url @@ -644,9 +631,9 @@ DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop 204 ``` -**根据 Label + Id 删除边** +**根据 Label + id 删除边** -通过指定 Label 参数和 Id 来删除边时，一般来说其性能比仅根据 Id 删除会更好 +通过指定 Label 参数和 id 来删除边时，一般来说其性能比仅根据 id 删除会更好 ##### Method & Url From 86b07c1b19c981d32a5a38bbdcd3af61095247f2 Mon Sep 17 00:00:00 2001 From: V_Galaxy <1904821183@qq.com> Date: Wed, 28 Jun 2023 23:41:02 +0800 Subject: [PATCH 4/4] doc: sync edge api EN doc --- content/cn/docs/clients/restful-api/edge.md | 6 +- content/en/docs/clients/restful-api/edge.md | 571 ++++++++++---------- 2 files changed, 301 insertions(+), 276 deletions(-) diff --git a/content/cn/docs/clients/restful-api/edge.md b/content/cn/docs/clients/restful-api/edge.md index 4af89f613..e164a142b 100644 --- a/content/cn/docs/clients/restful-api/edge.md +++ b/content/cn/docs/clients/restful-api/edge.md @@ -569,6 +569,8 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=EoYxOm1hcmtvgggCAIQy #### 2.2.7 根据 id 获取边 +##### Params + **路径参数说明：** - graph：待操作的图 @@ -631,9 +633,9 @@ DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop 204 ``` -**根据 Label + id 删除边** +**根据 label + id 删除边** -通过指定 Label 参数和 id 来删除边时，一般来说其性能比仅根据 id 删除会更好 +通过指定 label 参数和 id 来删除边时，一般来说其性能比仅根据 id 删除会更好 ##### Method & Url diff --git a/content/en/docs/clients/restful-api/edge.md b/content/en/docs/clients/restful-api/edge.md index 5240c5ba9..b990a54a2 100644 --- a/content/en/docs/clients/restful-api/edge.md +++ b/content/en/docs/clients/restful-api/edge.md @@ -15,21 +15,64 @@ The EdgeId is formed by concatenating `src-vertex-id + direction + label + sort- -------------------------------------------------------------------------------- -The following examples assume that various schemas and vertex information mentioned above have been created. +The following example requires creating a graph `schema` based on the following `groovy` script: + +```groovy +import org.apache.hugegraph.HugeFactory +import org.apache.tinkerpop.gremlin.structure.T + +conf = "conf/graphs/hugegraph.properties" +graph = HugeFactory.open(conf) +schema = graph.schema() + +schema.propertyKey("name").asText().ifNotExist().create() +schema.propertyKey("age").asInt().ifNotExist().create() +schema.propertyKey("city").asText().ifNotExist().create() +schema.propertyKey("weight").asDouble().ifNotExist().create() +schema.propertyKey("lang").asText().ifNotExist().create() +schema.propertyKey("date").asText().ifNotExist().create() +schema.propertyKey("price").asInt().ifNotExist().create() + +schema.vertexLabel("person").properties("name", "age", "city").primaryKeys("name").ifNotExist().create() +schema.vertexLabel("software").properties("name", "lang", "price").primaryKeys("name").ifNotExist().create() +schema.indexLabel("personByCity").onV("person").by("city").secondary().ifNotExist().create() +schema.indexLabel("personByAgeAndCity").onV("person").by("age", "city").secondary().ifNotExist().create() +schema.indexLabel("softwareByPrice").onV("software").by("price").range().ifNotExist().create() +schema.edgeLabel("knows").sourceLabel("person").targetLabel("person").properties("date", "weight").ifNotExist().create() +schema.edgeLabel("created").sourceLabel("person").targetLabel("software").properties("date", "weight").ifNotExist().create() +schema.indexLabel("createdByDate").onE("created").by("date").secondary().ifNotExist().create() +schema.indexLabel("createdByWeight").onE("created").by("weight").range().ifNotExist().create() +schema.indexLabel("knowsByWeight").onE("knows").by("weight").range().ifNotExist().create() + +marko = graph.addVertex(T.label, "person", "name", "marko", "age", 29, "city", "Beijing") +vadas = graph.addVertex(T.label, "person", "name", "vadas", "age", 27, "city", "Hongkong") +lop = graph.addVertex(T.label, "software", "name", "lop", "lang", "java", "price", 328) +josh = graph.addVertex(T.label, "person", "name", "josh", "age", 32, "city", "Beijing") +ripple = graph.addVertex(T.label, "software", "name", "ripple", "lang", "java", "price", 199) +peter = graph.addVertex(T.label, "person", "name", "peter", "age", 35, "city", "Shanghai") + +graph.tx().commit() +g = graph.traversal() +``` #### 2.2.1 Creating an Edge -Params Explanation +##### Params + +**Path Parameter Description:** -- label: The name of the edge type, required. -- outV: The ID of the source vertex, required. -- inV: The ID of the target vertex, required. -- outVLabel: The type of the source vertex, required. -- inVLabel: The type of the target vertex, required. -- properties: The properties associated with the edge. The internal structure of the object is as follows: - 1. name: The name of the property. - 2. value: The value of the property. +- graph: The graph to operate on +**Request Body Description:** + +- label: The edge type name (required) +- outV: The source vertex id (required) +- inV: The target vertex id (required) +- outVLabel: The source vertex type (required) +- inVLabel: The target vertex type (required) +- properties: The properties associated with the edge. The internal structure of the object is as follows: + 1. name: The property name + 2. value: The property value ##### Method & Url @@ -42,13 +85,13 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges ```json { "label": "created", - "outV": "1:peter", + "outV": "1:marko", "inV": "2:lop", "outVLabel": "person", "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "date": "20171210", + "weight": 0.4 } } ``` @@ -63,16 +106,16 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges ```json { - "id": "S1:peter>1>>S2:lop", + "id": "S1:marko>2>>S2:lop", "label": "created", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", "inV": "2:lop", - "outV": "1:peter", + "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "weight": 0.4, + "date": "20171210" } } ``` @@ -81,7 +124,17 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges ##### Params -- check_vertex: Whether to check vertex existence (true | false). When set to true and the source or target vertex of the edge being inserted does not exist, an error will be reported. +**Path Parameter Description:** + +- graph: The graph to operate on + +**Request Parameter Description:** + +- check_vertex: Whether to check the existence of vertices (true | false). When set to true, an error will be thrown if the source or target vertices of the edge to be inserted do not exist. Default is true. + +**Request Body Description:** + +- List of edge information ##### Method & Url @@ -94,25 +147,25 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges/batch ```json [ { - "label": "created", - "outV": "1:peter", - "inV": "2:lop", + "label": "knows", + "outV": "1:marko", + "inV": "1:vadas", "outVLabel": "person", - "inVLabel": "software", + "inVLabel": "person", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "date": "20160110", + "weight": 0.5 } }, { "label": "knows", "outV": "1:marko", - "inV": "1:vadas", + "inV": "1:josh", "outVLabel": "person", "inVLabel": "person", "properties": { - "date": "2016-01-10", - "weight": 0.5 + "date": "20130220", + "weight": 1.0 } } ] @@ -128,17 +181,32 @@ POST http://localhost:8080/graphs/hugegraph/graph/edges/batch ```json [ - "S1:peter>1>>S2:lop", - "S1:marko>2>>S1:vadas" + "S1:marko>1>>S1:vadas", + "S1:marko>1>>S1:josh" ] ``` #### 2.2.3 Updating Edge Properties +##### Params + +**Path Parameter Description:** + +- graph: The graph to operate on +- id: The ID of the edge to be operated on + +**Request Parameter Description:** + +- action: The append action + +**Request Body Description:** + +- Edge information + ##### Method & Url ``` -PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action=append +PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=append ``` ##### Request Body @@ -151,7 +219,7 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action } ``` -> Note: There are three categories of property values: single, set, and list. If it is single, it means adding or updating the property value. If it is set or list, it means appending the property value. +> NOTE: There are three categories of property values: single, set, and list. If it is single, it means adding or updating the property value. If it is set or list, it means appending the property value. ##### Response Status @@ -163,60 +231,39 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action ```json { - "id": "S1:peter>1>>S2:lop", + "id": "S1:marko>2>>S2:lop", "label": "created", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", "inV": "2:lop", - "outV": "1:peter", + "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 1 + "weight": 1.0, + "date": "20171210" } } ``` #### 2.2.4 Batch Updating Edge Properties -##### Function Description +##### Params -Similar to batch updating vertex properties. +**Path Parameter Description:** -Assuming the original edge and its properties are: +- graph: The graph to operate on -```json -{ - "edges":[ - { - "id":"S1:josh>2>>S2:ripple", - "label":"created", - "type":"edge", - "outV":"1:josh", - "outVLabel":"person", - "inV":"2:ripple", - "inVLabel":"software", - "properties":{ - "weight":1, - "date":1512835200000 - } - }, - { - "id":"S1:marko>1>7JooBil0>S1:josh", - "label":"knows", - "type":"edge", - "outV":"1:marko", - "outVLabel":"person", - "inV":"1:josh", - "inVLabel":"person", - "properties":{ - "weight":1, - "date":1361289600000 - } - } - ] -} -``` +**Request Body Description:** + +- edges: List of edge information +- update_strategies: For each property, you can set its update strategy individually, including: + - SUM: Only supports number type + - BIGGER/SMALLER: Only supports date/number type + - UNION/INTERSECTION: Only supports set type + - APPEND/ELIMINATE: Only supports collection type + - OVERRIDE +- check_vertex: Whether to check the existence of vertices (true | false). When set to true, an error will be thrown if the source or target vertices of the edge to be inserted do not exist. Default is true. +- create_if_not_exist: Currently only supports setting to true ##### Method & Url @@ -228,38 +275,36 @@ PUT http://127.0.0.1:8080/graphs/hugegraph/graph/edges/batch ```json { - "edges":[ + "edges": [ { - "id":"S1:josh>2>>S2:ripple", - "label":"created", - "outV":"1:josh", - "outVLabel":"person", - "inV":"2:ripple", - "inVLabel":"software", - "properties":{ - "weight":0.1, - "date":1522835200000 + "label": "knows", + "outV": "1:marko", + "inV": "1:vadas", + "outVLabel": "person", + "inVLabel": "person", + "properties": { + "date": "20160111", + "weight": 1.0 } }, { - "id":"S1:marko>1>7JooBil0>S1:josh", - "label":"knows", - "outV":"1:marko", - "outVLabel":"person", - "inV":"1:josh", - "inVLabel":"person", - "properties":{ - "weight":0.2, - "date":1301289600000 + "label": "knows", + "outV": "1:marko", + "inV": "1:josh", + "outVLabel": "person", + "inVLabel": "person", + "properties": { + "date": "20130221", + "weight": 0.5 } } ], - "update_strategies":{ - "weight":"SUM", - "date":"BIGGER" + "update_strategies": { + "weight": "SUM", + "date": "OVERRIDE" }, "check_vertex": false, - "create_if_not_exist":true + "create_if_not_exist": true } ``` @@ -273,31 +318,31 @@ PUT http://127.0.0.1:8080/graphs/hugegraph/graph/edges/batch ```json { - "edges":[ + "edges": [ { - "id":"S1:josh>2>>S2:ripple", - "label":"created", - "type":"edge", - "outV":"1:josh", - "outVLabel":"person", - "inV":"2:ripple", - "inVLabel":"software", - "properties":{ - "weight":1.1, - "date":1522835200000 + "id": "S1:marko>1>>S1:vadas", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:vadas", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20160111" } }, { - "id":"S1:marko>1>7JooBil0>S1:josh", - "label":"knows", - "type":"edge", - "outV":"1:marko", - "outVLabel":"person", - "inV":"1:josh", - "inVLabel":"person", - "properties":{ - "weight":1.2, - "date":1301289600000 + "id": "S1:marko>1>>S1:josh", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:josh", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20130221" } } ] @@ -306,10 +351,25 @@ PUT http://127.0.0.1:8080/graphs/hugegraph/graph/edges/batch #### 2.2.5 Deleting Edge Properties +##### Params + +**Path Parameter Description:** + +- graph: The graph to operate on +- id: The ID of the edge to be operated on + +**Request Parameter Description:** + +- action: The eliminate action + +**Request Body Description:** + +- Edge information + ##### Method & Url ``` -PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action=eliminate +PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=eliminate ``` ##### Request Body @@ -322,28 +382,23 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action } ``` -> Note: This will directly delete the properties (removing the key and all values), regardless of whether the property values are single, set, or list. +> NOTE: This will directly delete the properties (removing the key and all values), regardless of whether the property values are single, set, or list. ##### Response Status ```json -200 +400 ``` ##### Response Body +It is not possible to delete an attribute that is not set as nullable. + ```json { - "id": "S1:peter>1>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:peter", - "properties": { - "date": "20170324" - } + "exception": "class java.lang.IllegalArgumentException", + "message": "Can't remove non-null edge property 'p[weight->1.0]'", + "cause": "" } ``` @@ -351,42 +406,44 @@ PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?action ##### Params +**Path Parameter:** + +- graph: The graph to operate on + +**Request Parameters:** + - vertex_id: Vertex ID -- direction: Direction of the edge (OUT | IN | BOTH) +- direction: Edge direction (OUT | IN | BOTH), default is BOTH - label: Edge label -- properties: Key-value pairs of properties (previously indexed for property-based queries) +- properties: Key-value pairs of properties (requires pre-built indexes for property queries) +- keep_start_p: Default is false. When set to true, the range matching input expression will not be automatically escaped. For example, `properties={"age":"P.gt(0.8)"}` will be interpreted as an exact match, i.e., the age property is equal to "P.gt(0.8)" - offset: Offset, default is 0 -- limit: Number of results to query, default is 100 +- limit: Number of queries, default is 100 - page: Page number -The supported query options are as follows: - -- When the vertex_id parameter is provided, the page parameter cannot be used. The direction, label, and properties parameters are optional, while offset and limit can be used to restrict the result range. -- When the vertex_id parameter is not provided, the label and properties parameters are optional. - - If the page parameter is used: the offset parameter is not available (either not provided or set to 0), the direction parameter is not available, and at most one property can be specified. - - If the page parameter is not used: the offset and limit parameters can be used to restrict the result range, and the direction parameter is ignored. - -Property key-value pairs consist of the attribute name and attribute value in JSON format. Multiple property key-value pairs are allowed as query conditions. The attribute value supports exact matching, range matching, and fuzzy matching. For exact matching, it is in the form `properties={"weight": 0.8}`. For range matching, it is in the form `properties={"age": "P.gt(0.8)"}`. For fuzzy matching, it is in the form `properties={"city": "P.textcontains("ChengDu China")}`. The supported expressions for range matching are as follows: - -| Expression | Description | -| ------------------------------------ | ------------------------------------ | -| P.eq(number) | Edges with attribute value equal to `number` | -| P.neq(number) | Edges with attribute value not equal to `number` | -| P.lt(number) | Edges with attribute value less than `number` | -| P.lte(number) | Edges with attribute value less than or equal to `number` | -| P.gt(number) | Edges with attribute value greater than `number` | -| P.gte(number) | Edges with attribute value greater than or equal to `number` | -| P.between(number1, number2) | Edges with attribute value greater than or equal to `number1` and less than `number2` | -| P.inside(number1, number2) | Edges with attribute value greater than `number1` and less than `number2` | -| P.outside(number1, number2) | Edges with attribute value less than `number1` and greater than `number2` | -| P.within(value1, value2, value3, ...) | Edges with attribute value equal to any of the given `values` | - -**Query for edges connected to vertex person:josh (vertex_id="1:josh") with label created** +Key-value pairs of properties consist of the property name and value in JSON format. Multiple key-value pairs are allowed as query conditions. Property values support exact matching and range matching. For exact matching, it is in the form `properties={"weight":0.8}`. For range matching, it is in the form `properties={"age":"P.gt(0.8)"}`. The expressions supported by range matching are as follows: + +| Expression | Description | +|------------------------------------|----------------------------------------------------------------------------------| +| P.eq(number) | Edges with property value equal to number | +| P.neq(number) | Edges with property value not equal to number | +| P.lt(number) | Edges with property value less than number | +| P.lte(number) | Edges with property value less than or equal to number | +| P.gt(number) | Edges with property value greater than number | +| P.gte(number) | Edges with property value greater than or equal to number | +| P.between(number1,number2) | Edges with property value greater than or equal to number1 and less than number2 | +| P.inside(number1,number2) | Edges with property value greater than number1 and less than number2 | +| P.outside(number1,number2) | Edges with property value less than number1 and greater than number2 | +| P.within(value1,value2,value3,...) | Edges with property value equal to any of the given values | +| P.textcontains(value) | Edges with property value containing the given value (string type) | +| P.contains(value) | Edges with property value containing the given value (collection type) | + +**Edges connected to the vertex person:marko(vertex_id="1:marko") with label knows and date property equal to "20160111"** ##### Method & Url ``` -GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:josh"&direction=BOTH&label=created&properties={} +GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:marko"&label=knows&properties={"date":"P.within(\"20160111\")"} ``` ##### Response Status @@ -401,41 +458,28 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:josh"&direct { "edges": [ { - "id": "S1:josh>1>>S2:lop", - "label": "created", + "id": "S1:marko>1>>S1:vadas", + "label": "knows", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", - "inV": "2:lop", - "outV": "1:josh", + "inV": "1:vadas", + "inVLabel": "person", "properties": { - "date": "20091111", - "weight": 0.4 - } - }, - { - "id": "S1:josh>1>>S2:ripple", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:ripple", - "outV": "1:josh", - "properties": { - "date": "20171210", - "weight": 1 + "weight": 1.5, + "date": "20160111" } } ] } ``` -**Paginated query for all edges, fetching the first page (page without a parameter value), limited to 3 records** +**Paginate and retrieve all edges, get the first page (page without parameter value), limit to 2 entries** ##### Method & Url ``` -GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=3 +GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=2 ``` ##### Response Status @@ -448,58 +492,46 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=3 ```json { - "edges": [{ - "id": "S1:peter>2>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:peter", - "properties": { - "weight": 0.2, - "date": "20170324" - } - }, - { - "id": "S1:josh>2>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:josh", - "properties": { - "weight": 0.4, - "date": "20091111" - } - }, - { - "id": "S1:josh>2>>S2:ripple", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:ripple", - "outV": "1:josh", - "properties": { - "weight": 1, - "date": "20171210" - } - } - ], - "page": "002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004" + "edges": [ + { + "id": "S1:marko>1>>S1:josh", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:josh", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20130221" + } + }, + { + "id": "S1:marko>1>>S1:vadas", + "label": "knows", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "1:vadas", + "inVLabel": "person", + "properties": { + "weight": 1.5, + "date": "20160111" + } + } + ], + "page": "EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC" } ``` -The returned body contains the information of the next page, `"page": "002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004"`. When querying the next page, assign this value to the page parameter. +The returned body contains the page number information for the next page, `"page": "EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC"`. When querying the next page, assign this value to the page parameter. -**Paginated query for all edges, fetching the next page (page with the value returned from the previous page), limited to 3 records** +**Paginate and retrieve all edges, get the next page (include the page value returned from the previous page), limit to 2 entries** ##### Method & Url ``` -GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=002500100753313a6a6f73681210010004000000020953323a726970706c65f07ffffffcf07ffffffd8460d63f4b398dd2721ed4fdb7716b420004&limit=3 +GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC&limit=2 ``` ##### Response Status @@ -512,58 +544,42 @@ GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=002500100753313a6a6f ```json { - "edges": [{ - "id": "S1:marko>1>20130220>S1:josh", - "label": "knows", - "type": "edge", - "inVLabel": "person", - "outVLabel": "person", - "inV": "1:josh", - "outV": "1:marko", - "properties": { - "weight": 1, - "date": "20130220" - } - }, - { - "id": "S1:marko>1>20160110>S1:vadas", - "label": "knows", - "type": "edge", - "inVLabel": "person", - "outVLabel": "person", - "inV": "1:vadas", - "outV": "1:marko", - "properties": { - "weight": 0.5, - "date": "20160110" - } - }, - { - "id": "S1:marko>2>>S2:lop", - "label": "created", - "type": "edge", - "inVLabel": "software", - "outVLabel": "person", - "inV": "2:lop", - "outV": "1:marko", - "properties": { - "weight": 0.4, - "date": "20171210" - } - } - ], - "page": null + "edges": [ + { + "id": "S1:marko>2>>S2:lop", + "label": "created", + "type": "edge", + "outV": "1:marko", + "outVLabel": "person", + "inV": "2:lop", + "inVLabel": "software", + "properties": { + "weight": 1.0, + "date": "20171210" + } + } + ], + "page": null } ``` -When `"page": null` is returned, it indicates that there are no more pages available. (Note: When the backend is Cassandra, for performance considerations, if the returned page happens to be the last page, the `page` value may not be empty. When requesting the next page data using that `page` value, it will return `empty data` and `page = null`. Similar situations apply for other cases.) +When `"page": null` is returned, it indicates that there are no more pages available. + +> NOTE: When the backend is Cassandra, for performance considerations, if the returned page happens to be the last page, the `page` value may not be empty. When requesting the next page data using that `page` value, it will return `empty data` and `page = null`. Similar situations apply for other cases. #### 2.2.7 Fetching Edge by ID +##### Params + +**Path parameter description:** + +- graph: The graph to be operated on. +- id: The ID of the edge to be operated on. + ##### Method & Url ``` -GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop +GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop ``` ##### Response Status @@ -576,16 +592,16 @@ GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop ```json { - "id": "S1:peter>1>>S2:lop", + "id": "S1:marko>2>>S2:lop", "label": "created", "type": "edge", - "inVLabel": "software", + "outV": "1:marko", "outVLabel": "person", "inV": "2:lop", - "outV": "1:peter", + "inVLabel": "software", "properties": { - "date": "2017-5-18", - "weight": 0.2 + "weight": 1.0, + "date": "20171210" } } ``` @@ -594,14 +610,21 @@ GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop ##### Params -- label: Edge type, optional parameter +**Path parameter description:** + +- graph: The graph to be operated on. +- id: The ID of the edge to be operated on. + +**Request parameter description:** + +- label: The label of the edge. **Deleting Edge by ID only** ##### Method & Url ``` -DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop +DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop ``` ##### Response Status @@ -610,14 +633,14 @@ DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop 204 ``` -**Deleting Edge by Label+ID** +**Deleting Edge by Label + ID** In general, specifying the Label parameter along with the ID to delete an edge will provide better performance compared to deleting by ID only. ##### Method & Url ``` -DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:peter>1>>S2:lop?label=person +DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>1>>S1:vadas?label=knows ``` ##### Response Status