!CHAPTER Graph Module
The graph module provides functions dealing with graph structures.
!SECTION First Steps with Graphs
A Graph consists of *vertices* and *edges*. Edges are stored as documents in *edge
collections*. A vertex can be a document of a *document collection* or of an edge
collection (so edges can be used as vertices). Wich collections are used within
a graph is defined via *edge definitions*. A graph can contain more than one edge
definition, at least one is needed.
!SUBSECTION Create a graph
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.
```js
> var graph = require("org/arangodb/graph");
> var g = graph._create(graphName, edgeDefinitions);
```
There are different types of edge defintions:
!SUBSECTION Edge Definitions
To add further edge definitions to the array one must call:
```js
> graph._extendEdgeDefinitions(edgeDefinitions, edgeDefinition1,......edgeDefinitionN);
```
!SUBSUBSECTION Undirected Relation
`general-graph._undirectedRelationDefinition(relationName, vertexCollections)`
*Define an undirected relation.*
Defines an undirected relation with the name *relationName* using the
list of *vertexCollections*. This relation allows the user to store
edges in any direction between any pair of vertices within the
*vertexCollections*.
@EXAMPLES
To define simple relation with only one vertex collection:
```
arangosh> var graph = require("org/arangodb/general-graph");
arangosh> graph._undirectedRelationDefinition("friend", "user");
{
"collection" : "friend",
"from" : [
"user"
],
"to" : [
"user"
]
}
```
To define a relation between several vertex collections:
```
arangosh> var graph = require("org/arangodb/general-graph");
arangosh> graph._undirectedRelationDefinition("marriage", ["female", "male"]);
{
"collection" : "marriage",
"from" : [
"female",
"male"
],
"to" : [
"female",
"male"
]
}
```
!SUBSUBSECTION Directed Relation
`general-graph._directedRelationDefinition(relationName, fromVertexCollections, toVertexCollections)`
*Define a directed relation.*
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*.
@EXAMPLES
```
arangosh> var graph = require("org/arangodb/general-graph");
arangosh> graph._directedRelationDefinition("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]);
{
"collection" : "has_bought",
"from" : [
"Customer",
"Company"
],
"to" : [
"Groceries",
"Electronics"
]
}
```
!SUBSUBSECTION Complete Example to create a graph
Example Call:
```js
> var graph = require("org/arangodb/graph");
> var edgeDefinitions = graph._edgeDefinitions();
> graph._extendEdgeDefinitions(edgeDefinitions, graph._undirectedRelationDefinition("friend_of", ["Customer"]));
> graph._extendEdgeDefinitions(edgeDefinitions, graph._directedRelationDefinition("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]));
> graph._create("myStore", edgeDefinitions);
{
_id: "_graphs/123",
_rev: "123",
_key: "123"
}
```
alternative call:
```js
> var graph = require("org/arangodb/graph");
> var edgeDefinitions = graph._edgeDefinitions(graph._undirectedRelationDefinition("friend_of", ["Customer"]), graph._directedRelationDefinition("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]));
> graph._create("myStore", edgeDefinitions);
{
_id: "_graphs/123",
_rev: "123",
_key: "123"
};
```
!SUBSECTION Orphan Collections
Each graph has an orphan collection. It consists of arbitrary many vertex collection (type *document*), that are not
used in an edge definition of the graph. If the graph is extended with an edge definition using one of the orphans,
it will be removed from the orphan collection automatically.
!SUBSUBSECTION Add
Adds a vertex collection to the set of orphan collections of the graph. If the
collection does not exist, it will be created.
`general-graph._addOrphanCollection(orphanCollectionName, createCollection)`
*orphanCollectionName* - string : name of vertex collection.
*createCollection* - bool : if true the collection will be created if it does not exist. Default: true.
@EXAMPLES
```
arangosh> var graph = require("org/arangodb/general-graph")
arangosh> var ed1 = graph._directedRelationDefinition("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var g = graph._create("myGraph", [ed1, ed2]);
ReferenceError: ed2 is not defined
```
!SUBSUBSECTION Read
Returns all vertex collections of the graph, that are not used in an edge definition.
`general-graph._getOrphanCollections()`
@EXAMPLES
```
arangosh> var graph = require("org/arangodb/general-graph")
arangosh> var ed1 = graph._directedRelationDefinition("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var g = graph._create("myGraph", [ed1]);
[ArangoError 1925: graph already exists]
```
!SUBSUBSECTION Remove
Removes an orphan collection from the graph and deletes the collection, if it is not
used in any graph.
`general-graph._removeOrphanCollection()`
*orphanCollectionName* - string : name of vertex collection.
*dropCollection* - bool : if true the collection will be dropped if it is not used in any graph.
Default: true.
@EXAMPLES
```
arangosh> var graph = require("org/arangodb/general-graph")
arangosh> var ed1 = graph._directedRelationDefinition("myEC1", ["myVC1"], ["myVC2"]);
arangosh> var g = graph._create("myGraph", [ed1]);
[ArangoError 1925: graph already exists]
```
!SUBSECTION Read a graph
```js
> var graph = require("org/arangodb/graph");
> var g = graph._graph("myStore");
```
- - -
!SUBSECTION Remove a graph
Removes a graph from the collection *\_graphs*.
```js
> graph._drop(graphId, dropCollections);
true
```
graphId: string - id of the graph to be removed
dropCollections: bool - optional. *true* all collections of the graph will be deleted.
*false* no collection of the graph will be deleted. Default: *true*
!SECTION Edge
!SUBSECTION Save
Creates and saves a new vertex in collection *vertexCollectionName*
`general-graph.vertexCollectionName.save(data)`
*data*: json - data of vertex
@EXAMPLES
```
arangosh> var examples = require("org/arangodb/graph-examples/example-graph.js");
arangosh> var g = examples.loadGraph("social");
arangosh> g.male.save({name: "Floyd", _key: "floyd"});
{
"error" : false,
"_id" : "male/floyd",
"_rev" : "91260521",
"_key" : "floyd"
}
```
!SUBSECTION Replace
Replaces the data of a vertex in collection *vertexCollectionName*
`general-graph.vertexCollectionName.replace(vertexId, data, options)`
*vertexId*: string - id of the vertex
*data*: json - data of vertex
*options*: json - (optional) - see collection documentation
@EXAMPLES
```
arangosh> var examples = require("org/arangodb/graph-examples/example-graph.js");
arangosh> var g = examples.loadGraph("social");
arangosh> g.male.save({neym: "Jon", _key: "john"});
{
"error" : false,
"_id" : "male/john",
"_rev" : "31360617",
"_key" : "john"
}
arangosh> g.male.replace("male/john", {name: "John"});
{
"error" : false,
"_id" : "male/john",
"_rev" : "31557225",
"_key" : "john"
}
```
!SUBSECTION Update
Updates the data of a vertex in collection *vertexCollectionName*
`general-graph.vertexCollectionName.update(vertexId, data, options)`
*vertexId*: string - id of the vertex
*data*: json - data of vertex
*options*: json - (optional) - see collection documentation
@EXAMPLES
```
arangosh> var examples = require("org/arangodb/graph-examples/example-graph.js");
arangosh> var g = examples.loadGraph("social");
arangosh> g.female.save({name: "Lynda", _key: "linda"});
{
"error" : false,
"_id" : "female/linda",
"_rev" : "79201897",
"_key" : "linda"
}
arangosh> g.female.update({name: "Linda", _key: "linda"});
TypeError: Object #