Getting started

SmartGraphs cannot use existing collections. When switching to SmartGraph from an existing dataset you have to import the data into a fresh SmartGraph.

All collections that are being used in SmartGraphs need to be part of the same distributeShardslike group. The smartGraphAttribute and the number of shards are immutable. The smartGraphAttribute attribute is used to inform the database how to shard data and, as a consequence, all vertices must have this attribute. The _from and _to attributes that point from one document to another document stored in vertex collections are set by default, following the same smart sharding pattern.

Create a SmartGraph

In contrast to General Graphs we have to add more options when creating the SmartGraph. The two options smartGraphAttribute and numberOfShards are required and cannot be modified later.

arangosh> var graph_module = require("@arangodb/smart-graph");
arangosh> var graph = graph_module._create("myGraph", [], [], {smartGraphAttribute: "region", numberOfShards: 9});
arangosh> graph_module._graph("myGraph");

{[SmartGraph] 
}

Create a Disjoint SmartGraph

In contrast to regular SmartGraphs we have to add one option when creating the graph. The boolean option isDisjoint is required, needs to be set to true and cannot be modified later.

arangosh> var graph_module = require("@arangodb/smart-graph");
arangosh> var graph = graph_module._create("myGraph", [], [], {smartGraphAttribute: "region", numberOfShards: 9, isDisjoint: true});
arangosh> graph_module._graph("myGraph");

{[SmartGraph] 
}

Add vertex collections

This is analogous to General Graphs. Unlike with General Graphs, the collections must not exist when creating the SmartGraph. The SmartGraph module will create them for you automatically to set up the sharding for all these collections correctly. If you create collections via the SmartGraph module and remove them from the graph definition, then you may re-add them without trouble however, as they will have the correct sharding.

arangosh> graph._addVertexCollection("shop");
arangosh> graph._addVertexCollection("customer");
arangosh> graph._addVertexCollection("pet");
arangosh> graph_module._graph("myGraph");

{[SmartGraph] 
  "customer" : [ArangoCollection 11264, "customer" (type document, status loaded)], 
  "pet" : [ArangoCollection 11275, "pet" (type document, status loaded)], 
  "shop" : [ArangoCollection 11253, "shop" (type document, status loaded)] 
}

Define relations on the Graph

Adding edge collections works the same as with General Graphs, but again, the collections are created by the SmartGraph module to set up sharding correctly so they must not exist when creating the SmartGraph (unless they have the correct sharding already).

arangosh> var rel = graph_module._relation("isCustomer", ["shop"], ["customer"]);
arangosh> graph._extendEdgeDefinitions(rel);
arangosh> graph_module._graph("myGraph");

{[SmartGraph] 
  "isCustomer" : [ArangoCollection 11330, "isCustomer" (type edge, status loaded)], 
  "shop" : [ArangoCollection 11296, "shop" (type document, status loaded)], 
  "customer" : [ArangoCollection 11307, "customer" (type document, status loaded)], 
  "pet" : [ArangoCollection 11318, "pet" (type document, status loaded)] 
}

Using SatelliteCollections in SmartGraphs

When creating a collection, you can decide whether it’s a SatelliteCollection or not. For example, a vertex collection can be satellite as well. SatelliteCollections don’t require sharding as the data will be distributed globally on all DB-Servers. The smartGraphAttribute is also not required.

Create a SmartGraph using SatelliteCollections

In addition to the attributes you would set to create a SmartGraph, there is an additional attribute satellites you can optionally set. It needs to be an array of one or more collection names. These names can be used in edge definitions (relations) and these collections will be created as SatelliteCollections. However, all vertex collections on one side of the relation have to be of the same type - either all satellite or all smart. This is because _from and _to can have different types based on the sharding pattern.

In this example, both vertex collections are created as SatelliteCollections.

arangosh> var graph_module = require("@arangodb/smart-graph");
arangosh> var rel = graph_module._relation("isCustomer", "shop", "customer")
arangosh> var graph = graph_module._create("myGraph", [rel], [], {satellites: ["shop", "customer"], smartGraphAttribute: "region", numberOfShards: 9});
arangosh> graph_module._graph("myGraph");

{[SmartGraph] 
  "isCustomer" : [ArangoCollection 10803, "isCustomer" (type edge, status loaded)], 
  "shop" : [ArangoCollection 10801, "shop" (type document, status loaded)], 
  "customer" : [ArangoCollection 10802, "customer" (type document, status loaded)] 
}

Create a Disjoint SmartGraph using SatelliteCollections

The option isDisjoint needs to be set to true in addition to the other options for a SmartGraph using SatelliteCollections. Only the shop vertex collection is created as a SatelliteCollection in this example:

arangosh> var graph_module = require("@arangodb/smart-graph");
arangosh> var rel = graph_module._relation("isCustomer", "shop", "customer")
arangosh> var graph = graph_module._create("myGraph", [rel], [], {satellites: ["shop"], smartGraphAttribute: "region", isDisjoint: true, numberOfShards: 9});
arangosh> graph_module._graph("myGraph");

{[SmartGraph] 
  "isCustomer" : [ArangoCollection 10826, "isCustomer" (type edge, status loaded)], 
  "shop" : [ArangoCollection 10825, "shop" (type document, status loaded)], 
  "customer" : [ArangoCollection 10815, "customer" (type document, status loaded)] 
}