Smart Graph Management

    • General Graphs do not enforce or maintain any sharding of the collectionsand can therefore combine arbitrary sets of existing collections.
    • SmartGraphs enforce and rely on a special sharding of the underlyingcollections and hence can only work with collections that are createdthrough the SmartGraph itself. This also means that SmartGraphs cannot beoverlapping. A collection can either be sharded for one SmartGraph or foranother. If you need to make sure that all queries can be executed withSmartGraph performance, just create one large SmartGraph covering everythingand query it stating the subset of edge collections explicitly.

    To generally understand the concept of this module please read the chapterabout first.In the following we will only describe the overloaded functionality.Everything else works identical in both modules.

    SmartGraphs also require edge relations to be created. The format of therelations is identical. The only difference is that all collections used withinthe relations to create a new SmartGraph must not exist yet. You have to letthe SmartGraph module create the Graph collections for you, so that it canenforce the correct sharding.

    • graphName (string):Unique identifier of the graph
    • edgeDefinitions (array):List of relation definition objects, may be empty
    • orphanCollections (array):List of additional vertex collection names, may be empty
    • smartOptions (object):A JSON object having the following keys:
      • numberOfShards (number):The number of shards that will be created for each collection. To maintainthe correct sharding all collections need an identical number of shards.This cannot be modified after creation of the graph.
      • smartGraphAttribute (string):The attribute that will be used for sharding. All vertices are required tohave this attribute set and it has to be a string. Edges derive theattribute from their connected vertices.

    The creation of a graph requires the name and some SmartGraph options.Due to the API edgeDefinitions and orphanCollections have to be given, butboth can be empty arrays and be added later.

    The edgeDefinitions can be created using the convenience method known from the general-graph module, which is also available here.

    orphanCollections again is just a list of additional vertex collections whichare not yet connected via edges but should follow the same sharding to beconnected later on.

    All collections used within the creation process are newly created.The process will fail if one of them already exists, unless they have thecorrect sharding already. All newly created collections will immediatelybe dropped again in the failure case.

    Examples

    Create a graph without relations. Edge definitions can be added later:

    Show execution results

    Hide execution results

    1. {[SmartGraph] 
    2. }

    Create a graph using an edge collection edges and a single vertex collectionvertices as relation:

    1. arangosh> var graph_module = require("@arangodb/smart-graph");
    2. arangosh> var edgeDefinitions = [ graph_module._relation("edges", "vertices", "vertices") ];
    3. arangosh> var graph = graph_module._create("myGraph", edgeDefinitions, [], {smartGraphAttribute: "region", numberOfShards: 9});
    4. arangosh> graph_module._graph("myGraph");

    Show execution results

    Hide execution results

    1. {[SmartGraph] 
    2.   "edges" : [ArangoCollection 2010064, "edges" (type edge, status loaded)], 
    3.   "vertices" : [ArangoCollection 2010054, "vertices" (type document, status loaded)] 
    4. }

    Create a graph with edge definitions and orphan collections:

    1. arangosh> var graph_module = require("@arangodb/smart-graph");
    2. arangosh> var edgeDefinitions = [ graph_module._relation("myRelation", ["male", "female"], ["male", "female"]) ];
    3. arangosh> graph_module._graph("myGraph");

    Show execution results

    Hide execution results

    1. {[SmartGraph] 
    2.   "myRelation" : [ArangoCollection 2010107, "myRelation" (type edge, status loaded)], 
    3.   "female" : [ArangoCollection 2010105, "female" (type document, status loaded)], 
    4.   "male" : [ArangoCollection 2010106, "male" (type document, status loaded)], 
    5.   "sessions" : [ArangoCollection 2010095, "sessions" (type document, status loaded)] 
    6. }

    Modify a graph definition at runtime

    After you have created a SmartGraph its definition is not immutable. You canstill add or remove relations. This is again identical to General Graphs.

    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.

    In most cases this function works identically to the General Graph one.But there is one special case: The first vertex collection added to the graph(either orphan or within a relation) defines the sharding for all collectionswithin the graph. They have their distributeShardsLike attribute set to thename of the initial collection. This collection can not be dropped as long asother collections follow its sharding (i.e. they need to be dropped first).

    Examples

    Create a SmartGraph and list its orphan collections:

    1. arangosh> var graph_module = require("@arangodb/smart-graph");
    2. arangosh> var relation = graph_module._relation("edges", "vertices", "vertices");
    3. arangosh> var graph = graph_module._create("myGraph", [relation], ["other"], {smartGraphAttribute: "region", numberOfShards: 9});
    4. arangosh> graph._orphanCollections();

    Show execution results

    Hide execution results

    1. [ 
    2.   "other" 
    3. ]

    Remove the orphan collection from the SmartGraph and drop the collection:

    Show execution results

    Hide execution results

    1. {[SmartGraph] 
    2.   "edges" : [ArangoCollection 2010309, "edges" (type edge, status loaded)], 
    3.   "vertices" : [ArangoCollection 2010298, "vertices" (type document, status loaded)] 
    4. }

    Attempting to remove a non-orphan collection results in an error:

    1. arangosh> graph._removeVertexCollection("vertices");

    Show execution results

    Hide execution results

    1. [ArangoError 1928: collection is not in list of orphan collections]

    You cannot drop the initial collection (vertices) as long as it defines thesharding for other collections ().

    1. arangosh> var graph_module = require("@arangodb/smart-graph");
    2. arangosh> var relation = graph_module._relation("edges", "vertices", "vertices");
    3. arangosh> var graph = graph_module._create("myGraph", [relation], [], {smartGraphAttribute: "region", numberOfShards: 9});
    4. arangosh> graph._removeVertexCollection("vertices");
    5. arangosh> db._drop("vertices");

    Show execution results

    Hide execution results

    1. [ArangoError 1485: Collection 'vertices' must not be dropped while '_to_edges', '_local_edges', 'edges', '_from_edges' have distributeShardsLike set to 'vertices'.]

    You may drop the complete graph, but remember to drop collections that youmight have removed from the graph beforehand, as they will not be part of thegraph definition anymore and thus not be dropped for you. Alternatively, youcan truncate the graph if you just want to get rid of the data.

    1. arangosh> var graph_module = require("@arangodb/smart-graph");
    2. arangosh> var relation = graph_module._relation("edges", "vertices", "vertices");
    3. arangosh> var graph = graph_module._create("myGraph", [relation], [], {smartGraphAttribute: "region", numberOfShards: 9});
    4. arangosh> graph._deleteEdgeDefinition("edges");
    5. arangosh> graph._removeVertexCollection("vertices");
    6. arangosh> graph_module._drop("myGraph", true); // does not drop any collections
    7. arangosh> db._drop("edges"); // drop before sharding-defining 'vertices' collection
    8. arangosh> db._drop("vertices");

    Show execution results

    1.  

    Delete an edge definition from the graph:

    graph._deleteEdgeDefinition(edgeCollectionName, dropCollection)

    • edgeCollectionName (string):Name of edge collection.
    • dropCollection (bool, optional):If true the collection will be dropped if it is not used in any other graph.Default: false.

    Examples

    Create a SmartGraph, then delete the edge definition and drop the edge collection:

    Show execution results

    Hide execution results

    1. {[SmartGraph] 
    2.   "vertices" : [ArangoCollection 2010472, "vertices" (type document, status loaded)] 
    3. }

    It is allowed to remove the vertex collection vertices if it’s not used inany relation (i.e. after the deletion of the edge definition):

    1. arangosh> graph._deleteEdgeDefinition("edges");
    2. arangosh> graph._removeVertexCollection("vertices");

    Show execution results

    Hide execution results

    1.  

    Keep in mind that you can not drop the vertices collection until no othercollection references it anymore (distributeShardsLike collection property).

    Remove a SmartGraph:

    graph_module._drop(graphName, dropCollections)

    • graphName (string):Name of the Graph.
    • (bool, optional):Define if collections should be dropped. Default: false.

    Examples

    Delete a SmartGraph and drop its collections:

    1. arangosh> graph_module._drop("myGraph", true);

    Show execution results

    Hide execution results

    1.  

    Note that removing a Graph with the option to drop the collections fails ifyou removed collections from the Graph but did not drop these collections.This is because their distributeShardsLike attribute still referencescollections that are part of the Graph. Dropping collections while otherspoint to them in this way is not allowed. Make sure to drop the referencingcollections first.

    1. arangosh> graph._removeVertexCollection("other");

    Show execution results

    1. [ArangoError 1485: Collection 'vertices' must not be dropped while 'other' has distributeShardsLike set to 'vertices'.]