Skip to content

Edge API

Edge REST API: Create, query, update, and delete relationship data between vertices with support for batch operations and directional queries.

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”.

Edge IDs use Server’s raw edge ID format; escape URL reserved characters without additional JSON quotes. Do not apply vertex ID encoding rules to edge IDs. Append properties using PUT .../edges/{id}?action=append with the corresponding JSON properties body. When deleting an edge by ID, supply the label parameter required by the backend: DELETE .../edges/{id}?label={label}.

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

 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 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
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 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
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 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
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}

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
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 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
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 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
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}

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
1400
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 (see index coverage below)
  • 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

Without vertex_id, a properties query searches edges globally. When label is specified, that label needs a property index compatible with the query conditions; for a sub-edge label without one, a compatible index on its query-visible parent label is used and edges of sibling sub-labels are filtered out.

Candidate labels are edge labels that can hold edges and declare all queried non-OLAP properties, including labels with no edges yet. Labels hidden from normal queries, including those being deleted, are excluded from the candidate set and do not need index coverage. If all candidate labels are hidden or being deleted (or the specified label itself is hidden or being deleted), the query returns empty without raising an index error. If no schema label declares the queried properties, the index error still applies.

When label is omitted: a base (parent) edge label has no direct edges and does not need a separate index when all its sub-labels are covered. A compatible index on a query-visible parent label covers its sub-labels; alternatively, compatible indexes on every candidate sub-label are sufficient. Indexes on parents excluded due to hiding or deletion cannot provide this coverage. A label index alone does not mean the property is indexed.

Error trigger rules: when query values are type-compatible, missing a matching index or covering only some candidate labels raises an index error; only full coverage proceeds through the index. When query values are type-incompatible, a matching index may return an empty result (partial-coverage check skipped); with no matching index, the index error still applies. The query never falls back to a full scan.

Note

The partial-coverage error, parent-index fallback for sub-edge labels, and the empty result for hidden or deleting candidate labels apply starting from 1.8.0. Earlier versions use only indexes on the specified label, return only matches from indexed labels when label is omitted, and raise an index error when no label has a compatible index.

With vertex_id, the query filters that vertex’s adjacent edges; the global index-coverage requirement above does not apply.

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
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}

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

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}

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
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}

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

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
1DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph/edges/S1:marko>1>>S1:vadas?label=knows
Response Status
1204
Last modified 2026-11-01 · docs: clarify Server and Hubble HTTP API contracts (#552) (7d1737b50)