Graph Management

An edge definition is always a directed relation of a graph. Each graph can have arbitrary many relations defined within the edge definitions array.

Create a list of edge definitions to construct a graph.

The list of edge definitions of a graph can be managed by the graph module itself.This function is the entry point for the management and will return the correct list.

Parameters

• relationX (optional) An object representing a definition of one relation in the graphExamples

Show execution results

{ 
  "collection" : "lives_in", 
  "from" : [ 
    "user" 
  ], 
  "to" : [ 
    "city" 
  ] 
}
{ 
  "collection" : "knows", 
  "from" : [ 
    "user" 
  ], 
  "to" : [ 
    "user" 
  ] 
}
[ 
  { 
    "collection" : "lives_in", 
    "from" : [ 
      "user" 
    ], 
    "to" : [ 
      "city" 
    ] 
  }, 
  { 
    "collection" : "knows", 
    "from" : [ 
      "user" 
    ], 
    "to" : [ 
      "user" 
    ] 
  } 
]

Hide execution results

Extend the list

Extend the list of edge definitions to construct a graph.

graph_module._extendEdgeDefinitions(edgeDefinitions, relation1, relation2, …, relationN)

In order to add more edge definitions to the graph before creatingthis function can be used to add more definitions to the initial list.

Parameters

• edgeDefinitions (required) A list of relation definition objects.
• relationX (required) An object representing a definition of one relation in the graphExamples

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> directed_relation = graph_module._relation("lives_in", "user", "city");
arangosh> undirected_relation = graph_module._relation("knows", "user", "user");
arangosh> edgedefinitions = graph_module._edgeDefinitions(directed_relation);
arangosh> edgedefinitions = graph_module._extendEdgeDefinitions(undirected_relation);

Show execution results

{ 
  "collection" : "lives_in", 
  "from" : [ 
    "user" 
  ], 
  "to" : [ 
    "city" 
  ] 
}
{ 
  "collection" : "knows", 
  "from" : [ 
    "user" 
  ], 
  "to" : [ 
    "user" 
  ] 
}
[ 
  { 
    "collection" : "lives_in", 
    "from" : [ 
      "user" 
    ], 
    "to" : [ 
      "city" 
    ] 
  } 
]

Hide execution results

Relation

Define a directed relation.

graph_module._relation(relationName, fromVertexCollections, toVertexCollections)

The relationName defines the name of this relation and references to the underlying edge collection.The fromVertexCollections is an Array of document collections holding the start vertices.The toVertexCollections is an Array of document collections holding the target vertices.Relations are only allowed in the direction from any collection in fromVertexCollections_to any collection in _toVertexCollections.

Parameters

