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

This documentation is outdated. Please see the most recent version at docs.arangodb.com

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.

Responses

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

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

  • code (integer): The response code.

  • graphs (array):

    • graph (object): The information about the newly created graph

      • name (string): The name of the graph

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

        • collection (string): Name of the edge collection, where the edge are stored in.

        • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

        • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

      • _id (string): The internal id value of this graph.

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

      • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SmartGraph (Enterprise Edition only).

      • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

      • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

      • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

      • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

      • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

Examples

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 623
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (boolean, optional): define if the request should wait until everything is synced to disc. Will change the success response code.

Request Body

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

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

    • collection (string, required): Name of the edge collection, where the edge are stored in.

    • from (array of strings, required): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

    • to (array of strings, required): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

  • orphanCollections (array of strings, optional): An array of additional vertex collections. Documents within these collections do not have edges within this graph.

  • isSmart (boolean, optional): Define if the created graph should be smart (Enterprise Edition only).

  • isDisjoint (boolean, optional): Whether to create a Disjoint SmartGraph instead of a regular SmartGraph (Enterprise Edition only).

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

    • smartGraphAttribute (string, optional): 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.

    • satellites (array of strings, optional): An array of collection names that will be used to create SatelliteCollections for a Hybrid (Disjoint) SmartGraph (Enterprise Edition only). Each array element must be a string and a valid collection name. The collection type cannot be modified later.

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

    • replicationFactor (integer, required): The replication factor used when initially creating collections for this graph. Can be set to "satellite" to create a SatelliteGraph, which will ignore numberOfShards, minReplicationFactor and writeConcern (Enterprise Edition only).

    • writeConcern (integer, optional): Write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

The creation of a graph requires the name of the graph and a definition of its edges.

