Edge API

2.2 Edge

The modification of the vertex ID format also affects the ID of the edge, as well as the formats of the source vertex and target vertex IDs.

The EdgeId is formed by concatenating src-vertex-id + direction + label + sort-values + tgt-vertex-id, but the vertex ID types are not distinguished by quotation marks here. Instead, they are distinguished by prefixes:

  • When the ID type is number, the vertex ID in the EdgeId has a prefix L, like “L123456>1»L987654”.
  • When the ID type is string, the vertex ID in the EdgeId has a prefix S, like “S1:peter>1»S2:lop”.

The following example requires creating a graph schema based on the following groovy script:

  1. import org.apache.hugegraph.HugeFactory
  2. import org.apache.tinkerpop.gremlin.structure.T
  4. conf = "conf/graphs/hugegraph.properties"
  5. graph = HugeFactory.open(conf)
  6. schema = graph.schema()
  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()
  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()
  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")
  34. graph.tx().commit()
  35. g = graph.traversal()

2.2.1 Creating an Edge

Params

Path Parameter Description:

  • 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
  1. POST http://localhost:8080/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
  1. 201
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 Creating Multiple Edges

Params

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
  1. POST http://localhost:8080/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
  1. 201
Response Body
  1. [
  2.     "S1:marko>1>>S1:vadas",
  3.     "S1:marko>1>>S1:josh"
  4. ]

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
  1. PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=append
Request Body
  1. {
  2.     "properties": {
  3.         "weight": 1.0
  4.     }
  5. }

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
  1. 200
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 Batch Updating Edge Properties

Params

Path Parameter Description:

  • graph: The graph to operate on

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
  1. PUT http://127.0.0.1:8080/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
  1. 200
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 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
  1. PUT http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop?action=eliminate
Request Body
  1. {
  2.     "properties": {
  3.         "weight": 1.0
  4.     }
  5. }

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
  1. 400
Response Body

It is not possible to delete an attribute that is not set as 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 Fetching Edges that Match the Criteria

Params

Path Parameter:

  • graph: The graph to operate on

Request Parameters:

  • vertex_id: Vertex ID
  • direction: Edge direction (OUT | IN | BOTH), default is BOTH
  • label: Edge label
  • 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 queries, default is 100
  • page: Page number

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:

ExpressionDescription
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
  1. GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?vertex_id="1:marko"&label=knows&properties={"date":"P.within(\"20160111\")"}
Response Status
  1. 200
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. }

Paginate and retrieve all edges, get the first page (page without parameter value), limit to 2 entries

Method & Url
  1. GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page&limit=2
Response Status
  1. 200
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. }

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.

Paginate and retrieve all edges, get the next page (include the page value returned from the previous page), limit to 2 entries

Method & Url
  1. GET http://127.0.0.1:8080/graphs/hugegraph/graph/edges?page=EoYxOm1hcmtvgggCAIQyOmxvcAAAAAAAAAAC&limit=2
Response Status
  1. 200
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. }

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
  1. GET http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop
Response Status
  1. 200
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 Deleting Edge by ID

Params

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
  1. DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>2>>S2:lop
Response Status
  1. 204

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
  1. DELETE http://localhost:8080/graphs/hugegraph/graph/edges/S1:marko>1>>S1:vadas?label=knows
Response Status
  1. 204

Last modified June 29, 2023: doc: update outdated doc for edge api (#276) (59f96c04)