• relationName (required) The name of the edge collection where the edges should be stored.Will be created if it does not yet exist.
• fromVertexCollections (required) One or a list of collection names. Source vertices for the edgeshave to be stored in these collections. Collections will be created if they do not exist.
• toVertexCollections (required) One or a list of collection names. Target vertices for the edgeshave to be stored in these collections. Collections will be created if they do not exist.Examples

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph_module._relation("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]);

Show execution results

{ 
  "collection" : "has_bought", 
  "from" : [ 
    "Customer", 
    "Company" 
  ], 
  "to" : [ 
    "Groceries", 
    "Electronics" 
  ] 
}

Hide execution results

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph_module._relation("has_bought", "Customer", "Product");

Show execution results

{ 
  "collection" : "has_bought", 
  "from" : [ 
    "Customer" 
  ], 
  "to" : [ 
    "Product" 
  ] 

Hide execution results

Create a graph

After having introduced edge definitions a graph can be created.

Create a graph

graph_module._create(graphName, edgeDefinitions, orphanCollections)

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

For every type of edge definition a convenience method exists that can be used to create a graph.Optionally a list of vertex collections can be added, which are not used in any edge definition.These collections are referred to as orphan collections within this chapter.All collections used within the creation process are created if they do not exist.

Parameters

• graphName (required) Unique identifier of the graph
• edgeDefinitions (optional) List of relation definition objects
• orphanCollections (optional) List of additional vertex collection namesExamples

Create an empty graph, edge definitions can be added at runtime:

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph = graph_module._create("myGraph");

Show execution results

{[Graph] 
}

Hide execution results

Create a graph using an edge collection edges and a single vertex collection vertices

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> var edgeDefinitions = [ { collection: "edges", "from": [ "vertices" ], "to" : [ "vertices" ] } ];
arangosh> graph = graph_module._create("myGraph", edgeDefinitions);

Show execution results

{[Graph] 
  "edges" : [ArangoCollection 16669, "edges" (type edge, status loaded)], 
  "vertices" : [ArangoCollection 16664, "vertices" (type document, status loaded)] 
}

Hide execution results

Create a graph with edge definitions and orphan collections:

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph = graph_module._create("myGraph",
........> [graph_module._relation("myRelation", ["male", "female"], ["male", "female"])], ["sessions"]);

Show execution results

{[Graph] 
  "myRelation" : [ArangoCollection 16525, "myRelation" (type edge, status loaded)], 
  "female" : [ArangoCollection 16519, "female" (type document, status loaded)], 
  "male" : [ArangoCollection 16515, "male" (type document, status loaded)], 
  "sessions" : [ArangoCollection 16529, "sessions" (type document, status loaded)] 
}

Hide execution results

Complete Example to create a graph

Example Call:

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> var edgeDefinitions = graph_module._edgeDefinitions();
arangosh> graph_module._extendEdgeDefinitions(edgeDefinitions, graph_module._relation("friend_of", "Customer", "Customer"));
arangosh> graph_module._extendEdgeDefinitions(
........> edgeDefinitions, graph_module._relation(
........> "has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]));
arangosh> graph_module._create("myStore", edgeDefinitions);

Show execution results

{[Graph] 
  "friend_of" : [ArangoCollection 22583, "friend_of" (type edge, status loaded)], 
  "Customer" : [ArangoCollection 22578, "Customer" (type document, status loaded)], 
  "has_bought" : [ArangoCollection 22600, "has_bought" (type edge, status loaded)], 
  "Company" : [ArangoCollection 22588, "Company" (type document, status loaded)], 
  "Electronics" : [ArangoCollection 22596, "Electronics" (type document, status loaded)], 
  "Groceries" : [ArangoCollection 22592, "Groceries" (type document, status loaded)] 
}

Hide execution results

alternative call:

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh>  var edgeDefinitions = graph_module._edgeDefinitions(
........>  graph_module._relation("friend_of", ["Customer"], ["Customer"]), graph_module._relation(
........> "has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]));
arangosh> graph_module._create("myStore", edgeDefinitions);

Show execution results

{[Graph] 
  "friend_of" : [ArangoCollection 22625, "friend_of" (type edge, status loaded)], 
  "Customer" : [ArangoCollection 22620, "Customer" (type document, status loaded)], 
  "has_bought" : [ArangoCollection 22642, "has_bought" (type edge, status loaded)], 
  "Company" : [ArangoCollection 22629, "Company" (type document, status loaded)], 
  "Electronics" : [ArangoCollection 22634, "Electronics" (type document, status loaded)], 
  "Groceries" : [ArangoCollection 22638, "Groceries" (type document, status loaded)] 
}

Hide execution results

List all graphs.

graph_module._list()

Lists all graph names stored in this database.

Examples

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph_module._list();

Show execution results

Hide execution results

Load a graph

Get a graph

A graph can be retrieved by its name.

Parameters

• graphName (required) Unique identifier of the graphExamples

Get a graph:

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph = graph_module._graph("social");

Show execution results

{[Graph] 
  "relation" : [ArangoCollection 17298, "relation" (type edge, status loaded)], 
  "female" : [ArangoCollection 17292, "female" (type document, status loaded)], 
  "male" : [ArangoCollection 17295, "male" (type document, status loaded)] 
}

Hide execution results

Remove a graph

A graph can be dropped by its name.This can drop all collections contained in the graph as long as they are not used within other graphs.To drop the collections only belonging to this graph, the optional parameter drop-collections has to be set to true.

Parameters

• graphName (required) Unique identifier of the graph
• dropCollections (optional) Define if collections should be dropped (default: false)Examples

Drop a graph and keep collections:

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph_module._drop("social");
arangosh> db._collection("female");
arangosh> db._collection("male");
arangosh> db._collection("relation");

Show execution results

true
[ArangoCollection 16756, "female" (type document, status loaded)]
[ArangoCollection 16759, "male" (type document, status loaded)]
[ArangoCollection 16762, "relation" (type edge, status loaded)]

Hide execution results

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> graph_module._drop("social", true);
arangosh> db._collection("female");
arangosh> db._collection("male");
arangosh> db._collection("relation");

Show execution results

true
null
null
null

Hide execution results

Modify a graph definition at runtime

After you have created an graph its definition is not immutable.You can still add, delete or modify edge definitions and vertex collections.

Extend the edge definitions

Add another edge definition to the graph

graph._extendEdgeDefinitions(edgeDefinition)

Extends the edge definitions of a graph. If an orphan collection is used in thisedge definition, it will be removed from the orphanage. If the edge collection ofthe edge definition to add is already used in the graph or used in a differentgraph with different from and/or to collections an error is thrown.

Parameters

• edgeDefinition (required) The relation definition to extend the graphExamples

arangosh> var graph_module = require("@arangodb/general-graph")
arangosh> var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]);
arangosh> var graph = graph_module._create("myGraph", [ed1]);
arangosh> graph._extendEdgeDefinitions(ed2);

Show execution results

Hide execution results

Modify an relation definition

graph_module._editEdgeDefinition(edgeDefinition)

Edits one relation definition of a graph. The edge definition used as argument willreplace the existing edge definition of the graph which has the same collection.Vertex Collections of the replaced edge definition that are not used in the newdefinition will transform to an orphan. Orphans that are used in this new edgedefinition will be deleted from the list of orphans. Other graphs with the same edgedefinition will be modified, too.

Parameters

• edgeDefinition (required) The edge definition to replace the existing edgedefinition with the same attribute collection.Examples

arangosh> var graph_module = require("@arangodb/general-graph")
arangosh> var original = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var modified = graph_module._relation("myEC1", ["myVC2"], ["myVC3"]);
arangosh> var graph = graph_module._create("myGraph", [original]);
arangosh> graph._editEdgeDefinitions(modified);

Show execution results

Hide execution results

Delete an edge definition

Delete one relation definition

graph_module._deleteEdgeDefinition(edgeCollectionName, dropCollection)

Deletes a relation definition defined by the edge collection of a graph. If thecollections defined in the edge definition (collection, from, to) are not usedin another edge definition of the graph, they will be moved to the orphanage.

Parameters

• edgeCollectionName (required) Name of edge collection in the relation definition.
• dropCollection (optional) Define if the edge collection should be dropped. Default false.Examples

Remove an edge definition but keep the edge collection:

arangosh> var graph_module = require("@arangodb/general-graph")
arangosh> var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]);
arangosh> var graph = graph_module._create("myGraph", [ed1, ed2]);
arangosh> graph._deleteEdgeDefinition("myEC1");
arangosh> db._collection("myEC1");

Show execution results

[ArangoCollection 22285, "myEC1" (type edge, status loaded)]

Hide execution results

Remove an edge definition and drop the edge collection:

arangosh> var graph_module = require("@arangodb/general-graph")
arangosh> var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]);
arangosh> var graph = graph_module._create("myGraph", [ed1, ed2]);
arangosh> graph._deleteEdgeDefinition("myEC1", true);
arangosh> db._collection("myEC1");