Responses

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 (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • graph (object): The information about the newly created graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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 (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • graph (object): The information about the newly created graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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

  • 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 occurred.

  • errorMessage (string): 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 (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 occurred.

  • errorMessage (string): 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 (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 occurred.

  • 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 <<EOF
{ 
  "name" : "myGraph", 
  "edgeDefinitions" : [ 
    { 
      "collection" : "edges", 
      "from" : [ 
        "startVertices" 
      ], 
      "to" : [ 
        "endVertices" 
      ] 
    } 
  ] 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 227
etag: _gjDAjVW--_
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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" 
      ] 
    } 
  ], 
  "orphanCollections" : [ 
    "orphanVertices" 
  ], 
  "isSmart" : true, 
  "options" : { 
    "replicationFactor" : 2, 
    "numberOfShards" : 9, 
    "smartGraphAttribute" : "region" 
  } 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 243
etag: _gjDAjVq--_
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (string, 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.

Responses

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

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

  • code (integer): The response code.

  • graph (object): The information about the newly created graph

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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

  • 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 occurred.

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

Examples

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 227
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Drop a graph

delete an existing graph

DELETE /_api/gharial/{graph}

Path Parameters

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

Query Parameters

  • dropCollections (boolean, 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.

Responses

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

HTTP 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 (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 occurred.

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

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

  • 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 occurred.

  • errorMessage (string): 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 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 41
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (string, required): The name of the graph.

Lists all vertex collections within this graph.

Responses

HTTP 200: Is returned if the collections could be listed.

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

  • code (integer): The response code.

  • collections (array of strings): 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 (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 occurred.

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

Examples

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 58
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (string, required): The name of the graph.

Request Body

  • options (object, optional): A JSON object to set options for creating vertex collections.

    • satellites (array of strings, optional): An array of collection names that will be used to create SatelliteCollections for a Hybrid (Disjoint) SmartGraph (Enterprise Edition only). Each array element must be a string and a valid collection name. The collection type cannot be modified later.

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

Responses

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 (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • graph (object): The information about the modified graph.

    • name (string): The name of the graph

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SmartGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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 (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • graph (object): The information about the newly created graph

    • name (string): The name of the graph

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SmartGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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

  • 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 occurred.

  • errorMessage (string): 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 (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 occurred.

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

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

  • 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 occurred.

  • 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/vertex <<EOF
{ 
  "collection" : "otherVertices" 
}
EOF

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 244
etag: _gjDAjVC--E
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (string, required): The name of the graph.

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

Query Parameters

  • dropCollection (boolean, 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.

Responses

HTTP 200: Returned if the vertex collection was removed from the graph successfully 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.

  • graph (object): The information about the newly created graph

    • name (string): The name of the graph

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SmartGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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.

  • graph (object): The information about the newly created graph

    • name (string): The name of the graph

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SmartGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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 (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 occurred.

  • errorMessage (string): 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 (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 occurred.

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

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

  • 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 occurred.

  • errorMessage (string): 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 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 229
etag: _gjDAjci---
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 400 Bad Request
content-type: application/json
connection: Keep-Alive
content-length: 106
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

List edge definitions

Lists all edge definitions

GET /_api/gharial/{graph}/edge

Path Parameters

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

Lists all edge collections within this graph.

Responses

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

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

  • code (integer): The response code.

  • collections (array of strings): 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 (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 occurred.

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

Examples

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

HTTP/1.1 200 OK
content-type: application/json
connection: Keep-Alive
content-length: 53
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (string, required): The name of the graph.

Request Body

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

  • from (array of strings, required): One or many vertex collections that can contain source vertices.

  • to (array of strings, required): One or many vertex collections that can contain target vertices.

  • options (object, optional): A JSON object to set options for creating collections within this edge definition.

    • satellites (array of strings, optional): An array of collection names that will be used to create SatelliteCollections for a Hybrid (Disjoint) SmartGraph (Enterprise Edition only). Each array element must be a string and a valid collection name. The collection type cannot be modified later.

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.

Additionally, collection creation options can be set.

Responses

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 (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • graph (object): The information about the modified graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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 (boolean): Flag if there was an error (true) or not (false). It is false in this response.

  • code (integer): The response code.

  • graph (object): The information about the modified graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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 (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 occurred.

  • errorMessage (string): 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 (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 occurred.

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

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

  • 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 occurred.

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

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 294
etag: _gjDAjUG--_
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (string, required): The name of the graph.

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

Query Parameters

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

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

Request Body

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

  • from (array of strings, required): One or many vertex collections that can contain source vertices.

  • to (array of strings, required): One or many vertex collections that can contain target vertices.

  • options (object, optional): A JSON object to set options for modifying collections within this edge definition.

    • satellites (array of strings, optional): An array of collection names that will be used to create SatelliteCollections for a Hybrid (Disjoint) SmartGraph (Enterprise Edition only). Each array element must be a string and a valid collection name. The collection type cannot be modified later.

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

Responses

HTTP 201: Returned if the request was successful 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.

  • graph (object): The information about the modified graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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.

  • graph (object): The information about the modified graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

HTTP 400: Returned if the new edge definition is ill-formed and cannot be used.

  • 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 occurred.

  • errorMessage (string): 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 (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 occurred.

  • errorMessage (string): 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 (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 occurred.

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

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 247
etag: _gjDAjda--D
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
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 (string, required): The name of the graph.

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

Query Parameters

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

  • dropCollections (boolean, 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.

Responses

HTTP 201: Returned if the edge definition could be removed from the graph 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.

  • graph (object): The information about the modified graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

HTTP 202: Returned if the edge definition could be removed from the graph 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.

  • graph (object): The information about the modified graph.

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

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

      • collection (string): Name of the edge collection, where the edge are stored in.

      • from (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _from is in any of the collections here.

      • to (array of strings): List of vertex collection names. Edges in collection can only be inserted if their _to is in any of the collections here.

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

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

    • _id (string): The internal id value of this graph.

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

    • replicationFactor (integer): The replication factor used for every new collection in the graph. Can also be the string "satellite" for a SatelliteGraph (Enterprise Edition only).

    • writeConcern (integer): Default write concern for new collections in the graph. It determines how many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time however. The value of writeConcern can not be larger than replicationFactor. (cluster only)

    • isSmart (boolean): Whether the graph is a SmartGraph (Enterprise Edition only).

    • isDisjoint (boolean): Whether the graph is a Disjoint SmartGraph (Enterprise Edition only).

    • smartGraphAttribute (string): Name of the sharding attribute in the SmartGraph case (Enterprise Edition only).

    • isSatellite (boolean): Flag if the graph is a SatelliteGraph (Enterprise Edition only) or not.

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 (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 occurred.

  • errorMessage (string): 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 (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 occurred.

  • 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

HTTP/1.1 202 Accepted
content-type: application/json
connection: Keep-Alive
content-length: 171
etag: _gjDAjXm--A
server: ArangoDB
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
❮  Graphs

© ArangoDB - Graph and Beyond