From 8082941e94a056f530aac56bcf088f8500936a62 Mon Sep 17 00:00:00 2001 From: Thomas Schmidts Date: Tue, 17 Jun 2014 11:21:15 +0200 Subject: [PATCH 1/5] Added Upgrading to gitbook --- Documentation/Books/Users/Installing/README.mdpp | 3 +++ Documentation/Books/Users/SUMMARY.md | 2 ++ .../Users/localtheme/templates/includes/book/summary.html | 3 +++ Documentation/Books/codeBlockReader.py | 8 +++----- 4 files changed, 11 insertions(+), 5 deletions(-) diff --git a/Documentation/Books/Users/Installing/README.mdpp b/Documentation/Books/Users/Installing/README.mdpp index eee0d32c6f..34eeae3873 100644 --- a/Documentation/Books/Users/Installing/README.mdpp +++ b/Documentation/Books/Users/Installing/README.mdpp @@ -7,3 +7,6 @@ You can find packages for various operation systems at our [download](http://www If you don't want to install ArangoDB at the beginning and just want to experiment with the features, you can use our [online demo](https://www.arangodb.org/tryitout). +In this Chapter you will also learn how to Compile ArangoDB from scratch. + +You also get help if you want to update your ArangoDB Version to the newest one! \ No newline at end of file diff --git a/Documentation/Books/Users/SUMMARY.md b/Documentation/Books/Users/SUMMARY.md index b6db35e7e4..75aee80d43 100644 --- a/Documentation/Books/Users/SUMMARY.md +++ b/Documentation/Books/Users/SUMMARY.md @@ -5,6 +5,8 @@ * [Mac OS X](Installing/MacOSX.md) * [Windows](Installing/Windows.md) * [Compiling](Installing/Compiling.md) + * [Upgrading in general](Installing/Upgrading.md) + * [Set up Cluster](Installing/Cluster.md) * [First Steps](FirstSteps/README.md) * [Getting Familiar](FirstSteps/GettingFamiliar.md) diff --git a/Documentation/Books/Users/localtheme/templates/includes/book/summary.html b/Documentation/Books/Users/localtheme/templates/includes/book/summary.html index 0e28246b0d..e2005047f3 100644 --- a/Documentation/Books/Users/localtheme/templates/includes/book/summary.html +++ b/Documentation/Books/Users/localtheme/templates/includes/book/summary.html @@ -28,6 +28,9 @@
  • Have any questions?
    • +
  • + Whats New in this Version? +
    • {% endif %} {% if _divider %}
  • diff --git a/Documentation/Books/codeBlockReader.py b/Documentation/Books/codeBlockReader.py index ad7ad39709..90d93964ea 100644 --- a/Documentation/Books/codeBlockReader.py +++ b/Documentation/Books/codeBlockReader.py @@ -60,8 +60,7 @@ def fetch_comments(dirpath): if ("@startDocuBlock" in _text) or \ ("@endDocuBlock" in _text): fh.write("\n\n" % _text) - elif ("@EXAMPLE_ARANGOSH_OUTPUT" in _text or \ - "@EXAMPLE_ARANGOSH_RUN" in _text): + elif ("@EXAMPLE_ARANGOSH_OUTPUT" in _text): shouldIgnoreLine = True _filename = re.search("{(.*)}", _text).group(1) dirpath = os.path.abspath(os.path.join(os.path.dirname( __file__ ), os.pardir, "Examples", _filename + ".generated")) @@ -71,8 +70,7 @@ def fetch_comments(dirpath): print "Could not find code for " + _filename else: fh.write("%s\n" % _text) - elif ("@END_EXAMPLE_ARANGOSH_OUTPUT" in _text or \ - "@END_EXAMPLE_ARANGOSH_RUN" in _text): + elif ("@END_EXAMPLE_ARANGOSH_OUTPUT" in _text): shouldIgnoreLine = False fh.close() @@ -81,7 +79,7 @@ if __name__ == "__main__": open("allComments.txt", "w").close() path = ["arangod/cluster","arangod/RestHandler","arangod/V8Server", "lib/Admin","lib/HttpServer", - "js/actions","js/client","js/apps","js/common","js/server"] + "js/actions","js/client","js/apps/databases","js/apps/system/cerberus","js/apps/system/gharial","js/common","js/server"] for i in path: dirpath = os.path.abspath(os.path.join(os.path.dirname( __file__ ), os.pardir,"ArangoDB/../../"+i)) fetch_comments(dirpath) From 5f43e43979e73cfa4b6cfdef2aa27738b252d278 Mon Sep 17 00:00:00 2001 From: Michael Hackstein Date: Tue, 17 Jun 2014 11:21:22 +0200 Subject: [PATCH 2/5] Added more in-code documentation for the graph module --- .../modules/org/arangodb/general-graph.js | 88 +++++++++++++++++-- 1 file changed, 83 insertions(+), 5 deletions(-) diff --git a/js/common/modules/org/arangodb/general-graph.js b/js/common/modules/org/arangodb/general-graph.js index 7e7f317c55..d8b7be0e90 100644 --- a/js/common/modules/org/arangodb/general-graph.js +++ b/js/common/modules/org/arangodb/general-graph.js @@ -1427,8 +1427,28 @@ var _list = function() { return _.pluck(gdb.toArray(), "_key"); }; + + + //////////////////////////////////////////////////////////////////////////////// -/// @brief create a list of edge definitions +/// @startDocuBlock JSF_general_graph_edge_definitions +/// +/// The edge definitions for a graph is an array containing arbitrary many directed +/// and/or undirected relations as defined below. +/// The list of edge definitions of a graph can be managed by the graph module itself. +/// This function is the entry point for the management and will return the correct list. +/// +/// @EXAMPLES +/// +/// +/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeDefinitions} +/// var graph = require("org/arangodb/general-graph"); +/// directed-relation = graph._directedRelationDefinition("lives_in", "user", "city"); +/// undirected-relation = graph._directedRelationDefinition("knows", "user"); +/// edgedefinitions = graph._edgeDefinitions(directed-relation, undirected-relation); +/// @END_EXAMPLE_ARANGOSH_OUTPUT +/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// @@ -1445,10 +1465,24 @@ var _edgeDefinitions = function () { //////////////////////////////////////////////////////////////////////////////// -/// @brief extend a list of edge definitions +/// @startDocuBlock JSF_general_graph_extend_edge_definitions +/// +/// In order to add more edge definitions to the graph before creating +/// this function can be used to add more definitions to the initial list. +/// +/// @EXAMPLES +/// +/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeDefinitionsExtend} +/// var graph = require("org/arangodb/general-graph"); +/// directed-relation = graph._directedRelationDefinition("lives_in", "user", "city"); +/// undirected-relation = graph._directedRelationDefinition("knows", "user"); +/// edgedefinitions = graph._edgeDefinitions(directed-relation); +/// edgedefinitions = graph._extendEdgeDefinitions(undirected-relation); +/// @END_EXAMPLE_ARANGOSH_OUTPUT +/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// - var _extendEdgeDefinitions = function (edgeDefinition) { var args = arguments, i = 0; @@ -1991,7 +2025,27 @@ var Graph = function(graphName, edgeDefinitions, vertexCollections, edgeCollecti //////////////////////////////////////////////////////////////////////////////// -/// @brief load a graph. +/// @startDocuBlock JSF_general_graph_graph +/// `general-graph._graph(graph-name)` +/// *Load a graph* +/// +/// A graph can be loaded by its name. +/// +/// * *graph-name*: string - unique identifier of the graph +/// +/// @EXAMPLES +/// +/// Load a graph: +/// +/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionSave} +/// ~ var examples = require("org/arangodb/graph-examples/example-graph.js"); +/// ~ var g1 = examples.loadGraph("social"); +/// var graph = require("org/arangodb/general-graph"); +/// g = graph._graph("social"); +/// @END_EXAMPLE_ARANGOSH_OUTPUT +/// +/// @endDocuBlock +/// //////////////////////////////////////////////////////////////////////////////// var _graph = function(graphName) { @@ -2070,7 +2124,31 @@ var checkIfMayBeDropped = function(colName, graphName, graphs) { }; //////////////////////////////////////////////////////////////////////////////// -/// @brief drop a graph. +/// @startDocuBlock JSF_general_graph_drop +/// `general-graph._drop(graph-name, drop-collections)` +/// *Remove a graph* +/// +/// A graph can be dropped by its name. +/// This will automatically drop al collections contained in the graph as +/// long as they are not used within other graphs. +/// To prohibit the drop of collections, the optional parameter *drop-collections* can be set to *false*. +/// +/// * *graph-name*: string - unique identifier of the graph +/// * *drop-collections*: boolean (optional) - Define if collections should be dropped (default: true) +/// +/// @EXAMPLES +/// +/// Drop a graph: +/// +/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionSave} +/// ~ var examples = require("org/arangodb/graph-examples/example-graph.js"); +/// ~ var g1 = examples.loadGraph("social"); +/// var graph = require("org/arangodb/general-graph"); +/// graph._drop("social"); +/// @END_EXAMPLE_ARANGOSH_OUTPUT +/// +/// @endDocuBlock +/// //////////////////////////////////////////////////////////////////////////////// var _drop = function(graphId, dropCollections) { From 0ad502651dcd196a53cea07bb6102e7e4ad71067 Mon Sep 17 00:00:00 2001 From: Michael Hackstein Date: Tue, 17 Jun 2014 11:22:49 +0200 Subject: [PATCH 3/5] Improved ordering and structure of the graph management documentation --- .../Users/General-Graphs/Management.orig.mdpp | 299 ++---------------- 1 file changed, 34 insertions(+), 265 deletions(-) diff --git a/Documentation/Books/Users/General-Graphs/Management.orig.mdpp b/Documentation/Books/Users/General-Graphs/Management.orig.mdpp index 2b71122525..285a103190 100644 --- a/Documentation/Books/Users/General-Graphs/Management.orig.mdpp +++ b/Documentation/Books/Users/General-Graphs/Management.orig.mdpp @@ -1,8 +1,10 @@ -!SECTION Create a graph +!CHAPTER Graph Management - - -There are different types of edge definitions: +In order to create a graph the philosophy of handling the graph content has to introduced. +A graph contains a set of edge definitions each referring to one edge collection and +defining constraints on the vertex collections used as start and end points of the edges. +Furthermore a graph can contain an arbitrary amount of vertex collections, called orphan collections, that are not used in any edge definition but should be managed by the graph. +In order to create a graph the functionality to create edge definitions has to be introduced first: !SECTION Edge Definitions @@ -24,6 +26,31 @@ The edge definitions for a graph is an Array containing arbitrary many directed +!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 + + + +!SUBSUBSECTION Read + + + +!SUBSUBSECTION Remove + + + +!SECTION Create a graph + +After having introduced edge definitions and orphan collections a graph can be created. + + + + !SUBSUBSECTION Complete Example to create a graph Example Call: @@ -53,49 +80,14 @@ alternative call: _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. +!SUBSECTION Load a graph -!SUBSUBSECTION Add - - - -!SUBSUBSECTION Read - - - -!SUBSUBSECTION Remove - - - -!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 @@ -132,226 +124,3 @@ dropCollections: bool - optional. *true* all collections of the graph will be de !SUBSECTION Remove - -!SECTION Vertices - -!SUBSECTION Get vertex *from* of an edge - - - -!SUBSECTION Get vertex *to* of an edge - - - - - -!SECTION Some Methods - -```javascript -graph.listCommonNeighbors(vertex1, vertex2, options) -``` - -vertex1: string - vertex id -vertex2: string - vertex id -options: -* see getNeighbors - -```javascript -graph.amountCommonNeighbors(vertex1, vertex2, options) -``` - -vertex1: string - vertex id -vertex2: string - vertex id -options: -* see getNeighbors - - - -```javascript -graph.listCommonProperties((vertex1, vertex2) -``` - -vertex1: string - vertex id -vertex2: string - vertex id - - -```javascript -graph.amountCommonProperties((vertex1, vertex2) -``` - -vertex1: string - vertex id -vertex2: string - vertex id - - - - -```javascript -graph.pathTo(vertex1, vertex2, options) -``` - - -vertex1: string - vertex id -vertex2: string - vertex id -options: see determinePredecessors - - -```javascript -graph.distanceTo(vertex1, vertex2, options) -``` - - -vertex1: string - vertex id -vertex2: string - vertex id -options: see determinePredecessors - - -```javascript -graph.determinePredecessors(vertex1, source, options) -``` - - -vertex1: string - vertex id -source: ??? -options: -* cached: Boolean -> If true a cached version will be used - - -```javascript -graph.pathesForTree(vertex1, tree, path_to_here) -``` - -vertex1: string - vertex id -tree: ??? -path_to_here: Internal Array, should initially be undefined or an empty array - - -```javascript -graph.getNeighbors(vertex1, options) -``` - -vertex1: string - vertex id -options: - -* direction: - "inbound" -> consider only inbound edges - "outbount" -> consider only outbound edges - "any"(default) -> consider both directions -* weight: attribute-name -> use this attribute to determine edgeweight -* weight_function: function -> use this function to calculate the weight -* default-weight -> us this value if weight could not be calculated otherwise, default is Infinity -* only: function -> will be invoked on any edge, neighbors will only be included if this returns true or is not defined. - - -```javascript -graph.measurement(vertex1, measurement) -``` - -vertex1: string - vertex id -measurement: String -* "eccentricity": Calculates the eccentricity of the vertex -* "betweenness": Calculates the betweenness of the vertex -* "closeness": Calculates the closeness of the vertex - -!SECTION Using Graphs in AQL {#JSModuleGraphAQL} - -Complete Documentation can be copied from normal AQL documentation, with: - -* replace VertexCollection/EdgeCollection by Graph - -!SUBSECTION PATHS - -* **BUILD ON** `ahuacatl.js`: 4090 `GRAPH_PATHS` -> uses `COLLECTION` on second arg, has to use `COLLECTION` or `GRAPH` accordingly. Has to pass the graph to traverser - -Paths returns a handle for all paths included in the graph: - -`GRAPH_PATHS(graphname, direction, followcycles)` - -* `graphname` defines the graph -* `direction` defines the direction -* `followcycles` defines if cyclic paths should be followed - -Example calls: - -```javascript -FOR p in PATHS(shop, "outbound") - FILTER p.source._id == "123456/123456" && LENGTH(p.edges) == 2 - RETURN p.vertices[*].name -``` - - -!SUBSECTION TRAVERSAL - - -`GRAPH_TRAVERSAL(graphname, startVertex, direction, options)}` - -* **BUILD ON** `ahuacatl.js`: 4243 `TRAVERSAL_FUNC` -> uses `COLLECTION` on first and second arg, has to use `COLLECTION` or `GRAPH` accordingly. Has to pass the graph to traverser -* **TO CHANGE** `common/modules/org/arangodb/graph/traversal.js`: 106 `collectionDatasourceFactory` should be able to work on Graphs - -Traverses the graph described by the `graphname`, -starting at the vertex identified by id `startVertex`. Vertex connectivity is -specified by the `direction` parameter: - -- `"outbound"`: Vertices are connected in `_from` to `_to` order -- `"inbound"`: Vertices are connected in `_to` to `_from` order -- `"any"`: Vertices are connected in both `_to` to `_from` and in - `_from` to `_to` order - -All this is defined already for TRAVERSAL, no changes should be applied here - -```javascript -TRAVERSAL(shop, "products/arangodb", "outbound", { - strategy: "depthfirst", - order: "postorder", - itemOrder: "backward", - maxDepth: 6, - paths: true -}) -``` - - -!SUBSECTION TRAVERSAL_TREES - -`GRAPH_TRAVERSAL_TREE(graphname, startVertex, direction, connectName, options)` - -* **BUILD ON** `ahuacatl.js`: 4243 `TRAVERSAL_FUNC` -> uses `COLLECTION` on first and second arg, has to use `COLLECTION` or `GRAPH` accordingly. Has to pass the graph to traverser -* **TO CHANGE** `common/modules/org/arangodb/graph/traversal.js`: 106 `collectionDatasourceFactory` should be able to work on Graphs - -```javascript -GRAPH_TRAVERSAL_TREE(shop, "products/arangodb", "inbound", "sold", { - itemOrder: "forward" -}) -``` - -Makes internal use of TRAVERSAL, modyfing that is sufficient. - -!SUBSECTION SHORTEST_PATHS - - -* **BUILD ON** `ahuacatl.js`: 4243 `TRAVERSAL_FUNC` -> uses `COLLECTION` on first and second arg, has to use `COLLECTION` or `GRAPH` accordingly. Has to pass the graph to traverser -* **TO CHANGE** `common/modules/org/arangodb/graph/traversal.js`: 106 `collectionDatasourceFactory` should be able to work on Graphs - -`GRAPH_SHORTEST_PATH(graphname, startVertex, endVertex, direction, options)`: - -Equal to functionality of `SHORTEST_PATH`. -Makes internal use of TRAVERSAL, modyfing that is sufficient. - - -!SUBSECTION EDGES - - -* **BUILD ON** `ahuacatl.js`: 4479 `GRAPH_EDGES` -> uses `COLLECTION` on first argument, has to use `COLLECTION` or `GRAPH` accordingly. - -`GRAPH_EDGES(graphname, startvertex, direction, edgeexamples, collectionRestrictions)` - -Same as original, but with optional `collectionRestrictions`to define which edge collections have to be included. Default is all. - - -!SUBSECTION NEIGHBORS - - -* **BUILD ON** `ahuacatl.js`: 4508 `GRAPH_NEIGHBORS` -> uses `COLLECTION` on first, has to use `COLLECTION` or `GRAPH` accordingly. - -`GRAPH_NEIGHBORS(graphname, startvertex, direction, edgeexamples)` - -* Each of the graph functions in AQL (`PATHS`, `TRAVERSAL`, `TRAVERSAL_TREES`, `SHORTEST_PATHS`, `EDGES`, `NEIGHBORS`) will take the graph as its first argument (which parts of the other arguments will be pushed to be defined in FILTER and not in the signature of the function was discussed, but postponed because it is a detail). - From d4ad788710120f77926877320a7f8e6b46634baa Mon Sep 17 00:00:00 2001 From: Michael Hackstein Date: Tue, 17 Jun 2014 11:23:12 +0200 Subject: [PATCH 4/5] Moved Vertex operations to Functions in graph module documentation --- .../Books/Users/General-Graphs/Functions.mdpp | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/Documentation/Books/Users/General-Graphs/Functions.mdpp b/Documentation/Books/Users/General-Graphs/Functions.mdpp index 2f9fdc4288..511ff75af2 100644 --- a/Documentation/Books/Users/General-Graphs/Functions.mdpp +++ b/Documentation/Books/Users/General-Graphs/Functions.mdpp @@ -2,6 +2,16 @@ Write Intro! +!SECTION Get vertices from edges. + +!SUBSECTION Get vertex *from* of an edge + + + +!SUBSECTION Get vertex *to* of an edge + + + !SECTION Some Methods ```javascript From 4efec4b58ea9629d0739b6de9b643f08e0f513f5 Mon Sep 17 00:00:00 2001 From: Michael Hackstein Date: Tue, 17 Jun 2014 11:26:16 +0200 Subject: [PATCH 5/5] Moved list of all available graphs in the management documentation --- .../Users/General-Graphs/Management.orig.mdpp | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Documentation/Books/Users/General-Graphs/Management.orig.mdpp b/Documentation/Books/Users/General-Graphs/Management.orig.mdpp index 285a103190..667baa24f1 100644 --- a/Documentation/Books/Users/General-Graphs/Management.orig.mdpp +++ b/Documentation/Books/Users/General-Graphs/Management.orig.mdpp @@ -81,6 +81,21 @@ alternative call: }; ``` +!SUBSECTION List available graphs + + +`general-graph._list()` *List all graphs.* +
    +
    + + + +
    +@EXAMPLES +
    + + + !SUBSECTION Load a graph