Graph Management
This chapter describes the javascript interface for creating and modifyingnamed graphs.
Edge Definitions
An edge definition is always a directed relation of a graph. Each graph canhave arbitrary many relations defined within the edge definitions array.
Initialize the List
Create a list of edge definitions to construct a graph:
graph_module._edgeDefinitions(relation1, relation2, …, relationN)
relation
(object, optional):An object representing a definition of one relation in the graph
The list of edge definitions of a graph can be managed by the graph moduleitself. This function is the entry point for the management and will returnthe correct list.
Examples
- 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, undirected_relation);
Show execution results
Hide 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"
- ]
- }
- ]
Extend the List
Extend the list of edge definitions to construct a graph:
graph_module._extendEdgeDefinitions(edgeDefinitions, relation1, relation2, …, relationN)
edgeDefinitions
(array):A list of relation definition objects.relationX
(object):An object representing a definition of one relation in the graph
In order to add more edge definitions to the graph before creatingthis function can be used to add more definitions to the initial list.
Examples
- 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
Hide execution results
- {
- "collection" : "lives_in",
- "from" : [
- "user"
- ],
- "to" : [
- "city"
- ]
- }
- {
- "collection" : "knows",
- "from" : [
- "user"
- ],
- "to" : [
- "user"
- ]
- }
- [
- {
- "collection" : "lives_in",
- "from" : [
- "user"
- ],
- "to" : [
- "city"
- ]
- }
- ]
Relation
Define a directed relation:
graph_module._relation(relationName, fromVertexCollections, toVertexCollections)
relationName
(string):The name of the edge collection where the edges should be stored.Will be created if it does not yet exist.fromVertexCollections
(string|array):One or a list of collection names. Source vertices for the edgeshave to be stored in these collections. Collections will be created if theydo not exist.toVertexCollections
(string|array):One or a list of collection names. Target vertices for the edgeshave to be stored in these collections. Collections will be created if theydo not exist.
The relationName defines the name of this relation and references to theunderlying edge collection. The fromVertexCollections is an Array of documentcollections holding the start vertices. The toVertexCollections is an arrayof document collections holding the target vertices. Relations are only allowedin the direction from any collection in fromVertexCollections to anycollection in toVertexCollections.
Examples
- arangosh> var graph_module = require("@arangodb/general-graph");
- arangosh> graph_module._relation("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]);
Show execution results
Hide execution results
- {
- "collection" : "has_bought",
- "from" : [
- "Customer",
- "Company"
- ],
- "to" : [
- "Groceries",
- "Electronics"
- ]
- }
- arangosh> var graph_module = require("@arangodb/general-graph");
- arangosh> graph_module._relation("has_bought", "Customer", "Product");
Show execution results
Hide execution results
- {
- "collection" : "has_bought",
- "from" : [
- "Customer"
- ],
- "to" : [
- "Product"
- ]
- }
Create a Graph
graph_module._create(graphName, edgeDefinitions, orphanCollections)
graphName
(string):Unique identifier of the graphedgeDefinitions
(array, optional):List of relation definition objectsorphanCollections
(array, optional):List of additional vertex collection names
The creation of a graph requires the name of the graph and a definition ofits edges.
For every type of edge definition a convenience method exists that can be usedto create a graph. Optionally a list of vertex collections can be added, whichare not used in any edge definition. These collections are referred to asorphan collections within this chapter. All collections used within thecreation process are created if they do not exist.
Examples
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
Hide execution results
- {[Graph]
- }
Create a graph using an edge collection edges
and a singlevertex 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
Hide execution results
- {[Graph]
- "edges" : [ArangoCollection 75107, "edges" (type edge, status loaded)],
- "vertices" : [ArangoCollection 75104, "vertices" (type document, status loaded)]
- }
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
Hide execution results
- {[Graph]
- "myRelation" : [ArangoCollection 74991, "myRelation" (type edge, status loaded)],
- "female" : [ArangoCollection 74985, "female" (type document, status loaded)],
- "male" : [ArangoCollection 74988, "male" (type document, status loaded)],
- "sessions" : [ArangoCollection 74982, "sessions" (type document, status loaded)]
- }
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
Hide execution results
- {[Graph]
- "friend_of" : [ArangoCollection 78968, "friend_of" (type edge, status loaded)],
- "Customer" : [ArangoCollection 78960, "Customer" (type document, status loaded)],
- "has_bought" : [ArangoCollection 78963, "has_bought" (type edge, status loaded)],
- "Company" : [ArangoCollection 78954, "Company" (type document, status loaded)],
- "Electronics" : [ArangoCollection 78951, "Electronics" (type document, status loaded)],
- "Groceries" : [ArangoCollection 78957, "Groceries" (type document, status loaded)]
- }
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
Hide execution results
- {[Graph]
- "friend_of" : [ArangoCollection 79004, "friend_of" (type edge, status loaded)],
- "Customer" : [ArangoCollection 78996, "Customer" (type document, status loaded)],
- "has_bought" : [ArangoCollection 78999, "has_bought" (type edge, status loaded)],
- "Company" : [ArangoCollection 78990, "Company" (type document, status loaded)],
- "Electronics" : [ArangoCollection 78987, "Electronics" (type document, status loaded)],
- "Groceries" : [ArangoCollection 78993, "Groceries" (type document, status loaded)]
- }
List available Graphs
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 by its name:
graph_module._graph(graphName)
graphName
(string):Unique identifier of the graph
Examples
- arangosh> var graph_module = require("@arangodb/general-graph");
- arangosh> graph = graph_module._graph("social");
Show execution results
Hide execution results
- {[Graph]
- "relation" : [ArangoCollection 75545, "relation" (type edge, status loaded)],
- "female" : [ArangoCollection 75535, "female" (type document, status loaded)],
- "male" : [ArangoCollection 75540, "male" (type document, status loaded)]
- }
Remove a Graph
Drop a Graph by its name:
graph_module._drop(graphName, dropCollections)
graphName
(string):Unique identifier of the graphdropCollections
(bool, optional):Define if collections should be dropped (default: false)
This can drop all collections contained in the graph as long as they are notused within other graphs. To drop the collections only belonging to this graph,the optional parameter drop-collections has to be set to true.
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
Hide execution results
- [ArangoCollection 75166, "female" (type document, status loaded)]
- [ArangoCollection 75171, "male" (type document, status loaded)]
- [ArangoCollection 75176, "relation" (type edge, status loaded)]
- 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
Hide execution results
- null
- null
- null
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)
edgeDefinition
(object):The relation definition to extend the graph
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.
Examples
- 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 Edge Definition
Modify a relation definition:
graph_module._editEdgeDefinitions(edgeDefinition)
edgeDefinition
(object):The edge definition to replace the existing edge definition with the sameattribute collection.
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.
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)
edgeCollectionName
(string):Name of edge collection in the relation definition.dropCollection
(bool, optional):Define if the edge collection should be dropped. Default: false
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.
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
Hide execution results
- [ArangoCollection 78719, "myEC1" (type edge, status loaded)]
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
Hide execution results
- null
Extend Vertex Collections
Each graph can have an arbitrary amount of vertex collections, which are notpart of any edge definition of the graph. These collections are called orphancollections. If the graph is extended with an edge definition using one of theorphans, 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)
vertexCollectionName
(string):Name of vertex collection.createCollection
(bool, optional):If true the collection will be created if it does not exist. Default: true
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.
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 anyedge 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
Hide execution results
- [
- "myVC3"
- ]
Remove a Vertex Collection
Remove a vertex collection from the graph:
graph._removeVertexCollection(vertexCollectionName, dropCollection)
vertexCollectionName
(string):Name of vertex collection.dropCollection
(bool, optional):If true the collection will be dropped if it is not used in any other graph.Default: false
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.
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._addVertexCollection("myVC4", true);
- arangosh> graph._orphanCollections();
- arangosh> graph._removeVertexCollection("myVC3");
- arangosh> graph._orphanCollections();
Show execution results
Hide execution results
- [
- "myVC3",
- "myVC4"
- ]
- [
- "myVC4"
- ]
Manipulating Vertices
Save a Vertex
Create a new vertex in vertexCollectionName:
graph.vertexCollectionName.save(data)
data
(object):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
Hide execution results
- {
- "_id" : "male/floyd",
- "_key" : "floyd",
- "_rev" : "_Z2KDRY----"
- }
Replace a Vertex
Replaces the data of a vertex in collection vertexCollectionName:
graph.vertexCollectionName.replace(vertexId, data, options)
vertexId
(string):_id attribute of the vertexdata
(object):JSON data of vertex.options
(object, optional):See collection documentation
Examples
- 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
Hide execution results
- {
- "_id" : "male/john",
- "_key" : "john",
- "_rev" : "_Z2KDRX---A"
- }
- {
- "_id" : "male/john",
- "_key" : "john",
- "_rev" : "_Z2KDRXC--_",
- "_oldRev" : "_Z2KDRX---A"
- }
Update a Vertex
Updates the data of a vertex in collection vertexCollectionName
graph.vertexCollectionName.update(vertexId, data, options)
vertexId
(string):_id attribute of the vertexdata
(object):JSON data of vertex.options
(object, optional):See collection documentation
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
Hide execution results
- {
- "_id" : "female/linda",
- "_key" : "linda",
- "_rev" : "_Z2KDRY2---"
- }
- {
- "_id" : "female/linda",
- "_key" : "linda",
- "_rev" : "_Z2KDRY2--B",
- "_oldRev" : "_Z2KDRY2---"
- }
Remove a Vertex
Removes a vertex in collection vertexCollectionName
graph.vertexCollectionName.remove(vertexId, options)
vertexId
(string):_id attribute of the vertexoptions
(object, optional):See collection documentation
Additionally removes all ingoing and outgoing edges of the vertex recursively(see edge remove).
Examples
- 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
Hide execution results
- {
- "_id" : "male/kermit",
- "_key" : "kermit",
- "_rev" : "_Z2KDRV2---"
- }
- true
- true
- false
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)
from
(string):_id attribute of the source vertexto
(string):_id attribute of the target vertexdata
(object, optional):JSON data of the edgeoptions
(object, optional):See collection documentation
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
Hide execution results
- {
- "_id" : "relation/bobAndAlice",
- "_key" : "bobAndAlice",
- "_rev" : "_Z2KDQRW---"
- }
If the collections of from and to are not defined in an edge definitionof 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
Hide execution results
- [ArangoError 1906: invalid edge between relation/aliceAndBob and female/alice. Doesn't conform to any edge definition]
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)
edgeId
(string):_id attribute of the edgedata
(object, optional):JSON data of the edgeoptions
(object, optional):See collection documentation
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
Hide execution results
- {
- "_id" : "relation/aliceAndDiana",
- "_key" : "aliceAndDiana",
- "_rev" : "_Z2KDQQa---"
- }
- {
- "_id" : "relation/aliceAndDiana",
- "_key" : "aliceAndDiana",
- "_rev" : "_Z2KDQQa--B",
- "_oldRev" : "_Z2KDQQa---"
- }
Update an Edge
Updates the data of an edge in collection edgeCollectionName
graph.edgeCollectionName.update(edgeId, data, options)
edgeId
(string):_id attribute of the edgedata
(object, optional):JSON data of the edgeoptions
(object, optional):See collection documentation
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
Hide execution results
- {
- "_id" : "relation/aliceAndDiana",
- "_key" : "aliceAndDiana",
- "_rev" : "_Z2KDQTC---"
- }
- {
- "_id" : "relation/aliceAndDiana",
- "_key" : "aliceAndDiana",
- "_rev" : "_Z2KDQTC--B",
- "_oldRev" : "_Z2KDQTC---"
- }
Remove an Edge
Removes an edge in collection edgeCollectionName
graph.edgeCollectionName.remove(edgeId, options)
edgeId
(string):_id attribute of the edgeoptions
(object, optional):See collection documentation
If this edge is used as a vertex by another edge, the other edge will be removed(recursively).
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", {_key: "aliceAndDiana"});
- arangosh> db._exists("relation/aliceAndDiana")
- arangosh> graph.relation.remove("relation/aliceAndDiana")
- arangosh> db._exists("relation/aliceAndDiana")
Show execution results
Hide execution results
- {
- "_id" : "relation/aliceAndDiana",
- "_key" : "aliceAndDiana",
- "_rev" : "_Z2KDQPO--A"
- }
- true
- true
- false