Show execution results

null

Hide execution results

Extend vertex Collections

Each graph can have an arbitrary amount of vertex collections, which are not part of any edge definition of the graph.These collections are called orphan collections.If the graph is extended with an edge definition using one of the orphans,it will be removed from the set of orphan collection automatically.

Add a vertex collection

Add a vertex collection to the graph

graph._addVertexCollection(vertexCollectionName, createCollection)

Adds a vertex collection to the set of orphan collections of the graph. If thecollection does not exist, it will be created. If it is already used by any edgedefinition of the graph, an error will be thrown.

Parameters

• vertexCollectionName (required) Name of vertex collection.
• createCollection (optional) If true the collection will be created if it does not exist. Default: true.Examples

arangosh> var graph_module = require("@arangodb/general-graph");
arangosh> var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var graph = graph_module._create("myGraph", [ed1]);
arangosh> graph._addVertexCollection("myVC3", true);

Show execution results

Hide execution results

Get the orphaned collections

Get all orphan collections

graph._orphanCollections()

Returns all vertex collections of the graph that are not used in any edge definition.

Examples

arangosh> var graph_module = require("@arangodb/general-graph")
arangosh> var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var graph = graph_module._create("myGraph", [ed1]);
arangosh> graph._addVertexCollection("myVC3", true);
arangosh> graph._orphanCollections();

