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 graph names stored in this database.

Example:

shell> curl --dump - http://localhost:8529/_api/gharial

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

{ 
  "error" : false, 
  "graphs" : [ 
    { 
      "_key" : "routeplanner", 
      "_id" : "_graphs/routeplanner", 
      "_rev" : "_VTxSeZO---", 
      "orphanCollections" : [ ], 
      "edgeDefinitions" : [ 
        { 
          "collection" : "germanHighway", 
          "from" : [ 
            "germanCity" 
          ], 
          "to" : [ 
            "germanCity" 
          ] 
        }, 
        { 
          "collection" : "frenchHighway", 
          "from" : [ 
            "frenchCity" 
          ], 
          "to" : [ 
            "frenchCity" 
          ] 
        }, 
        { 
          "collection" : "internationalHighway", 
          "from" : [ 
            "frenchCity", 
            "germanCity" 
          ], 
          "to" : [ 
            "frenchCity", 
            "germanCity" 
          ] 
        } 
      ], 
      "numberOfShards" : 1, 
      "replicationFactor" : 1 
    }, 
    { 
      "_key" : "social", 
      "_id" : "_graphs/social", 
      "_rev" : "_VTxSeUa---", 
      "orphanCollections" : [ ], 
      "edgeDefinitions" : [ 
        { 
          "collection" : "relation", 
          "from" : [ 
            "female", 
            "male" 
          ], 
          "to" : [ 
            "female", 
            "male" 
          ] 
        } 
      ], 
      "numberOfShards" : 1, 
      "replicationFactor" : 1 
    } 
  ], 
  "code" : 200 
}

Return Codes

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

Examples

shell> curl --dump - http://localhost:8529/_api/gharial

HTTP/1.1 200 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

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

A JSON object with these properties is required:

  • orphanCollections: An array of additional vertex collections.
  • edgeDefinitions: An array of definitions for the edge
  • name: Name of the graph.
  • isSmart: Define if the created graph should be smart. This only has effect in Enterprise version.
  • options:
    • smartGraphAttribute: The attribute name that is used to smartly shard the vertices of a graph. Every vertex in this Graph 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.

Example:

shell> curl -X POST --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; charset=utf-8
etag: _VTxSdea---
x-content-type-options: nosniff

{ 
  "error" : false, 
  "graph" : { 
    "name" : "myGraph", 
    "edgeDefinitions" : [ 
      { 
        "collection" : "edges", 
        "from" : [ 
          "startVertices" 
        ], 
        "to" : [ 
          "endVertices" 
        ] 
      } 
    ], 
    "orphanCollections" : [ ], 
    "isSmart" : false, 
    "numberOfShards" : 0, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/myGraph", 
    "_rev" : "_VTxSdea---" 
  }, 
  "code" : 202 
}

Example:

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

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

{ 
  "error" : false, 
  "graph" : { 
    "name" : "myGraph", 
    "edgeDefinitions" : [ 
      { 
        "collection" : "edges", 
        "from" : [ 
          "startVertices" 
        ], 
        "to" : [ 
          "endVertices" 
        ] 
      } 
    ], 
    "orphanCollections" : [ ], 
    "isSmart" : false, 
    "numberOfShards" : 0, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/myGraph", 
    "_rev" : "_VTxSdju---" 
  }, 
  "code" : 202 
}

shell> curl -X POST --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; charset=utf-8
etag: _VTxSdea---
x-content-type-options: nosniff
show response body
shell> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/gharial <<EOF
{ 
  "name" : "myGraph", 
  "edgeDefinitions" : [ 
    { 
      "collection" : "edges", 
      "from" : [ 
        "startVertices" 
      ], 
      "to" : [ 
        "endVertices" 
      ] 
    } 
  ], 
  "isSmart" : true, 
  "options" : { 
    "numberOfShards" : 9, 
    "smartGraphAttribute" : "region" 
  } 
}
EOF

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

Get a graph

Get a graph from the graph module.

GET /_api/gharial/{graph-name}

Gets a graph from the collection _graphs. Returns the definition content of this graph.

Example:

shell> curl --dump - http://localhost:8529/_api/gharial/myGraph

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

