ArangoDB v3.4 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Latest Docs

Handling Edges

Examples will explain the REST API for manipulating edges of the graph module on the knows graph:

Social Example Graph

Create an edge

Creates an edge in an existing graph

POST /_api/gharial/{graph}/edge/{collection}

Path Parameters

  • graph (string, required): The name of the graph.

  • collection (string, required): The name of the edge collection the edge belongs to.

Query Parameters

  • waitForSync (boolean, optional): Define if the request should wait until synced to disk.

  • returnNew (boolean, optional): Define if the response should contain the complete new version of the document.

Request Body

  • _from (string, required): The source vertex of this edge. Has to be valid within the used edge definition.

  • _to (string, required): The target vertex of this edge. Has to be valid within the used edge definition.

Creates a new edge in the collection. Within the body the edge has to contain a _from and _to value referencing to valid vertices in the graph. Furthermore the edge has to be valid in the definition of the used edge collection.

Responses

HTTP 201: Returned if the edge could be created and waitForSync is true.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • edge (object): The internal attributes for the edge.

  • new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

HTTP 202: Returned if the request was successful but waitForSync is false.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • edge (object): The internal attributes for the edge.

  • new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

HTTP 400: Returned if the input document is invalid. This can for instance be the case if _from or _to is mising.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

HTTP 403: Returned if your user has insufficient rights. In order to insert edges into the graph you at least need to have the following privileges:

  1. Read Only access on the Database.
  2. Write access on the given collection.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

HTTP 404: Returned in any of the following cases:

  • no graph with this name could be found.
  • this edge collection is not part of the graph.

  • either _from or _to vertex does not exist.

    • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

    • code (integer): The response code.

    • errorNum (integer): ArangoDB error number for the error that occured.

    • errorMessage (string): A message created for this error.

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation <<EOF
{ 
  "type" : "friend", 
  "_from" : "female/alice", 
  "_to" : "female/diana" 
}
EOF

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
etag: _bHcRDFW---
x-content-type-options: nosniff
Show response body

Get an edge

fetch an edge

GET /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

  • graph (string, required): The name of the graph.

  • collection (string, required): The name of the edge collection the edge belongs to.

  • edge (string, required): The _key attribute of the edge.

Query Parameters

  • rev (string, optional): Must contain a revision. If this is set a document is only returned if it has exactly this revision. Also see if-match header as an alternative to this.

Header Parameters

  • if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is returned, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

  • if-none-match (string, optional): If the “If-None-Match” header is given, then it must contain exactly one Etag. The document is returned, only if it has a different revision as the given Etag. Otherwise a HTTP 304 is returned.

Gets an edge from the given collection.

Responses

HTTP 200: Returned if the edge could be found.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • edge (object): The complete edge.

HTTP 304: Returned if the if-none-match header is given and the currently stored edge still has this revision value. So there was no update between the last time the edge was fetched by the caller.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

HTTP 403: Returned if your user has insufficient rights. In order to update vertices in the graph you at least need to have the following privileges:

  1. Read Only access on the Database.
  2. Read Only access on the given collection.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

  • No graph with this name could be found.
  • This collection is not part of the graph.

  • The edge does not exist.

    • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

    • code (integer): The response code.

    • errorNum (integer): ArangoDB error number for the error that occured.

    • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

Examples

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/edge/relation/67612

HTTP/1.1 OK
content-type: application/json; charset=utf-8
etag: _bHcRDVy--A
x-content-type-options: nosniff
Show response body

Examples will explain the API on the social graph:

Social Example Graph

Modify an edge

modify an existing edge

PATCH /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

  • graph (string, required): The name of the graph.

  • collection (string, required): The name of the edge collection the edge belongs to.

  • edge (string, required): The _key attribute of the vertex.

Query Parameters

  • waitForSync (boolean, optional): Define if the request should wait until synced to disk.

  • keepNull (boolean, optional): Define if values set to null should be stored. By default (true) the given documents attribute(s) will be set to null. If this parameter is false the attribute(s) will instead be deleted from the document.

  • returnOld (boolean, optional): Define if a presentation of the deleted document should be returned within the response object.

  • returnNew (boolean, optional): Define if a presentation of the new document should be returned within the response object.

Header Parameters

  • if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is updated, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

Request Body

(object, required)

The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged.

Updates the data of the specific edge in the collection.

Responses

HTTP 200: Returned if the edge could be updated, and waitForSync is false.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • edge (object): The internal attributes for the edge.

  • new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

HTTP 202: Returned if the request was successful but waitForSync is false.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • edge (object): The internal attributes for the edge.

  • new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

