Manage your graphs

The graph module provides functions dealing with graph structures. Examples will explain the REST API on the social graph:

Social Example Graph

List all graphs

Lists all graphs known to the graph module.

GET /_api/gharial

Lists all graphs stored in this database.

HTTP 200 Is returned if the module is available and the graphs could be listed.

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

  • code: The response code.

  • graphs:

    • graph: The information about the newly created graph

    • name: The name of the graph

    • edgeDefinitions: An array of definitions for the relations of the graph. Each has the following type:

    • orphanCollections: An array of additional vertex collections. Documents within these collections do not have edges within this graph.

    • numberOfShards: Number of shards created for every new collection in the graph.

    • replicationFactor: The replication factor used for every new collection in the graph.

    • _id: The internal id value of this graph.

    • _rev: The revision of this graph. Can be used to make sure to not override concurrent modifications to this graph.

    • isSmart: Flag if the graph is a SmartGraph (Enterprise Edition only) or not.

    • smartGraphAttribute: The name of the sharding attribute in smart graph case (Enterprise Edition only)

Examples

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Create a graph

Create a new graph in the graph module.

POST /_api/gharial

Query Parameters

  • waitForSync (optional): define if the request should wait until everything is synced to disc. Will change the success response code.

A JSON object with these properties is required:

  • name: Name of the graph.

  • edgeDefinitions: An array of definitions for the relations of the graph. Each has the following type:

  • isSmart: Define if the created graph should be smart. This only has effect in Enterprise Edition.

  • options: a JSON object to define options for creating collections within this graph. It can contain the following attributes:

    • smartGraphAttribute: Only has effect in Enterprise Edition and it is required if isSmart is true. The attribute name that is used to smartly shard the vertices of a graph. Every vertex in this SmartGraph has to have this attribute. Cannot be modified later.

    • numberOfShards: The number of shards that is used for every collection within this graph. Cannot be modified later.

    • replicationFactor: The replication factor used when initially creating collections for this graph.

The creation of a graph requires the name of the graph and a definition of its edges. See also edge definitions.

HTTP 201 Is returned if the graph could be created and waitForSync is enabled for the _graphs collection, or given in the request. The response body contains the graph configuration that has been stored.

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

  • code: The response code.

  • graph: The information about the newly created graph.

HTTP 202 Is returned if the graph could be created and waitForSync is disabled for the _graphs collection and not given in the request. The response body contains the graph configuration that has been stored.

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

  • code: The response code.

  • graph: The information about the newly created graph.

HTTP 400 Returned if the request is in a wrong format.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

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

  1. Administrate access on the Database.
  2. Read Only access on every collection used within this graph.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 409 Returned if there is a conflict storing the graph. This can occur either if a graph with this name is already stored, or if there is one edge definition with a the same edge collection but a different signature used in any other graph.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial <<EOF
{ 
  "name" : "myGraph", 
  "edgeDefinitions" : [ 
    { 
      "collection" : "edges", 
      "from" : [ 
        "startVertices" 
      ], 
      "to" : [ 
        "endVertices" 
      ] 
    } 
  ] 
}
EOF

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
etag: _YwlovMG--B
x-content-type-options: nosniff

Show response body
shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial <<EOF
{ 
  "name" : "myGraph", 
  "edgeDefinitions" : [ 
    { 
      "collection" : "edges", 
      "from" : [ 
        "startVertices" 
      ], 
      "to" : [ 
        "endVertices" 
      ] 
    } 
  ], 
  "isSmart" : true, 
  "options" : { 
    "replicationFactor" : 2, 
    "numberOfShards" : 9, 
    "smartGraphAttribute" : "region" 
  } 
}
EOF

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

Show response body

Get a graph

Get a graph from the graph module.

GET /_api/gharial/{graph}

Path Parameters

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

Selects information for a given graph. Will return the edge definitions as well as the orphan collections. Or returns a 404 if the graph does not exist.

HTTP 200 Returns the graph if it could be found. The result will have the following format:

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

  • code: The response code.

  • graph: The information about the newly created graph

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/myGraph

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Drop a graph

delete an existing graph

DELETE /_api/gharial/{graph}

Path Parameters

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

Query Parameters

  • dropCollections (optional): Drop collections of this graph as well. Collections will only be dropped if they are not used in other graphs.

Drops an existing graph object by name. Optionally all collections not used by other graphs can be dropped as well.

  • 201: Is returned if the graph could be dropped and waitForSync is enabled for the _graphs collection, or given in the request.

  • 202: Is returned if the graph could be dropped and waitForSync is disabled for the _graphs collection and not given in the request.

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

  1. Administrate access on the Database.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/gharial/social?dropCollections=true

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

List vertex collections

Lists all vertex collections used in this graph.

GET /_api/gharial/{graph}/vertex

Path Parameters

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

Lists all vertex collections within this graph.

HTTP 200 Is returned if the collections could be listed.

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

  • code: The response code.

  • collections: The list of all vertex collections within this graph. Includes collections in edgeDefinitions as well as orphans.

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Add vertex collection

Add an additional vertex collection to the graph.

POST /_api/gharial/{graph}/vertex

Path Parameters

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

Adds a vertex collection to the set of orphan collections of the graph. If the collection does not exist, it will be created.

HTTP 201 Is returned if the collection could be created and waitForSync is enabled for the _graphs collection, or given in the request. The response body contains the graph configuration that has been stored.

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

  • code: The response code.

  • graph: The information about the modified graph.

HTTP 202 Is returned if the collection could be created and waitForSync is disabled for the _graphs collection, or given in the request. The response body contains the graph configuration that has been stored.

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

  • code: The response code.

  • graph: The information about the newly created graph