{ 
  "error" : false, 
  "graph" : { 
    "name" : "myGraph", 
    "edgeDefinitions" : [ 
      { 
        "collection" : "edges", 
        "from" : [ 
          "startVertices" 
        ], 
        "to" : [ 
          "endVertices" 
        ] 
      } 
    ], 
    "orphanCollections" : [ ], 
    "isSmart" : false, 
    "numberOfShards" : 1, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/myGraph", 
    "_rev" : "_VTxSeHO---" 
  }, 
  "code" : 200 
}

Path Parameters

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

Return Codes

  • 200: Returned if the graph could be found.
  • 404: Returned if no graph with this name could be found.

Examples

shell> curl --dump - http://localhost:8529/_api/gharial/myGraph

HTTP/1.1 200 OK
content-type: application/json; charset=utf-8
etag: _VTxSeHO---
x-content-type-options: nosniff
show response body

Drop a graph

delete an existing graph

DELETE /_api/gharial/{graph-name}

Removes a graph from the collection _graphs.

Example:

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social?dropCollections=true

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

{ 
  "error" : false, 
  "removed" : true, 
  "code" : 202 
}

Path Parameters

  • graph-name (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.

Return Codes

  • 201: Is returned if the graph could be dropped and waitForSync is enabled for the _graphs collection.
  • 202: Returned if the graph could be dropped and waitForSync is disabled for the _graphs collection.
  • 404: Returned if no graph with this name could be found.

Examples

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social?dropCollections=true

HTTP/1.1 202 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-name}/vertex

Lists all vertex collections within this graph.

Example:

shell> curl --dump - http://localhost:8529/_api/gharial/social/vertex

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

{ 
  "error" : false, 
  "collections" : [ 
    "female", 
    "male" 
  ], 
  "code" : 200 
}

Path Parameters

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

Return Codes

  • 200: Is returned if the collections could be listed.
  • 404: Returned if no graph with this name could be found.

Examples

shell> curl --dump - http://localhost:8529/_api/gharial/social/vertex

HTTP/1.1 200 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-name}/vertex

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

Example:

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

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

{ 
  "error" : false, 
  "graph" : { 
    "name" : "social", 
    "edgeDefinitions" : [ 
      { 
        "collection" : "relation", 
        "from" : [ 
          "female", 
          "male" 
        ], 
        "to" : [ 
          "female", 
          "male" 
        ] 
      } 
    ], 
    "orphanCollections" : [ 
      "otherVertices" 
    ], 
    "isSmart" : false, 
    "numberOfShards" : 1, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/social", 
    "_rev" : "_VTxSdXG---" 
  }, 
  "code" : 202 
}

Path Parameters

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

Return Codes

  • 201: Returned if the edge collection could be added successfully and waitForSync is true.
  • 202: Returned if the edge collection could be added successfully and waitForSync is false.
  • 404: Returned if no graph with this name could be found.

Examples

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

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

Remove vertex collection

Remove a vertex collection form the graph.

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

Removes a vertex collection from the graph and optionally deletes the collection, if it is not used in any other graph.

Example:

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

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social/vertex/otherVertices

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

{ 
  "error" : false, 
  "graph" : { 
    "name" : "social", 
    "edgeDefinitions" : [ 
      { 
        "collection" : "relation", 
        "from" : [ 
          "female", 
          "male" 
        ], 
        "to" : [ 
          "female", 
          "male" 
        ] 
      } 
    ], 
    "orphanCollections" : [ ], 
    "isSmart" : false, 
    "numberOfShards" : 1, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/social", 
    "_rev" : "_VTxSfFS---" 
  }, 
  "code" : 202 
}

Example:

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

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social/vertex/male

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

{ 
  "error" : true, 
  "errorNum" : 1928, 
  "errorMessage" : "not in orphan collection", 
  "code" : 400 
}

Path Parameters

  • graph-name (required): The name of the graph.
  • collection-name (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.

Return Codes

  • 201: Returned if the vertex collection was removed from the graph successfully and waitForSync is true.
  • 202: Returned if the request was successful but waitForSync is false.
  • 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.
  • 404: Returned if no graph with this name could be found.

Examples

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

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social/vertex/otherVertices

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

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

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social/vertex/male

HTTP/1.1 400 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-name}/edge

Lists all edge collections within this graph.

Example:

shell> curl --dump - http://localhost:8529/_api/gharial/social/edge

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