Show execution results

[ 
  "myVC3" 
]

Remove a vertex collection

Remove a vertex collection from the graph

graph._removeVertexCollection(vertexCollectionName, dropCollection)

Removes a vertex collection from the graph.Only collections not used in any relation definition can be removed.Optionally the collection can be deleted, if it is not used in any other graph.

Parameters

• vertexCollectionName (required) Name of vertex collection.
• dropCollection (optional) If true the collection will be dropped if it isnot used in any other graph. Default: false.Examples

Show execution results

  "myVC3", 
  "myVC4" 
]
[ 
  "myVC4" 
]

Hide execution results

Save a vertex

Create a new vertex in vertexCollectionName

graph.vertexCollectionName.save(data)

Parameters

• data (required) JSON data of vertex.Examples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.male.save({name: "Floyd", _key: "floyd"});

Show execution results

{ 
  "_id" : "male/floyd", 
  "_key" : "floyd", 
  "_rev" : "_ZHpY2Ai--B" 
}

Hide execution results

Replace a vertex

Replaces the data of a vertex in collection vertexCollectionName

Parameters

• vertexId (required) _id attribute of the vertex
• data (required) JSON data of vertex.
• options (optional) See collection documentationExamples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.male.save({neym: "Jon", _key: "john"});
arangosh> graph.male.replace("male/john", {name: "John"});

Show execution results

{ 
  "_id" : "male/john", 
  "_key" : "john", 
  "_rev" : "_ZHpY17W--_" 
}
{ 
  "_id" : "male/john", 
  "_key" : "john", 
  "_rev" : "_ZHpY17W--B", 
  "_oldRev" : "_ZHpY17W--_" 
}

Hide execution results

Updates the data of a vertex in collection vertexCollectionName

graph.vertexCollectionName.update(vertexId, data, options)

Parameters

• vertexId (required) _id attribute of the vertex
• data (required) JSON data of vertex.
• options (optional) See Examples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.female.save({name: "Lynda", _key: "linda"});
arangosh> graph.female.update("female/linda", {name: "Linda", _key: "linda"});

Show execution results

{ 
  "_id" : "female/linda", 
  "_key" : "linda", 
  "_rev" : "_ZHpY2Fm--B" 
}
{ 
  "_id" : "female/linda", 
  "_key" : "linda", 
  "_rev" : "_ZHpY2Fq--_", 
  "_oldRev" : "_ZHpY2Fm--B" 
}

Hide execution results

Remove a vertex

Removes a vertex in collection vertexCollectionName

graph.vertexCollectionName.remove(vertexId, options)

Additionally removes all ingoing and outgoing edges of the vertex recursively(see ).