HTTP 403: Returned if your user has insufficient rights. In order to update edges in the graph you at least need to have the following privileges:

  1. Read Only access on the Database.
  2. Write access on the given collection.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

  • No graph with this name could be found.
  • This collection is not part of the graph.
  • The edge to update does not exist.

  • either _from or _to vertex does not exist (if updated).

    • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

    • code (integer): The response code.

    • errorNum (integer): ArangoDB error number for the error that occured.

    • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

Examples

shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation/67992 <<EOF
{ 
  "since" : "01.01.2001" 
}
EOF

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
etag: _bHcRDkq--_
x-content-type-options: nosniff
Show response body

Replace an edge

replace the content of an existing edge

PUT /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

  • graph (string, required): The name of the graph.

  • collection (string, required): The name of the edge collection the edge belongs to.

  • edge (string, required): The _key attribute of the vertex.

Query Parameters

  • waitForSync (boolean, optional): Define if the request should wait until synced to disk.

  • keepNull (boolean, optional): Define if values set to null should be stored. By default the key is not removed from the document.

  • returnOld (boolean, optional): Define if a presentation of the deleted document should be returned within the response object.

  • returnNew (boolean, optional): Define if a presentation of the new document should be returned within the response object.

Header Parameters

  • if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is updated, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

Request Body

  • _from (string, required): The source vertex of this edge. Has to be valid within the used edge definition.

  • _to (string, required): The target vertex of this edge. Has to be valid within the used edge definition.

Replaces the data of an edge in the collection.

Responses

HTTP 201: Returned if the request was successful but waitForSync is true.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • edge (object): The internal attributes for the edge

  • new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

HTTP 202: Returned if the request was successful but waitForSync is false.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • edge (object): The internal attributes for the edge

  • new (object): The complete newly written edge document. Includes all written attributes in the request body and all internal attributes generated by ArangoDB. Will only be present if returnNew is true.

  • old (object): The complete overwritten edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

HTTP 403: Returned if your user has insufficient rights. In order to replace edges in the graph you at least need to have the following privileges:

  1. Read Only access on the Database.
  2. Write access on the given collection.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

  • No graph with this name could be found.
  • This collection is not part of the graph.
  • The edge to replace does not exist.

  • either _from or _to vertex does not exist.

    • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

    • code (integer): The response code.

    • errorNum (integer): ArangoDB error number for the error that occured.

    • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

Examples

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/edge/relation/68042 <<EOF
{ 
  "type" : "divorced", 
  "_from" : "female/alice", 
  "_to" : "male/bob" 
}
EOF

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
etag: _bHcRDma--_
x-content-type-options: nosniff
Show response body

Remove an edge

removes an edge from graph

DELETE /_api/gharial/{graph}/edge/{collection}/{edge}

Path Parameters

  • graph (string, required): The name of the graph.

  • collection (string, required): The name of the edge collection the edge belongs to.

  • edge (string, required): The _key attribute of the edge.

Query Parameters

  • waitForSync (boolean, optional): Define if the request should wait until synced to disk.

  • returnOld (boolean, optional): Define if a presentation of the deleted document should be returned within the response object.

Header Parameters

  • if-match (string, optional): If the “If-Match” header is given, then it must contain exactly one Etag. The document is updated, if it has the same revision as the given Etag. Otherwise a HTTP 412 is returned. As an alternative you can supply the Etag in an attribute rev in the URL.

Removes an edge from the collection.

Responses

HTTP 200: Returned if the edge could be removed.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • removed (boolean): Is set to true if the remove was successful.

  • old (object): The complete deleted edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

HTTP 202: Returned if the request was successful but waitForSync is false.

  • error (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • removed (boolean): Is set to true if the remove was successful.

  • old (object): The complete deleted edge document. Includes all attributes stored before this operation. Will only be present if returnOld is true.

HTTP 403: Returned if your user has insufficient rights. In order to delete vertices in the graph you at least need to have the following privileges:

  1. Read Only access on the Database.
  2. Write access on the given collection.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

HTTP 404: Returned in the following cases:

  • No graph with this name could be found.
  • This collection is not part of the graph.

  • The edge to remove does not exist.

    • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

    • code (integer): The response code.

    • errorNum (integer): ArangoDB error number for the error that occured.

    • errorMessage (string): A message created for this error.

HTTP 412: Returned if if-match header is given, but the stored documents revision is different.

  • error (boolean): Flag if there was an error (true) or not (false). It is true in this response.

  • code (integer): The response code.

  • errorNum (integer): ArangoDB error number for the error that occured.

  • errorMessage (string): A message created for this error.

Examples

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social/edge/relation/67427

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body
❮  Vertices

© ArangoDB - the native multi-model NoSQL database