Feature Hybrid SmartGraphs

3.9/generated/Examples/hybridSmartGraphCreateGraphHowTo1_cluster.generated

@@ -0,0 +1,9 @@
+arangosh&gt; <span class="hljs-keyword">var</span> graph_module = <span class="hljs-built_in">require</span>(<span class="hljs-string">&quot;@arangodb/smart-graph&quot;</span>);
+arangosh&gt; <span class="hljs-keyword">var</span> rel = graph_module._relation(<span class="hljs-string">&quot;isCustomer&quot;</span>, <span class="hljs-string">&quot;shop&quot;</span>, <span class="hljs-string">&quot;customer&quot;</span>)
+arangosh&gt; <span class="hljs-keyword">var</span> graph = graph_module._create(<span class="hljs-string">&quot;myGraph&quot;</span>, [rel], [], {<span class="hljs-attr">satellites</span>: [<span class="hljs-string">&quot;shop&quot;</span>, <span class="hljs-string">&quot;customer&quot;</span>], <span class="hljs-attr">smartGraphAttribute</span>: <span class="hljs-string">&quot;region&quot;</span>, <span class="hljs-attr">numberOfShards</span>: <span class="hljs-number">9</span>});
+arangosh&gt; graph_module._graph(<span class="hljs-string">&quot;myGraph&quot;</span>);
+{[SmartGraph] 
+  <span class="hljs-string">&quot;isCustomer&quot;</span> : [ArangoCollection <span class="hljs-number">10060</span>, <span class="hljs-string">&quot;isCustomer&quot;</span> (type edge, status loaded)], 
+  <span class="hljs-string">&quot;shop&quot;</span> : [ArangoCollection <span class="hljs-number">10058</span>, <span class="hljs-string">&quot;shop&quot;</span> (type <span class="hljs-built_in">document</span>, status loaded)], 
+  <span class="hljs-string">&quot;customer&quot;</span> : [ArangoCollection <span class="hljs-number">10059</span>, <span class="hljs-string">&quot;customer&quot;</span> (type <span class="hljs-built_in">document</span>, status loaded)] 
+}

3.9/generated/Examples/hybridSmartGraphCreateGraphHowTo2_cluster.generated

@@ -0,0 +1,9 @@
+arangosh&gt; <span class="hljs-keyword">var</span> graph_module = <span class="hljs-built_in">require</span>(<span class="hljs-string">&quot;@arangodb/smart-graph&quot;</span>);
+arangosh&gt; <span class="hljs-keyword">var</span> rel = graph_module._relation(<span class="hljs-string">&quot;isCustomer&quot;</span>, <span class="hljs-string">&quot;shop&quot;</span>, <span class="hljs-string">&quot;customer&quot;</span>)
+arangosh&gt; <span class="hljs-keyword">var</span> graph = graph_module._create(<span class="hljs-string">&quot;myGraph&quot;</span>, [rel], [], {<span class="hljs-attr">satellites</span>: [<span class="hljs-string">&quot;shop&quot;</span>], <span class="hljs-attr">smartGraphAttribute</span>: <span class="hljs-string">&quot;region&quot;</span>, <span class="hljs-attr">isDisjoint</span>: <span class="hljs-literal">true</span>, <span class="hljs-attr">numberOfShards</span>: <span class="hljs-number">9</span>});
+arangosh&gt; graph_module._graph(<span class="hljs-string">&quot;myGraph&quot;</span>);
+{[SmartGraph] 
+  <span class="hljs-string">&quot;isCustomer&quot;</span> : [ArangoCollection <span class="hljs-number">10079</span>, <span class="hljs-string">&quot;isCustomer&quot;</span> (type edge, status loaded)], 
+  <span class="hljs-string">&quot;shop&quot;</span> : [ArangoCollection <span class="hljs-number">10078</span>, <span class="hljs-string">&quot;shop&quot;</span> (type <span class="hljs-built_in">document</span>, status loaded)], 
+  <span class="hljs-string">&quot;customer&quot;</span> : [ArangoCollection <span class="hljs-number">10068</span>, <span class="hljs-string">&quot;customer&quot;</span> (type <span class="hljs-built_in">document</span>, status loaded)] 
+}