HTTP 400 Returned if the request is in an invalid format.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

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

  1. Administrate access on the Database.
  2. Read Only access on every collection used within this graph.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/gharial/social/vertex <<EOF
{ 
  "collection" : "otherVertices" 
}
EOF

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
etag: _Ywlougm--B
x-content-type-options: nosniff

Show response body

Remove vertex collection

Remove a vertex collection form the graph.

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

Path Parameters

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

  • collection (required): The name of the vertex collection.

Query Parameters

  • dropCollection (optional): Drop the collection as well. Collection will only be dropped if it is not used in other graphs.

Removes a vertex collection from the graph and optionally deletes the collection, if it is not used in any other graph. It can only remove vertex collections that are no longer part of edge definitions, if they are used in edge definitions you are required to modify those first.

HTTP 200 Returned if the vertex collection was removed from the graph successfully and waitForSync is true.

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

  • code: The response code.

  • graph: The information about the newly created graph

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

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

  • code: The response code.

  • graph: The information about the newly created graph

HTTP 400 Returned if the vertex collection is still used in an edge definition. In this case it cannot be removed from the graph yet, it has to be removed from the edge definition first.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 403 Returned if your user has insufficient rights. In order to drop a vertex you at least need to have the following privileges:

  1. Administrate access on the Database.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

You can remove vertex collections that are not used in any edge collection:

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

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

Show response body

You cannot remove vertex collections that are used in edge collections:

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

HTTP/1.1 Bad Request
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

List edge definitions

Lists all edge definitions

GET /_api/gharial/{graph}/edge

Path Parameters

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

Lists all edge collections within this graph.

HTTP 200 Is returned if the edge definitions could be listed.

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

  • code: The response code.

  • collections: The list of all vertex collections within this graph. Includes collections in edgeDefinitions as well as orphans.

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Add edge definition

Add a new edge definition to the graph

POST /_api/gharial/{graph}/edge

Path Parameters

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

A JSON object with these properties is required:

  • collection: The name of the edge collection to be used.

  • from: One or many vertex collections that can contain source vertices.

  • to: One or many vertex collections that can contain target vertices.

Adds an additional edge definition to the graph.

This edge definition has to contain a collection and an array of each from and to vertex collections. An edge definition can only be added if this definition is either not used in any other graph, or it is used with exactly the same definition. It is not possible to store a definition “e” from “v1” to “v2” in the one graph, and “e” from “v2” to “v1” in the other graph.

HTTP 201 Returned if the definition could be added successfully and waitForSync is enabled for the _graphs collection. The response body contains the graph configuration that has been stored.

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

  • code: The response code.

  • graph: The information about the modified graph.

HTTP 202 Returned if the definition could be added successfully and waitForSync is disabled for the _graphs collection. The response body contains the graph configuration that has been stored.

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

  • code: The response code.

  • graph: The information about the modified graph.

HTTP 400 Returned if the definition could not be added. This could be because it is ill-formed, or if the definition is used in an other graph with a different signature.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

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

  1. Administrate access on the Database.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: 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 <<EOF
{ 
  "collection" : "works_in", 
  "from" : [ 
    "female", 
    "male" 
  ], 
  "to" : [ 
    "city" 
  ] 
}
EOF

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

Show response body

Replace an edge definition

Replace an existing edge definition

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

Path Parameters

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

  • definition (required): The name of the edge collection used in the definition.

Query Parameters

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

  • dropCollections (optional): Drop the collection as well. Collection will only be dropped if it is not used in other graphs.

A JSON object with these properties is required:

  • collection: The name of the edge collection to be used.

  • from: One or many vertex collections that can contain source vertices.

  • to: One or many vertex collections that can contain target vertices.

Change one specific edge definition. This will modify all occurrences of this definition in all graphs known to your database.

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

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

  • code: The response code.

  • graph: The information about the modified graph.

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

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

  • code: The response code.

  • graph: The information about the modified graph.

HTTP 400 Returned if no edge definition with this name is found in the graph, or of the new definition is ill-formed and cannot be used.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 403 Returned if your user has insufficient rights. In order to drop a vertex you at least need to have the following privileges:

  1. Administrate access on the Database.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 404 Returned if no graph with this name could be found.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: 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 <<EOF
{ 
  "collection" : "relation", 
  "from" : [ 
    "female", 
    "male", 
    "animal" 
  ], 
  "to" : [ 
    "female", 
    "male", 
    "animal" 
  ] 
}
EOF

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
etag: _Ywlo3tO--B
x-content-type-options: nosniff

Show response body

Remove an edge definition from the graph

Remove an edge definition form the graph

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

Path Parameters

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

  • definition (required): The name of the edge collection used in the definition.

Query Parameters

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

  • dropCollections (optional): Drop the collection as well. Collection will only be dropped if it is not used in other graphs.

Remove one edge definition from the graph. This will only remove the edge collection, the vertex collections remain untouched and can still be used in your queries.

HTTP 201 Returned if the edge definition could be removed from the graph and waitForSync is true.

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

  • code: The response code.

  • graph: The information about the modified graph.

HTTP 202 Returned if the edge definition could be removed from the graph and waitForSync is false.

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

  • code: The response code.

  • graph: The information about the modified graph.

HTTP 403 Returned if your user has insufficient rights. In order to drop a vertex you at least need to have the following privileges:

  1. Administrate access on the Database.
  • error: Flag if there was an error (true) or not (false). It is true in this response.

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

HTTP 404 Returned if no graph with this name could be found, or if no edge definition with this name is found in the graph.

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

  • code: The response code.

  • errorNum: ArangoDB error number for the error that occured.

  • errorMessage: A message created for this error.

Examples

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

HTTP/1.1 Accepted
content-type: application/json; charset=utf-8
etag: _YwloxKO--C
x-content-type-options: nosniff

Show response body