Parameters

• vertexId (required) _id attribute of the vertex
• options (optional) See collection documentationExamples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.male.save({name: "Kermit", _key: "kermit"});
arangosh> db._exists("male/kermit")
arangosh> graph.male.remove("male/kermit")
arangosh> db._exists("male/kermit")

Show execution results

{ 
  "_id" : "male/kermit", 
  "_key" : "kermit", 
  "_rev" : "_ZHpY11q--_" 
}
true
true
false

Hide execution results

Manipulating Edges

Save a new edge

Creates an edge from vertex from to vertex to in collection edgeCollectionName

graph.edgeCollectionName.save(from, to, data, options)

Parameters

• from (required) _id attribute of the source vertex
• to (required) _id attribute of the target vertex
• data (required) JSON data of the edge
• options (optional) See Examples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.relation.save("male/bob", "female/alice", {type: "married", _key: "bobAndAlice"});

Show execution results

{ 
  "_id" : "relation/bobAndAlice", 
  "_key" : "bobAndAlice", 
  "_rev" : "_ZHpYt8e--F" 
}

Hide execution results

If the collections of from and to are not defined in an edge definition of the graph,the edge will not be stored.

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.relation.save(
........>  "relation/aliceAndBob",
........>   "female/alice",
........> {type: "married", _key: "bobAndAlice"});

Show execution results

[ArangoError 1906: invalid edge between relation/aliceAndBob and female/alice. Doesn't conform to any edge definition]

Hide execution results

Replace an edge

Replaces the data of an edge in collection edgeCollectionName. Note that _from and _to are mandatory.

graph.edgeCollectionName.replace(edgeId, data, options)

Parameters

• edgeId (required) _id attribute of the edge
• data (required) JSON data of the edge
• options (optional) See Examples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.relation.save("female/alice", "female/diana", {typo: "nose", _key: "aliceAndDiana"});
arangosh> graph.relation.replace("relation/aliceAndDiana", {type: "knows", _from: "female/alice", _to: "female/diana"});

Show execution results

{ 
  "_id" : "relation/aliceAndDiana", 
  "_key" : "aliceAndDiana", 
  "_rev" : "_ZHpYt3i--D" 
}
{ 
  "_id" : "relation/aliceAndDiana", 
  "_key" : "aliceAndDiana", 
  "_rev" : "_ZHpYt3m--_", 
  "_oldRev" : "_ZHpYt3i--D" 
}

Hide execution results

Update an edge

Updates the data of an edge in collection edgeCollectionName

graph.edgeCollectionName.update(edgeId, data, options)

Parameters

• edgeId (required) _id attribute of the edge
• data (required) JSON data of the edge
• options (optional) See Examples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.relation.save("female/alice", "female/diana", {type: "knows", _key: "aliceAndDiana"});
arangosh> graph.relation.update("relation/aliceAndDiana", {type: "quarreled", _key: "aliceAndDiana"});

Show execution results

{ 
  "_id" : "relation/aliceAndDiana", 
  "_key" : "aliceAndDiana", 
  "_rev" : "_ZHpYuHK--_" 
}
{ 
  "_id" : "relation/aliceAndDiana", 
  "_key" : "aliceAndDiana", 
  "_rev" : "_ZHpYuHK--B", 
  "_oldRev" : "_ZHpYuHK--_" 
}

Hide execution results

Removes an edge in collection edgeCollectionName

If this edge is used as a vertex by another edge, the other edge will be removed (recursively).

Parameters

• edgeId (required) _id attribute of the edge
• options (optional) See collection documentationExamples

arangosh> var examples = require("@arangodb/graph-examples/example-graph.js");
arangosh> var graph = examples.loadGraph("social");
arangosh> graph.relation.save("female/alice", "female/diana", {_key: "aliceAndDiana"});
arangosh> db._exists("relation/aliceAndDiana")
arangosh> db._exists("relation/aliceAndDiana")

Hide execution results