{ 
  "error" : false, 
  "collections" : [ 
    "relation" 
  ], 
  "code" : 200 
}

Path Parameters

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

Return Codes

  • 200: Is returned if the edge definitions could be listed.
  • 404: Returned if no graph with this name could be found.

Examples

shell> curl --dump - http://localhost:8529/_api/gharial/social/edge

HTTP/1.1 200 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-name}/edge

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.

A JSON object with these properties is required:

  • to (string): One or many vertex collections that can contain target vertices.
  • from (string): One or many vertex collections that can contain source vertices.
  • collection: The name of the edge collection to be used.

Example:

shell> curl -X POST --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; charset=utf-8
etag: _VTxSdH6---
x-content-type-options: nosniff

{ 
  "error" : false, 
  "graph" : { 
    "name" : "social", 
    "edgeDefinitions" : [ 
      { 
        "collection" : "relation", 
        "from" : [ 
          "female", 
          "male" 
        ], 
        "to" : [ 
          "female", 
          "male" 
        ] 
      }, 
      { 
        "collection" : "works_in", 
        "from" : [ 
          "female", 
          "male" 
        ], 
        "to" : [ 
          "city" 
        ] 
      } 
    ], 
    "orphanCollections" : [ ], 
    "isSmart" : false, 
    "numberOfShards" : 1, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/social", 
    "_rev" : "_VTxSdH6---" 
  }, 
  "code" : 202 
}

Path Parameters

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

Return Codes

  • 201: Returned if the definition could be added successfully and waitForSync is enabled for the _graphs collection.
  • 202: Returned if the definition could be added successfully and waitForSync is disabled for the _graphs collection.
  • 400: Returned if the defininition could not be added, the edge collection is used in an other graph with a different signature.
  • 404: Returned if no graph with this name could be found.

Examples

shell> curl -X POST --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; charset=utf-8
etag: _VTxSdH6---
x-content-type-options: nosniff
show response body

Replace an edge definition

Replace an existing edge definition

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

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

A JSON object with these properties is required:

  • to (string): One or many vertex collections that can contain target vertices.
  • from (string): One or many vertex collections that can contain source vertices.
  • collection: The name of the edge collection to be used.

Example:

shell> curl -X PUT --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; charset=utf-8
etag: _VTxSfRu---
x-content-type-options: nosniff

{ 
  "error" : false, 
  "graph" : { 
    "name" : "social", 
    "edgeDefinitions" : [ 
      { 
        "collection" : "relation", 
        "from" : [ 
          "animal", 
          "female", 
          "male" 
        ], 
        "to" : [ 
          "animal", 
          "female", 
          "male" 
        ] 
      } 
    ], 
    "orphanCollections" : [ ], 
    "isSmart" : false, 
    "numberOfShards" : 1, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/social", 
    "_rev" : "_VTxSfRu---" 
  }, 
  "code" : 202 
}

Path Parameters

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

Return Codes

  • 201: Returned if the request was successful and waitForSync is true.
  • 202: Returned if the request was successful but waitForSync is false.
  • 400: Returned if no edge definition with this name is found in the graph.
  • 404: Returned if no graph with this name could be found.

Examples

shell> curl -X PUT --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; charset=utf-8
etag: _VTxSfRu---
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-name}/edge/{definition-name}

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.

Example:

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social/edge/relation

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

{ 
  "error" : false, 
  "graph" : { 
    "name" : "social", 
    "edgeDefinitions" : [ ], 
    "orphanCollections" : [ 
      "female", 
      "male" 
    ], 
    "isSmart" : false, 
    "numberOfShards" : 1, 
    "smartGraphAttribute" : "", 
    "_id" : "_graphs/social", 
    "_rev" : "_VTxSd66---" 
  }, 
  "code" : 202 
}

Path Parameters

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

Query Parameters

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

Return Codes

  • 201: Returned if the edge definition could be removed from the graph and waitForSync is true.
  • 202: Returned if the edge definition could be removed from the graph and waitForSync is false.
  • 400: Returned if no edge definition with this name is found in the graph.
  • 404: Returned if no graph with this name could be found.

Examples

shell> curl -X DELETE --dump - http://localhost:8529/_api/gharial/social/edge/relation

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

© ArangoDB - the native multi-model NoSQL database