3.9/graphs-general-graphs-management.md

@@ -118,6 +118,16 @@ collection in *toVertexCollections*.
 {% endarangoshexample %}
 {% include arangoshexample.html id=examplevar script=script result=result %}
 
+### Edge Definition Options
+
+The following edge definition options are supported:
+
+- `satellites` (array):
+  An array of collection names that will be used to create [SatelliteCollections](satellites.html)
+  for a Hybrid (Disjoint) SmartGraph (Enterprise Edition only). Each array element
+  must be a string and a valid collection name. The collection type cannot be
+  modified later.
+
 Create a Graph
 --------------
 
@@ -336,17 +346,20 @@ Drop a graph and keep collections:
 Modify a Graph definition at runtime
 ------------------------------------
 
-After you have created an graph its definition is not immutable.
+After you have created a 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)`
+`graph._extendEdgeDefinitions(edgeDefinition, options)`
 
 - `edgeDefinition` (object):
   The relation definition to extend the graph
+- `options` (object):
+  Additional options related to the edge definition itself.
+  See [Edge Definition Options](#edge-definition-options).
 
 Extends the edge definitions of a graph. If an orphan collection is used in this
 edge definition, it will be removed from the orphanage. If the edge collection of
@@ -374,11 +387,14 @@ graph with different *from* and/or *to* collections an error is thrown.
 
 Modify a relation definition:
 
-`graph_module._editEdgeDefinitions(edgeDefinition)`
+`graph_module._editEdgeDefinitions(edgeDefinition, options)`
 
 - `edgeDefinition` (object):
   The edge definition to replace the existing edge definition with the same
   attribute *collection*.
+- `options` (object):
+  Additional options related to the edge definition itself.
+  See [Edge Definition Options](#edge-definition-options).
 
 Edits one relation definition of a graph. The edge definition used as argument will
 replace the existing edge definition of the graph which has the same collection.
@@ -470,12 +486,15 @@ orphans, it will be removed from the set of orphan collection automatically.
 
 Add a vertex collection to the graph:
 
-`graph._addVertexCollection(vertexCollectionName, createCollection)`
+`graph._addVertexCollection(vertexCollectionName, createCollection, options)`
 
 - `vertexCollectionName` (string):
   Name of vertex collection.
 - `createCollection` (bool, _optional_):
   If true the collection will be created if it does not exist. Default: true
+- `options` (object, _optional_):
+  Additional options related to the edge definition itself.
+  See [Edge Definition Options](#edge-definition-options).
 
 Adds a vertex collection to the set of orphan collections of the graph. If the
 collection does not exist, it will be created. If it is already used by any edge

3.9/graphs-smart-graphs-management.md

@@ -57,6 +57,11 @@ enforce the correct sharding.
   - `isDisjoint` (bool, optional):
     If set to true, a Disjoint SmartGraph will be created. This flag is not
     editable after creation. Default: false.
+  - `satellites` (array, optional):
+    An array of collection names that will be used to create
+    [SatelliteCollections](satellites.html) for a Hybrid (Disjoint) SmartGraph.
+    Each array element must be a string and a valid collection name.
+    The collection type cannot be modified later.
 
 The creation of a graph requires the name and some SmartGraph options.
 Due to the API `edgeDefinitions` and `orphanCollections` have to be given, but

3.9/graphs-smart-graphs.md

@@ -71,9 +71,21 @@ overhead. The more subgraphs are touched the more network cost will apply.
 However the overall performance is never worse than the same query using a
 General Graph.
 
-Benefits of Disjoint SmartGraphs
+Benefits of Hybrid SmartGraphs
 -------------------------------
 
+Hybrid SmartGraphs are capable of using SatelliteCollections within their graph
+definition. Therefore, edge definitions defined between SmartCollections and
+SatelliteCollections can be created. As SatelliteCollections (and the edge
+collections between SmartGraph collections and SatelliteCollection) are globally
+replicated to each participating DB-Server, (weighted) graph traversals and
+(k-)shortest path(s) queries can partially be executed locally on each
+DB-Server. This means a larger part of the query can be executed fully local
+whenever data from the SatelliteCollections is required.
+
+Benefits of Disjoint SmartGraphs
+--------------------------------
+
 Disjoint SmartGraphs are a specialized type of SmartGraphs. 
 
 In addition to the guaranteed sharding in SmartGraphs, a Disjoint SmartGraph
@@ -83,6 +95,16 @@ This ensures that graph traversals, shortest path, and k-shortest-paths queries
 can be executed locally on a DB-Server, achieving improved performance for
 these type of queries.
 
+Benefits of Hybrid Disjoint SmartGraphs
+---------------------------------------
+
+Hybrid Disjoint SmartGraphs are like Hybrid SmartGraphs but also prohibit
+edges between vertices with different `smartGraphAttribute` values. This
+restriction makes it unnecessary to replicate the edge collections between
+SmartGraph collections and SatelliteCollections to all DB-Servers for local
+execution. They are sharded like the SmartGraph collections instead
+(`distributeShardsLike`).
+
 Getting started
 ---------------
 
@@ -177,3 +199,43 @@ correct sharding already).
     @endDocuBlock smartGraphCreateGraphHowTo3_cluster
 {% endarangoshexample %}
 {% include arangoshexample.html id=examplevar script=script result=result %}
+
+**Create a Hybrid SmartGraph**
+
+In addition to the attributes you would set to create a SmartGraph, there is an
+additional attribute `satellites` you need to 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.
+In this example, both vertex collections are created as SatelliteCollections:
+
+{% arangoshexample examplevar="examplevar" script="script" result="result" %}
+    @startDocuBlockInline hybridSmartGraphCreateGraphHowTo1_cluster
+    @EXAMPLE_ARANGOSH_OUTPUT{hybridSmartGraphCreateGraphHowTo1_cluster}
+      var graph_module = require("@arangodb/smart-graph");
+      var rel = graph_module._relation("isCustomer", "shop", "customer")
+      var graph = graph_module._create("myGraph", [rel], [], {satellites: ["shop", "customer"], smartGraphAttribute: "region", numberOfShards: 9});
+      graph_module._graph("myGraph");
+     ~graph_module._drop("myGraph", true);
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock hybridSmartGraphCreateGraphHowTo1_cluster
+{% endarangoshexample %}
+{% include arangoshexample.html id=examplevar script=script result=result %}
+
+**Create a Hybrid Disjoint SmartGraph**
+
+The option `isDisjoint` needs to be set to `true` in addition to the other
+options for a Hybrid SmartGraph. Only the `shop` vertex collection is created
+as a SatelliteCollection in this example:
+
+{% arangoshexample examplevar="examplevar" script="script" result="result" %}
+    @startDocuBlockInline hybridSmartGraphCreateGraphHowTo2_cluster
+    @EXAMPLE_ARANGOSH_OUTPUT{hybridSmartGraphCreateGraphHowTo2_cluster}
+      var graph_module = require("@arangodb/smart-graph");
+      var rel = graph_module._relation("isCustomer", "shop", "customer")
+      var graph = graph_module._create("myGraph", [rel], [], {satellites: ["shop"], smartGraphAttribute: "region", isDisjoint: true, numberOfShards: 9});
+      graph_module._graph("myGraph");
+     ~graph_module._drop("myGraph", true);
+    @END_EXAMPLE_ARANGOSH_OUTPUT
+    @endDocuBlock hybridSmartGraphCreateGraphHowTo2_cluster
+{% endarangoshexample %}
+{% include arangoshexample.html id=examplevar script=script result=result %}

3.9/highlights.md

@@ -19,6 +19,10 @@ Version 3.9
 
 **Enterprise Edition**
 
+- [**Hybrid (Disjoint) SmartGraphs**](graphs-smart-graphs.html#benefits-of-hybrid-smartgraphs):
+  SatelliteCollections can be used in (Disjoint) SmartGraphs to enable more
+  local execution of graph queries.
+
 Also see [What's New in 3.9](release-notes-new-features39.html).
 
 Version 3.8

3.9/release-notes-api-changes39.md

@@ -11,6 +11,45 @@ integrations for ArangoDB 3.9.
 
 ## HTTP RESTful API
 
+### Graph API (Gharial)
+
+The following changes affect the behavior of the RESTful graph APIs at
+endpoints starting with path `/_api/gharial/`:
+
+The options object now supports a new optional field `satellites` in the
+Enterprise Edition when creating a graph (POST method). If set, it needs to be
+an array of collection names. Each name must be a string and valid as collection
+name. The `satellites` option is ignored in the Community Edition.
+
+Using `satellites` during SmartGraph creation will result in a Hybrid SmartGraph.
+Using `satellites` during Disjoint SmartGraph creation will result in a Hybrid
+Disjoint SmartGraph.
+
+Hybrid (Disjoint) SmartGraphs are capable of having SatelliteCollections in their
+graph definitions. If a collection is named in `satellites` and also used in the
+graph definition itself (e.g. EdgeDefinition), this collection will be created
+as a SatelliteCollection. Hybrid (Disjoint) SmartGraphs are then capable of
+executing all types of graph queries between the regular SmartCollections and
+SatelliteCollections.
+
+The following changes affect the behavior of the RESTful graph APIs at
+endpoints starting with path `/_api/gharial/{graph}/edge` and
+`/_api/gharial/{graph}/vertex`:
+
+Added new optional `options` object that can be set when creating a new or
+modifying an existing edge definition (POST / PUT method), as well as when
+creating a new vertex collection (POST method). This was not available in
+previous ArangoDB versions. The `options` object can currently contain a field
+called `satellites` only.
+
+The `satellites` field must be an array with one or more collection name strings.
+If an EdgeDefinition contains a collection name that is also contained in the
+`satellites` option, or if the vertex collection to add is contained in the
+`satellites` option, the collection will be created as a SatelliteCollection.
+Otherwise, it will be ignored. This option only takes effect using SmartGraphs.
+
+Also see [Graph Management](http/gharial-management.html).
+
 ### Extended naming convention for databases
 
 There is a new startup option `--database.extended-names-databases` to allow

3.9/release-notes-new-features39.md

@@ -9,6 +9,38 @@ The following list shows in detail which features have been added or improved in
 ArangoDB 3.9. ArangoDB 3.9 also contains several bug fixes that are not listed
 here.
 
+Hybrid (Disjoint) SmartGraphs (Enterprise Edition)
+--------------------------------------------------
+
+SmartGraphs have been extended with a new option to create Hybrid SmartGraphs.
+Hybrid SmartGraphs are capable of using SatelliteCollections within their graph
+definition and therefore can make use of all the benefits of
+[SatelliteCollections](satellites.html).
+
+Edge definitions can now be created between SmartCollections and
+SatelliteCollections. As SatelliteCollections are globally replicated to each
+participating DB-Server, regular graph traversals, weighted traversals,
+shortest path, and k shortest paths queries can partially be executed locally on
+each DB-Server. This means that query execution can be fully local whenever
+actual data from the SatelliteCollections is being processed. This can improve
+data locality and reduce the number of network hops between cluster nodes.
+
+In case you do have collections that are needed in almost every traversal but
+are small enough to be copied over to every participating DB-Server,
+Hybrid SmartGraphs are the perfect fit, as this will increase the amount of
+local query execution.
+
+Hybrid SmartGraphs can also be disjoint. A Disjoint SmartGraph prohibits edges
+connecting different SmartGraph components. The same rule applies to
+[Hybrid Disjoint SmartGraphs](graphs-smart-graphs.html#benefits-of-hybrid-disjoint-smartgraphs).
+If your graph does not need edges between vertices with different SmartGraph
+attribute values, then you should enable this option. This topology restriction
+allows the query optimizer to improve traversal execution times, because the
+execution can be pushed down to a single DB-Server in many cases.
+
+[Hybrid SmartGraphs](graphs-smart-graphs.html#benefits-of-hybrid-smartgraphs)
+are only available in the Enterprise Edition.
+
 ArangoSearch
 ------------