diff --git a/Documentation/DocuBlocks/DatabaseDirectory.md b/Documentation/DocuBlocks/DatabaseDirectory.md index 00c47fbc5c..74ba5a391f 100644 --- a/Documentation/DocuBlocks/DatabaseDirectory.md +++ b/Documentation/DocuBlocks/DatabaseDirectory.md @@ -1,27 +1,26 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock DatabaseDirectory -/// @brief path to the database -/// `--database.directory directory` -/// -/// The directory containing the collections and datafiles. Defaults -/// to */var/lib/arango*. When specifying the database directory, please -/// make sure the directory is actually writable by the arangod process. -/// -/// You should further not use a database directory which is provided by a -/// network filesystem such as NFS. The reason is that networked filesystems -/// might cause inconsistencies when there are multiple parallel readers or -/// writers or they lack features required by arangod (e.g. flock()). -/// -/// `directory` -/// -/// When using the command line version, you can simply supply the database -/// directory as argument. -/// -/// @EXAMPLES -/// -/// ``` -/// > ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory -/// /tmp/vocbase -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief path to the database +`--database.directory directory` + +The directory containing the collections and datafiles. Defaults +to */var/lib/arango*. When specifying the database directory, please +make sure the directory is actually writable by the arangod process. + +You should further not use a database directory which is provided by a +network filesystem such as NFS. The reason is that networked filesystems +might cause inconsistencies when there are multiple parallel readers or +writers or they lack features required by arangod (e.g. flock()). + +`directory` + +When using the command line version, you can simply supply the database +directory as argument. + +@EXAMPLES + +``` +> ./arangod --server.endpoint tcp://127.0.0.1:8529 --database.directory +/tmp/vocbase +``` + diff --git a/Documentation/DocuBlocks/DefaultLanguage.md b/Documentation/DocuBlocks/DefaultLanguage.md index f6f62bced8..75d4e7e194 100644 --- a/Documentation/DocuBlocks/DefaultLanguage.md +++ b/Documentation/DocuBlocks/DefaultLanguage.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock DefaultLanguage -/// @brief server default language for sorting strings -/// `--default-language default-language` -/// -/// The default language ist used for sorting and comparing strings. -/// The language value is a two-letter language code (ISO-639) or it is -/// composed by a two-letter language code with and a two letter country code -/// (ISO-3166). Valid languages are "de", "en", "en_US" or "en_UK". -/// -/// The default default-language is set to be the system locale on that -/// platform. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief server default language for sorting strings +`--default-language default-language` + +The default language ist used for sorting and comparing strings. +The language value is a two-letter language code (ISO-639) or it is +composed by a two-letter language code with and a two letter country code +(ISO-3166). Valid languages are "de", "en", "en_US" or "en_UK". + +The default default-language is set to be the system locale on that +platform. + diff --git a/Documentation/DocuBlocks/IndexHandle.md b/Documentation/DocuBlocks/IndexHandle.md index 6a12fb4185..a4525aa2d0 100644 --- a/Documentation/DocuBlocks/IndexHandle.md +++ b/Documentation/DocuBlocks/IndexHandle.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock IndexHandle -/// @brief finds an index -/// `db._index(index-handle)` -/// -/// Returns the index with *index-handle* or null if no such index exists. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{IndexHandle} -/// ~db._create("example"); -/// db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] }); -/// var indexInfo = db.example.getIndexes().map(function(x) { return x.id; }); -/// indexInfo; -/// db._index(indexInfo[0]) -/// db._index(indexInfo[1]) -/// ~db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief finds an index +`db._index(index-handle)` + +Returns the index with *index-handle* or null if no such index exists. + +@EXAMPLE_ARANGOSH_OUTPUT{IndexHandle} +~db._create("example"); +db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] }); +var indexInfo = db.example.getIndexes().map(function(x) { return x.id; }); +indexInfo; +db._index(indexInfo[0]) +db._index(indexInfo[1]) +~db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/IndexVerify.md b/Documentation/DocuBlocks/IndexVerify.md index 9e6ecac576..9010c7f36d 100644 --- a/Documentation/DocuBlocks/IndexVerify.md +++ b/Documentation/DocuBlocks/IndexVerify.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock IndexVerify -/// @brief finds an index -/// -/// So you've created an index, and since its maintainance isn't for free, -/// you definitely want to know whether your query can utilize it. -/// -/// You can use explain to verify whether **skiplists** or **hash indexes** are -/// used (if you omit `colors: false` you will get nice colors in ArangoShell): -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{IndexVerify} -/// ~db._create("example"); -/// var explain = require("@arangodb/aql/explainer").explain; -/// db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] }); -/// explain("FOR doc IN example FILTER doc.a < 23 RETURN doc", {colors:false}); -/// ~db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief finds an index + +So you've created an index, and since its maintainance isn't for free, +you definitely want to know whether your query can utilize it. + +You can use explain to verify whether **skiplists** or **hash indexes** are +used (if you omit `colors: false` you will get nice colors in ArangoShell): + +@EXAMPLE_ARANGOSH_OUTPUT{IndexVerify} +~db._create("example"); +var explain = require("@arangodb/aql/explainer").explain; +db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] }); +explain("FOR doc IN example FILTER doc.a < 23 RETURN doc", {colors:false}); +~db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/InsertEdgeCol.md b/Documentation/DocuBlocks/InsertEdgeCol.md index 9ed81b2fe3..a20fa7f88c 100644 --- a/Documentation/DocuBlocks/InsertEdgeCol.md +++ b/Documentation/DocuBlocks/InsertEdgeCol.md @@ -1,36 +1,35 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock InsertEdgeCol -/// @brief saves a new edge document -/// `edge-collection.insert(from, to, document)` -/// -/// Saves a new edge and returns the document-handle. *from* and *to* -/// must be documents or document references. -/// -/// `edge-collection.insert(from, to, document, waitForSync)` -/// -/// The optional *waitForSync* parameter can be used to force -/// synchronization of the document creation operation to disk even in case -/// that the *waitForSync* flag had been disabled for the entire collection. -/// Thus, the *waitForSync* parameter can be used to force synchronization -/// of just specific operations. To use this, set the *waitForSync* parameter -/// to *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_01_SaveEdgeCol} -/// db._create("vertex"); -/// db._createEdgeCollection("relation"); -/// v1 = db.vertex.insert({ name : "vertex 1" }); -/// v2 = db.vertex.insert({ name : "vertex 2" }); -/// e1 = db.relation.insert(v1, v2, { label : "knows" }); -/// db._document(e1); -/// ~ db._drop("relation"); -/// ~ db._drop("vertex"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief saves a new edge document +`edge-collection.insert(from, to, document)` + +Saves a new edge and returns the document-handle. *from* and *to* +must be documents or document references. + +`edge-collection.insert(from, to, document, waitForSync)` + +The optional *waitForSync* parameter can be used to force +synchronization of the document creation operation to disk even in case +that the *waitForSync* flag had been disabled for the entire collection. +Thus, the *waitForSync* parameter can be used to force synchronization +of just specific operations. To use this, set the *waitForSync* parameter +to *true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_01_SaveEdgeCol} + db._create("vertex"); + db._createEdgeCollection("relation"); + v1 = db.vertex.insert({ name : "vertex 1" }); + v2 = db.vertex.insert({ name : "vertex 2" }); + e1 = db.relation.insert(v1, v2, { label : "knows" }); + db._document(e1); +~ db._drop("relation"); +~ db._drop("vertex"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_Cluster_Kickstarter_Constructor.md b/Documentation/DocuBlocks/JSF_Cluster_Kickstarter_Constructor.md index 26d7b05ee8..64c8c0c9d5 100644 --- a/Documentation/DocuBlocks/JSF_Cluster_Kickstarter_Constructor.md +++ b/Documentation/DocuBlocks/JSF_Cluster_Kickstarter_Constructor.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Cluster_Kickstarter_Constructor -/// -/// `new require("@arangodb/cluster").Kickstarter(plan)` -/// -/// This constructor constructs a kickstarter object. Its first -/// argument is a cluster plan as for example provided by the planner -/// (see Cluster Planner Constructor and the general -/// explanations before this reference). The second argument is -/// optional and is taken to be "me" if omitted, it is the ID of the -/// dispatcher this object should consider itself to be. If the plan -/// contains startup commands for the dispatcher with this ID, these -/// commands are executed immediately. Otherwise they are handed over -/// to another responsible dispatcher via a REST call. -/// -/// The resulting object of this constructors allows to launch, -/// shutdown, relaunch the cluster described in the plan. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`new require("@arangodb/cluster").Kickstarter(plan)` + +This constructor constructs a kickstarter object. Its first +argument is a cluster plan as for example provided by the planner +(see Cluster Planner Constructor and the general +explanations before this reference). The second argument is +optional and is taken to be "me" if omitted, it is the ID of the +dispatcher this object should consider itself to be. If the plan +contains startup commands for the dispatcher with this ID, these +commands are executed immediately. Otherwise they are handed over +to another responsible dispatcher via a REST call. + +The resulting object of this constructors allows to launch, +shutdown, relaunch the cluster described in the plan. + diff --git a/Documentation/DocuBlocks/JSF_Cluster_Planner_Constructor.md b/Documentation/DocuBlocks/JSF_Cluster_Planner_Constructor.md index 3cbc668c0a..d65d96fedd 100644 --- a/Documentation/DocuBlocks/JSF_Cluster_Planner_Constructor.md +++ b/Documentation/DocuBlocks/JSF_Cluster_Planner_Constructor.md @@ -1,162 +1,161 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Cluster_Planner_Constructor -/// -/// *new require("@arangodb/cluster").Planner(userConfig)* -/// -/// This constructor builds a cluster planner object. The one and only -/// argument is an object that can have the properties described below. -/// The planner can plan clusters on a single machine (basically for -/// testing purposes) and on multiple machines. The resulting "cluster plans" -/// can be used by the kickstarter to start up the processes comprising -/// the cluster, including the agency. To this end, there has to be one -/// dispatcher on every machine participating in the cluster. A dispatcher -/// is a simple instance of ArangoDB, compiled with the cluster extensions, -/// but not running in cluster mode. This is why the configuration option -/// *dispatchers* below is of central importance. -/// -/// - *dispatchers*: an object with a property for each dispatcher, -/// the property name is the ID of the dispatcher and the value -/// should be an object with at least the property *endpoint* -/// containing the endpoint of the corresponding dispatcher. -/// Further optional properties are: -/// -/// - *avoidPorts* which is an object -/// in which all port numbers that should not be used are bound to -/// *true*, default is empty, that is, all ports can be used -/// - *arangodExtraArgs*, which is a list of additional -/// command line arguments that will be given to DBservers and -/// coordinators started by this dispatcher, the default is -/// an empty list. These arguments will be appended to those -/// produced automatically, such that one can overwrite -/// things with this. -/// - *allowCoordinators*, which is a boolean value indicating -/// whether or not coordinators should be started on this -/// dispatcher, the default is *true* -/// - *allowDBservers*, which is a boolean value indicating -/// whether or not DBservers should be started on this dispatcher, -/// the default is *true* -/// - *allowAgents*, which is a boolean value indicating whether or -/// not agents should be started on this dispatcher, the default is -/// *true* -/// - *username*, which is a string that contains the user name -/// for authentication with this dispatcher -/// - *passwd*, which is a string that contains the password -/// for authentication with this dispatcher, if not both -/// *username* and *passwd* are set, then no authentication -/// is used between dispatchers. Note that this will not work -/// if the dispatchers are configured with authentication. -/// -/// If *.dispatchers* is empty (no property), then an entry for the -/// local arangod itself is automatically added. Note that if the -/// only configured dispatcher has endpoint *tcp://localhost:*, -/// all processes are started in a special "local" mode and are -/// configured to bind their endpoints only to the localhost device. -/// In all other cases both agents and *arangod* instances bind -/// their endpoints to all available network devices. -/// - *numberOfAgents*: the number of agents in the agency, -/// usually there is no reason to deviate from the default of 3. The -/// planner distributes them amongst the dispatchers, if possible. -/// - *agencyPrefix*: a string that is used as prefix for all keys of -/// configuration data stored in the agency. -/// - *numberOfDBservers*: the number of DBservers in the -/// cluster. The planner distributes them evenly amongst the dispatchers. -/// - *startSecondaries*: a boolean flag indicating whether or not -/// secondary servers are started. In this version, this flag is -/// silently ignored, since we do not yet have secondary servers. -/// - *numberOfCoordinators*: the number of coordinators in the cluster, -/// the planner distributes them evenly amongst the dispatchers. -/// - *DBserverIDs*: a list of DBserver IDs (strings). If the planner -/// runs out of IDs it creates its own ones using *DBserver* -/// concatenated with a unique number. -/// - *coordinatorIDs*: a list of coordinator IDs (strings). If the planner -/// runs out of IDs it creates its own ones using *Coordinator* -/// concatenated with a unique number. -/// - *dataPath*: this is a string and describes the path under which -/// the agents, the DBservers and the coordinators store their -/// data directories. This can either be an absolute path (in which -/// case all machines in the clusters must use the same path), or -/// it can be a relative path. In the latter case it is relative -/// to the directory that is configured in the dispatcher with the -/// *cluster.data-path* option (command line or configuration file). -/// The directories created will be called *data-PREFIX-ID* where -/// *PREFIX* is replaced with the agency prefix (see above) and *ID* -/// is the ID of the DBserver or coordinator. -/// - *logPath*: this is a string and describes the path under which -/// the DBservers and the coordinators store their log file. This can -/// either be an absolute path (in which case all machines in the cluster -/// must use the same path), or it can be a relative path. In the -/// latter case it is relative to the directory that is configured -/// in the dispatcher with the *cluster.log-path* option. -/// - *arangodPath*: this is a string and describes the path to the -/// actual executable *arangod* that will be started for the -/// DBservers and coordinators. If this is an absolute path, it -/// obviously has to be the same on all machines in the cluster -/// as described for *dataPath*. If it is an empty string, the -/// dispatcher uses the executable that is configured with the -/// *cluster.arangod-path* option, which is by default the same -/// executable as the dispatcher uses. -/// - *agentPath*: this is a string and describes the path to the -/// actual executable that will be started for the agents in the -/// agency. If this is an absolute path, it obviously has to be -/// the same on all machines in the cluster, as described for -/// *arangodPath*. If it is an empty string, the dispatcher -/// uses its *cluster.agent-path* option. -/// - *agentExtPorts*: a list of port numbers to use for the external -/// ports of the agents. When running out of numbers in this list, -/// the planner increments the last one used by one for every port -/// needed. Note that the planner checks availability of the ports -/// during the planning phase by contacting the dispatchers on the -/// different machines, and uses only ports that are free during -/// the planning phase. Obviously, if those ports are connected -/// before the actual startup, things can go wrong. -/// - *agentIntPorts*: a list of port numbers to use for the internal -/// ports of the agents. The same comments as for *agentExtPorts* -/// apply. -/// - *DBserverPorts*: a list of port numbers to use for the -/// DBservers. The same comments as for *agentExtPorts* apply. -/// - *coordinatorPorts*: a list of port numbers to use for the -/// coordinators. The same comments as for *agentExtPorts* apply. -/// - *useSSLonDBservers*: a boolean flag indicating whether or not -/// we use SSL on all DBservers in the cluster -/// - *useSSLonCoordinators*: a boolean flag indicating whether or not -/// we use SSL on all coordinators in the cluster -/// - *valgrind*: a string to contain the path of the valgrind binary -/// if we should run the cluster components in it -/// - *valgrindopts*: commandline options to the valgrind process -/// - *valgrindXmlFileBase*: pattern for logfiles -/// - *valgrindTestname*: name of test to add to the logfiles -/// - *valgrindHosts*: which host classes should run in valgrind? -/// Coordinator / DBServer -/// - *extremeVerbosity* : if set to true, then there will be more test -/// run output, especially for cluster tests. -/// -/// All these values have default values. Here is the current set of -/// default values: -/// -/// ```js -/// { -/// "agencyPrefix" : "arango", -/// "numberOfAgents" : 1, -/// "numberOfDBservers" : 2, -/// "startSecondaries" : false, -/// "numberOfCoordinators" : 1, -/// "DBserverIDs" : ["Pavel", "Perry", "Pancho", "Paul", "Pierre", -/// "Pit", "Pia", "Pablo" ], -/// "coordinatorIDs" : ["Claus", "Chantalle", "Claire", "Claudia", -/// "Claas", "Clemens", "Chris" ], -/// "dataPath" : "", // means configured in dispatcher -/// "logPath" : "", // means configured in dispatcher -/// "arangodPath" : "", // means configured as dispatcher -/// "agentPath" : "", // means configured in dispatcher -/// "agentExtPorts" : [4001], -/// "agentIntPorts" : [7001], -/// "DBserverPorts" : [8629], -/// "coordinatorPorts" : [8530], -/// "dispatchers" : {"me": {"endpoint": "tcp://localhost:"}}, -/// // this means only we as a local instance -/// "useSSLonDBservers" : false, -/// "useSSLonCoordinators" : false -/// }; -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +*new require("@arangodb/cluster").Planner(userConfig)* + +This constructor builds a cluster planner object. The one and only +argument is an object that can have the properties described below. +The planner can plan clusters on a single machine (basically for +testing purposes) and on multiple machines. The resulting "cluster plans" +can be used by the kickstarter to start up the processes comprising +the cluster, including the agency. To this end, there has to be one +dispatcher on every machine participating in the cluster. A dispatcher +is a simple instance of ArangoDB, compiled with the cluster extensions, +but not running in cluster mode. This is why the configuration option +*dispatchers* below is of central importance. + + - *dispatchers*: an object with a property for each dispatcher, + the property name is the ID of the dispatcher and the value + should be an object with at least the property *endpoint* + containing the endpoint of the corresponding dispatcher. + Further optional properties are: + + - *avoidPorts* which is an object + in which all port numbers that should not be used are bound to + *true*, default is empty, that is, all ports can be used + - *arangodExtraArgs*, which is a list of additional + command line arguments that will be given to DBservers and + coordinators started by this dispatcher, the default is + an empty list. These arguments will be appended to those + produced automatically, such that one can overwrite + things with this. + - *allowCoordinators*, which is a boolean value indicating + whether or not coordinators should be started on this + dispatcher, the default is *true* + - *allowDBservers*, which is a boolean value indicating + whether or not DBservers should be started on this dispatcher, + the default is *true* + - *allowAgents*, which is a boolean value indicating whether or + not agents should be started on this dispatcher, the default is + *true* + - *username*, which is a string that contains the user name + for authentication with this dispatcher + - *passwd*, which is a string that contains the password + for authentication with this dispatcher, if not both + *username* and *passwd* are set, then no authentication + is used between dispatchers. Note that this will not work + if the dispatchers are configured with authentication. + + If *.dispatchers* is empty (no property), then an entry for the + local arangod itself is automatically added. Note that if the + only configured dispatcher has endpoint *tcp://localhost:*, + all processes are started in a special "local" mode and are + configured to bind their endpoints only to the localhost device. + In all other cases both agents and *arangod* instances bind + their endpoints to all available network devices. + - *numberOfAgents*: the number of agents in the agency, + usually there is no reason to deviate from the default of 3. The + planner distributes them amongst the dispatchers, if possible. + - *agencyPrefix*: a string that is used as prefix for all keys of + configuration data stored in the agency. + - *numberOfDBservers*: the number of DBservers in the + cluster. The planner distributes them evenly amongst the dispatchers. + - *startSecondaries*: a boolean flag indicating whether or not + secondary servers are started. In this version, this flag is + silently ignored, since we do not yet have secondary servers. + - *numberOfCoordinators*: the number of coordinators in the cluster, + the planner distributes them evenly amongst the dispatchers. + - *DBserverIDs*: a list of DBserver IDs (strings). If the planner + runs out of IDs it creates its own ones using *DBserver* + concatenated with a unique number. + - *coordinatorIDs*: a list of coordinator IDs (strings). If the planner + runs out of IDs it creates its own ones using *Coordinator* + concatenated with a unique number. + - *dataPath*: this is a string and describes the path under which + the agents, the DBservers and the coordinators store their + data directories. This can either be an absolute path (in which + case all machines in the clusters must use the same path), or + it can be a relative path. In the latter case it is relative + to the directory that is configured in the dispatcher with the + *cluster.data-path* option (command line or configuration file). + The directories created will be called *data-PREFIX-ID* where + *PREFIX* is replaced with the agency prefix (see above) and *ID* + is the ID of the DBserver or coordinator. + - *logPath*: this is a string and describes the path under which + the DBservers and the coordinators store their log file. This can + either be an absolute path (in which case all machines in the cluster + must use the same path), or it can be a relative path. In the + latter case it is relative to the directory that is configured + in the dispatcher with the *cluster.log-path* option. + - *arangodPath*: this is a string and describes the path to the + actual executable *arangod* that will be started for the + DBservers and coordinators. If this is an absolute path, it + obviously has to be the same on all machines in the cluster + as described for *dataPath*. If it is an empty string, the + dispatcher uses the executable that is configured with the + *cluster.arangod-path* option, which is by default the same + executable as the dispatcher uses. + - *agentPath*: this is a string and describes the path to the + actual executable that will be started for the agents in the + agency. If this is an absolute path, it obviously has to be + the same on all machines in the cluster, as described for + *arangodPath*. If it is an empty string, the dispatcher + uses its *cluster.agent-path* option. + - *agentExtPorts*: a list of port numbers to use for the external + ports of the agents. When running out of numbers in this list, + the planner increments the last one used by one for every port + needed. Note that the planner checks availability of the ports + during the planning phase by contacting the dispatchers on the + different machines, and uses only ports that are free during + the planning phase. Obviously, if those ports are connected + before the actual startup, things can go wrong. + - *agentIntPorts*: a list of port numbers to use for the internal + ports of the agents. The same comments as for *agentExtPorts* + apply. + - *DBserverPorts*: a list of port numbers to use for the + DBservers. The same comments as for *agentExtPorts* apply. + - *coordinatorPorts*: a list of port numbers to use for the + coordinators. The same comments as for *agentExtPorts* apply. + - *useSSLonDBservers*: a boolean flag indicating whether or not + we use SSL on all DBservers in the cluster + - *useSSLonCoordinators*: a boolean flag indicating whether or not + we use SSL on all coordinators in the cluster + - *valgrind*: a string to contain the path of the valgrind binary + if we should run the cluster components in it + - *valgrindopts*: commandline options to the valgrind process + - *valgrindXmlFileBase*: pattern for logfiles + - *valgrindTestname*: name of test to add to the logfiles + - *valgrindHosts*: which host classes should run in valgrind? + Coordinator / DBServer + - *extremeVerbosity* : if set to true, then there will be more test + run output, especially for cluster tests. + +All these values have default values. Here is the current set of +default values: + +```js +{ + "agencyPrefix" : "arango", + "numberOfAgents" : 1, + "numberOfDBservers" : 2, + "startSecondaries" : false, + "numberOfCoordinators" : 1, + "DBserverIDs" : ["Pavel", "Perry", "Pancho", "Paul", "Pierre", + "Pit", "Pia", "Pablo" ], + "coordinatorIDs" : ["Claus", "Chantalle", "Claire", "Claudia", + "Claas", "Clemens", "Chris" ], + "dataPath" : "", // means configured in dispatcher + "logPath" : "", // means configured in dispatcher + "arangodPath" : "", // means configured as dispatcher + "agentPath" : "", // means configured in dispatcher + "agentExtPorts" : [4001], + "agentIntPorts" : [7001], + "DBserverPorts" : [8629], + "coordinatorPorts" : [8530], + "dispatchers" : {"me": {"endpoint": "tcp://localhost:"}}, + // this means only we as a local instance + "useSSLonDBservers" : false, + "useSSLonCoordinators" : false +}; +``` + diff --git a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_cleanup.md b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_cleanup.md index aadce07de8..d51b3ccb95 100644 --- a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_cleanup.md +++ b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_cleanup.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Kickstarter_prototype_cleanup -/// -/// `Kickstarter.cleanup()` -/// -/// This cleans up all the data and logs of a previously shut down cluster. -/// To this end, other dispatchers are contacted as necessary. -/// [Use shutdown](../ModulePlanner/README.md#shutdown) first and -/// use with caution, since potentially a lot of data is being erased with -/// this call! -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Kickstarter.cleanup()` + +This cleans up all the data and logs of a previously shut down cluster. +To this end, other dispatchers are contacted as necessary. +[Use shutdown](../ModulePlanner/README.md#shutdown) first and +use with caution, since potentially a lot of data is being erased with +this call! + diff --git a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_isHealthy.md b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_isHealthy.md index 5b6cc30c9f..eb4944d794 100644 --- a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_isHealthy.md +++ b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_isHealthy.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Kickstarter_prototype_isHealthy -/// -/// `Kickstarter.isHealthy()` -/// -/// This checks that all processes belonging to a running cluster are -/// healthy. To this end, other dispatchers are contacted as necessary. -/// At this stage it is only checked that the processes are still up and -/// running. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Kickstarter.isHealthy()` + +This checks that all processes belonging to a running cluster are +healthy. To this end, other dispatchers are contacted as necessary. +At this stage it is only checked that the processes are still up and +running. + diff --git a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_launch.md b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_launch.md index 114188e0be..a46b9efeef 100644 --- a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_launch.md +++ b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_launch.md @@ -1,25 +1,24 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Kickstarter_prototype_launch -/// -/// `Kickstarter.launch()` -/// -/// This starts up a cluster as described in the plan which was given to -/// the constructor. To this end, other dispatchers are contacted as -/// necessary. All startup commands for the local dispatcher are -/// executed immediately. -/// -/// The result is an object that contains information about the started -/// processes, this object is also stored in the Kickstarter object -/// itself. We do not go into details here about the data structure, -/// but the most important information are the process IDs of the -/// started processes. The corresponding -/// [see shutdown method](../ModulePlanner/README.md#shutdown) needs this -/// information to shut down all processes. -/// -/// Note that all data in the DBservers and all log files and all agency -/// information in the cluster is deleted by this call. This is because -/// it is intended to set up a cluster for the first time. See -/// the [relaunch method](../ModulePlanner/README.md#relaunch) -/// for restarting a cluster without data loss. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Kickstarter.launch()` + +This starts up a cluster as described in the plan which was given to +the constructor. To this end, other dispatchers are contacted as +necessary. All startup commands for the local dispatcher are +executed immediately. + +The result is an object that contains information about the started +processes, this object is also stored in the Kickstarter object +itself. We do not go into details here about the data structure, +but the most important information are the process IDs of the +started processes. The corresponding +[see shutdown method](../ModulePlanner/README.md#shutdown) needs this +information to shut down all processes. + +Note that all data in the DBservers and all log files and all agency +information in the cluster is deleted by this call. This is because +it is intended to set up a cluster for the first time. See +the [relaunch method](../ModulePlanner/README.md#relaunch) +for restarting a cluster without data loss. + diff --git a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_relaunch.md b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_relaunch.md index 7c9aae6dd7..13f00444bb 100644 --- a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_relaunch.md +++ b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_relaunch.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Kickstarter_prototype_relaunch -/// -/// `Kickstarter.relaunch()` -/// -/// This starts up a cluster as described in the plan which was given to -/// the constructor. To this end, other dispatchers are contacted as -/// necessary. All startup commands for the local dispatcher are -/// executed immediately. -/// -/// The result is an object that contains information about the started -/// processes, this object is also stored in the Kickstarter object -/// itself. We do not go into details here about the data structure, -/// but the most important information are the process IDs of the -/// started processes. The corresponding -/// [shutdown method ](../ModulePlanner/README.md#shutdown) needs this information to -/// shut down all processes. -/// -/// Note that this methods needs that all data in the DBservers and the -/// agency information in the cluster are already set up properly. See -/// the [launch method](../ModulePlanner/README.md#launch) for -/// starting a cluster for the first time. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Kickstarter.relaunch()` + +This starts up a cluster as described in the plan which was given to +the constructor. To this end, other dispatchers are contacted as +necessary. All startup commands for the local dispatcher are +executed immediately. + +The result is an object that contains information about the started +processes, this object is also stored in the Kickstarter object +itself. We do not go into details here about the data structure, +but the most important information are the process IDs of the +started processes. The corresponding +[shutdown method ](../ModulePlanner/README.md#shutdown) needs this information to +shut down all processes. + +Note that this methods needs that all data in the DBservers and the +agency information in the cluster are already set up properly. See +the [launch method](../ModulePlanner/README.md#launch) for +starting a cluster for the first time. + diff --git a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_shutdown.md b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_shutdown.md index 088b32c966..8cb340fd28 100644 --- a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_shutdown.md +++ b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_shutdown.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Kickstarter_prototype_shutdown -/// -/// `Kickstarter.shutdown()` -/// -/// This shuts down a cluster as described in the plan which was given to -/// the constructor. To this end, other dispatchers are contacted as -/// necessary. All processes in the cluster are gracefully shut down -/// in the right order. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Kickstarter.shutdown()` + +This shuts down a cluster as described in the plan which was given to +the constructor. To this end, other dispatchers are contacted as +necessary. All processes in the cluster are gracefully shut down +in the right order. + diff --git a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_upgrade.md b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_upgrade.md index f8dcc29a2b..35d80cc3dd 100644 --- a/Documentation/DocuBlocks/JSF_Kickstarter_prototype_upgrade.md +++ b/Documentation/DocuBlocks/JSF_Kickstarter_prototype_upgrade.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Kickstarter_prototype_upgrade -/// -/// `Kickstarter.upgrade(username, passwd)` -/// -/// This performs an upgrade procedure on a cluster as described in -/// the plan which was given to the constructor. To this end, other -/// dispatchers are contacted as necessary. All commands for the local -/// dispatcher are executed immediately. The basic approach for the -/// upgrade is as follows: The agency is started first (exactly as -/// in relaunch), no configuration is sent there (exactly as in the -/// relaunch action), all servers are first started with the option -/// "--upgrade" and then normally. In the end, the upgrade-database.js -/// script is run on one of the coordinators, as in the launch action. -/// -/// The result is an object that contains information about the started -/// processes, this object is also stored in the Kickstarter object -/// itself. We do not go into details here about the data structure, -/// but the most important information are the process IDs of the -/// started processes. The corresponding -/// [shutdown method](../ModulePlanner/README.md#shutdown) needs -/// this information to shut down all processes. -/// -/// Note that this methods needs that all data in the DBservers and the -/// agency information in the cluster are already set up properly. See -/// the [launch method](../ModulePlanner/README.md#launch) for -/// starting a cluster for the first time. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Kickstarter.upgrade(username, passwd)` + +This performs an upgrade procedure on a cluster as described in +the plan which was given to the constructor. To this end, other +dispatchers are contacted as necessary. All commands for the local +dispatcher are executed immediately. The basic approach for the +upgrade is as follows: The agency is started first (exactly as +in relaunch), no configuration is sent there (exactly as in the +relaunch action), all servers are first started with the option +"--upgrade" and then normally. In the end, the upgrade-database.js +script is run on one of the coordinators, as in the launch action. + +The result is an object that contains information about the started +processes, this object is also stored in the Kickstarter object +itself. We do not go into details here about the data structure, +but the most important information are the process IDs of the +started processes. The corresponding +[shutdown method](../ModulePlanner/README.md#shutdown) needs +this information to shut down all processes. + +Note that this methods needs that all data in the DBservers and the +agency information in the cluster are already set up properly. See +the [launch method](../ModulePlanner/README.md#launch) for +starting a cluster for the first time. + diff --git a/Documentation/DocuBlocks/JSF_Planner_prototype_getPlan.md b/Documentation/DocuBlocks/JSF_Planner_prototype_getPlan.md index 7f71b26c38..11396a537c 100644 --- a/Documentation/DocuBlocks/JSF_Planner_prototype_getPlan.md +++ b/Documentation/DocuBlocks/JSF_Planner_prototype_getPlan.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_Planner_prototype_getPlan -/// -/// `Planner.getPlan()` -/// -/// returns the cluster plan as a JavaScript object. The result of this -/// method can be given to the constructor of a Kickstarter. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Planner.getPlan()` + +returns the cluster plan as a JavaScript object. The result of this +method can be given to the constructor of a Kickstarter. + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_betweenness.md b/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_betweenness.md index 3a9d9b0d42..3d07c1af68 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_betweenness.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_betweenness.md @@ -1,61 +1,60 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_absolute_betweenness -/// -/// `GRAPH_ABSOLUTE_BETWEENNESS (graphName, options)` -/// -/// The GRAPH\_ABSOLUTE\_BETWEENNESS function returns the -/// [betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) -/// of all vertices in the graph. -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// -/// * *graphName* : The name of the graph as a string. -/// * *options* : An object containing the following options: -/// * *direction* : The direction of the edges. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *weight* : The name of the attribute of -/// the edges containing the length. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the betweenness can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the absolute betweenness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS('routeplanner', {})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute betweenness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS(" -/// +"'routeplanner', {weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute closeness regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS(" -/// | + "'routeplanner', {direction : 'outbound', weight : 'distance'})" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_ABSOLUTE_BETWEENNESS (graphName, options)` + +The GRAPH\_ABSOLUTE\_BETWEENNESS function returns the +[betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) +of all vertices in the graph. + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + + +* *graphName* : The name of the graph as a string. +* *options* : An object containing the following options: + * *direction* : The direction of the edges. +Possible values are *outbound*, *inbound* and *any* (default). + * *weight* : The name of the attribute of +the edges containing the length. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the betweenness can not be calculated. + +@EXAMPLES + +A route planner example, the absolute betweenness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS('routeplanner', {})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute betweenness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS(" + +"'routeplanner', {weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute closeness regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsBetweenness3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ABSOLUTE_BETWEENNESS(" +| + "'routeplanner', {direction : 'outbound', weight : 'distance'})" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_closeness.md b/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_closeness.md index 60c53e9253..225fb1b2dc 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_closeness.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_closeness.md @@ -1,79 +1,78 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_absolute_closeness -/// -/// `GRAPH_ABSOLUTE_CLOSENESS (graphName, vertexExample, options)` -/// -/// The GRAPH\_ABSOLUTE\_CLOSENESS function returns the -/// [closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality) -/// of the vertices defined by the examples. -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *vertexExample* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *options* : An object containing the following options: -/// * *direction* : The direction of the edges. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeCollectionRestriction* : One or multiple edge -/// collection names. Only edges from these collections will be considered for the path. -/// * *startVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// start vertex of a path. -/// * *endVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// end vertex of a path. -/// * *edgeExamples* : A filter example for the -/// edges in the shortest paths ( -/// see [example](#short-explanation-of-the-example-parameter)). -/// * *algorithm* : The algorithm to calculate -/// the shortest paths. Possible values are -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default) -/// and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight* : The name of the attribute of -/// the edges containing the length. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the absolute closeness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS('routeplanner', {})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute closeness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS(" -/// +"'routeplanner', {}, {weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute closeness of all German cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS(" -/// | + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " + -/// "direction : 'outbound', weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_ABSOLUTE_CLOSENESS (graphName, vertexExample, options)` + +The GRAPH\_ABSOLUTE\_CLOSENESS function returns the +[closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality) +of the vertices defined by the examples. + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *vertexExample* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *options* : An object containing the following options: + * *direction* : The direction of the edges. +Possible values are *outbound*, *inbound* and *any* (default). + * *edgeCollectionRestriction* : One or multiple edge + collection names. Only edges from these collections will be considered for the path. + * *startVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + start vertex of a path. + * *endVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + end vertex of a path. + * *edgeExamples* : A filter example for the +edges in the shortest paths ( +see [example](#short-explanation-of-the-example-parameter)). + * *algorithm* : The algorithm to calculate +the shortest paths. Possible values are +[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default) + and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight* : The name of the attribute of +the edges containing the length. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the absolute closeness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS('routeplanner', {})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute closeness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS(" + +"'routeplanner', {}, {weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute closeness of all German cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsCloseness3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ABSOLUTE_CLOSENESS(" +| + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " + + "direction : 'outbound', weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_eccentricity.md b/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_eccentricity.md index 481123b257..3a58f70924 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_eccentricity.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_absolute_eccentricity.md @@ -1,79 +1,78 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_absolute_eccentricity -/// -/// `GRAPH_ABSOLUTE_ECCENTRICITY (graphName, vertexExample, options)` -/// -/// The GRAPH\_ABSOLUTE\_ECCENTRICITY function returns the -/// [eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) -/// of the vertices defined by the examples. -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *vertexExample* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *options* (optional) : An object containing the following options: -/// * *direction* : The direction of the edges as a string. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeCollectionRestriction* : One or multiple edge -/// collection names. Only edges from these collections will be considered for the path. -/// * *startVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// start vertex of a path. -/// * *endVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// end vertex of a path. -/// * *edgeExamples* : A filter example for the edges in the -/// shortest paths (see [example](#short-explanation-of-the-example-parameter)). -/// * *algorithm* : The algorithm to calculate -/// the shortest paths as a string. If vertex example is empty -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is -/// used as default, otherwise the default is -/// [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm) -/// * *weight* : The name of the attribute of -/// the edges containing the length as a string. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the absolute eccentricity of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY('routeplanner', {})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute eccentricity of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY(" -/// +"'routeplanner', {}, {weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute eccentricity of all German cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY(" -/// | + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " + -/// "direction : 'outbound', weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_ABSOLUTE_ECCENTRICITY (graphName, vertexExample, options)` + + The GRAPH\_ABSOLUTE\_ECCENTRICITY function returns the +[eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) +of the vertices defined by the examples. + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *vertexExample* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *options* (optional) : An object containing the following options: + * *direction* : The direction of the edges as a string. +Possible values are *outbound*, *inbound* and *any* (default). + * *edgeCollectionRestriction* : One or multiple edge + collection names. Only edges from these collections will be considered for the path. + * *startVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + start vertex of a path. + * *endVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + end vertex of a path. + * *edgeExamples* : A filter example for the edges in the + shortest paths (see [example](#short-explanation-of-the-example-parameter)). + * *algorithm* : The algorithm to calculate + the shortest paths as a string. If vertex example is empty + [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is + used as default, otherwise the default is + [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm) + * *weight* : The name of the attribute of +the edges containing the length as a string. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the absolute eccentricity of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY('routeplanner', {})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute eccentricity of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY(" + +"'routeplanner', {}, {weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute eccentricity of all German cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphAbsEccentricity3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY(" +| + "'routeplanner', {}, {startVertexCollectionRestriction : 'germanCity', " + + "direction : 'outbound', weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_betweenness.md b/Documentation/DocuBlocks/JSF_aql_general_graph_betweenness.md index aa80e556b8..472329ad36 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_betweenness.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_betweenness.md @@ -1,60 +1,59 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_betweenness -/// -/// `GRAPH_BETWEENNESS (graphName, options)` -/// -/// The GRAPH\_BETWEENNESS function returns the -/// [betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) -/// of graphs vertices. -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *options* : An object containing the following options: -/// * *direction* : The direction of the edges. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *weight* : The name of the attribute of -/// the edges containing the length. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the betweenness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_BETWEENNESS('routeplanner')").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the betweenness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_BETWEENNESS('routeplanner', {weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the betweenness regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_BETWEENNESS(" -/// + "'routeplanner', {direction : 'outbound', weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_BETWEENNESS (graphName, options)` + +The GRAPH\_BETWEENNESS function returns the +[betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) +of graphs vertices. + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *options* : An object containing the following options: + * *direction* : The direction of the edges. +Possible values are *outbound*, *inbound* and *any* (default). + * *weight* : The name of the attribute of +the edges containing the length. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the betweenness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_BETWEENNESS('routeplanner')").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the betweenness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_BETWEENNESS('routeplanner', {weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the betweenness regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphBetweenness3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_BETWEENNESS(" + + "'routeplanner', {direction : 'outbound', weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_closeness.md b/Documentation/DocuBlocks/JSF_aql_general_graph_closeness.md index 22426a2ae0..eabcf0f9a5 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_closeness.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_closeness.md @@ -1,66 +1,65 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_closeness -/// -/// `GRAPH_CLOSENESS (graphName, options)` -/// -/// The GRAPH\_CLOSENESS function returns the normalized -/// [closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality) -/// of graphs vertices. -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *options* : An object containing the following options: -/// * *direction* : The direction of the edges. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *algorithm* : The algorithm to calculate -/// the shortest paths. Possible values are -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default) -/// and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight* : The name of the attribute of -/// the edges containing the length. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the closeness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_CLOSENESS('routeplanner')").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the closeness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_CLOSENESS(" -/// +"'routeplanner', {weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute closeness of all cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_CLOSENESS(" -/// | + "'routeplanner',{direction : 'outbound', weight : 'distance'})" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_CLOSENESS (graphName, options)` + +The GRAPH\_CLOSENESS function returns the normalized +[closeness](http://en.wikipedia.org/wiki/Centrality#Closeness-centrality) +of graphs vertices. + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *options* : An object containing the following options: + * *direction* : The direction of the edges. +Possible values are *outbound*, *inbound* and *any* (default). + * *algorithm* : The algorithm to calculate +the shortest paths. Possible values are +[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) (default) + and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight* : The name of the attribute of +the edges containing the length. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the closeness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_CLOSENESS('routeplanner')").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the closeness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_CLOSENESS(" + +"'routeplanner', {weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute closeness of all cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCloseness3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_CLOSENESS(" +| + "'routeplanner',{direction : 'outbound', weight : 'distance'})" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_common_neighbors.md b/Documentation/DocuBlocks/JSF_aql_general_graph_common_neighbors.md index f8cd8d1992..6e7605db7b 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_common_neighbors.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_common_neighbors.md @@ -1,46 +1,45 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_common_neighbors -/// The GRAPH\_COMMON\_NEIGHBORS function returns all common neighbors of the vertices -/// defined by the examples. -/// -/// `GRAPH_COMMON_NEIGHBORS (graphName, vertex1Example, vertex2Examples, -/// optionsVertex1, optionsVertex2)` -/// -/// This function returns the intersection of *GRAPH_NEIGHBORS(vertex1Example, optionsVertex1)* -/// and *GRAPH_NEIGHBORS(vertex2Example, optionsVertex2)*. -/// The complexity of this method is **O(n\*m^x)** with *n* being the maximal amount of vertices -/// defined by the parameters vertexExamples, *m* the average amount of neighbors and *x* the -/// maximal depths. -/// Hence the default call would have a complexity of **O(n\*m)**; -/// -/// For parameter documentation read the documentation of -/// [GRAPH_NEIGHBORS](#graphneighbors). -/// -/// @EXAMPLES -/// -/// A route planner example, all common neighbors of capitals. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_COMMON_NEIGHBORS(" -/// | +"'routeplanner', {isCapital : true}, {isCapital : true}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all common outbound neighbors of Hamburg with any other location -/// which have a maximal depth of 2: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_COMMON_NEIGHBORS(" -/// | +"'routeplanner', 'germanCity/Hamburg', {}, {direction : 'outbound', maxDepth : 2}, "+ -/// | "{direction : 'outbound', maxDepth : 2}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_COMMON\_NEIGHBORS function returns all common neighbors of the vertices +defined by the examples. + +`GRAPH_COMMON_NEIGHBORS (graphName, vertex1Example, vertex2Examples, +optionsVertex1, optionsVertex2)` + +This function returns the intersection of *GRAPH_NEIGHBORS(vertex1Example, optionsVertex1)* +and *GRAPH_NEIGHBORS(vertex2Example, optionsVertex2)*. +The complexity of this method is **O(n\*m^x)** with *n* being the maximal amount of vertices +defined by the parameters vertexExamples, *m* the average amount of neighbors and *x* the +maximal depths. +Hence the default call would have a complexity of **O(n\*m)**; + +For parameter documentation read the documentation of +[GRAPH_NEIGHBORS](#graphneighbors). + +@EXAMPLES + +A route planner example, all common neighbors of capitals. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_COMMON_NEIGHBORS(" +| +"'routeplanner', {isCapital : true}, {isCapital : true}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all common outbound neighbors of Hamburg with any other location +which have a maximal depth of 2: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCommonNeighbors2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_COMMON_NEIGHBORS(" +| +"'routeplanner', 'germanCity/Hamburg', {}, {direction : 'outbound', maxDepth : 2}, "+ +| "{direction : 'outbound', maxDepth : 2}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_common_properties.md b/Documentation/DocuBlocks/JSF_aql_general_graph_common_properties.md index 55c509dda2..04f4e6a134 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_common_properties.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_common_properties.md @@ -1,54 +1,53 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_common_properties -/// -/// `GRAPH_COMMON_PROPERTIES (graphName, vertex1Example, vertex2Examples, options)` -/// -/// The GRAPH\_COMMON\_PROPERTIES function returns a list of objects which have the id of -/// the vertices defined by *vertex1Example* as keys and a list of vertices defined by -/// *vertex21Example*, that share common properties as value. Notice that only the -/// vertex id and the matching attributes are returned in the result. -/// -/// The complexity of this method is **O(n)** with *n* being the maximal amount of vertices -/// defined by the parameters vertexExamples. -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *vertex1Example* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *vertex2Example* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *options* (optional) : An object containing the following options: -/// * *vertex1CollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered. -/// * *vertex2CollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered. -/// * *ignoreProperties* : One or multiple -/// attributes of a document that should be ignored, either a string or an array.. -/// -/// @EXAMPLES -/// -/// A route planner example, all locations with the same properties: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_COMMON_PROPERTIES(" -/// | +"'routeplanner', {}, {}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all cities which share same properties except for population. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_COMMON_PROPERTIES(" -/// | +"'routeplanner', {}, {}, {ignoreProperties: 'population'}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_COMMON_PROPERTIES (graphName, vertex1Example, vertex2Examples, options)` + +The GRAPH\_COMMON\_PROPERTIES function returns a list of objects which have the id of +the vertices defined by *vertex1Example* as keys and a list of vertices defined by +*vertex21Example*, that share common properties as value. Notice that only the +vertex id and the matching attributes are returned in the result. + +The complexity of this method is **O(n)** with *n* being the maximal amount of vertices +defined by the parameters vertexExamples. + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *vertex1Example* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *vertex2Example* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *options* (optional) : An object containing the following options: + * *vertex1CollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered. + * *vertex2CollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered. + * *ignoreProperties* : One or multiple + attributes of a document that should be ignored, either a string or an array.. + +@EXAMPLES + +A route planner example, all locations with the same properties: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_COMMON_PROPERTIES(" +| +"'routeplanner', {}, {}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all cities which share same properties except for population. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphProperties2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_COMMON_PROPERTIES(" +| +"'routeplanner', {}, {}, {ignoreProperties: 'population'}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_diameter.md b/Documentation/DocuBlocks/JSF_aql_general_graph_diameter.md index 2fab69b216..b6f791c328 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_diameter.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_diameter.md @@ -1,64 +1,63 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_diameter -/// -/// `GRAPH_DIAMETER (graphName, options)` -/// -/// The GRAPH\_DIAMETER function returns the -/// [diameter](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) -/// of a graph. -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *options* : An object containing the following options: -/// * *direction* : The direction of the edges. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible -/// values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) -/// (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight* : The name of the attribute of -/// the edges containing the length. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the diameter of the graph. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_DIAMETER('routeplanner')").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the diameter of the graph. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_DIAMETER('routeplanner', {weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the diameter of the graph regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_DIAMETER(" -/// | + "'routeplanner', {direction : 'outbound', weight : 'distance'})" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_DIAMETER (graphName, options)` + +The GRAPH\_DIAMETER function returns the +[diameter](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) +of a graph. + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *options* : An object containing the following options: + * *direction* : The direction of the edges. +Possible values are *outbound*, *inbound* and *any* (default). + * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible +values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) + (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight* : The name of the attribute of +the edges containing the length. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the diameter of the graph. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_DIAMETER('routeplanner')").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the diameter of the graph. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_DIAMETER('routeplanner', {weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the diameter of the graph regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDiameter3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_DIAMETER(" +| + "'routeplanner', {direction : 'outbound', weight : 'distance'})" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_distance.md b/Documentation/DocuBlocks/JSF_aql_general_graph_distance.md index f27985f971..a17cb37880 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_distance.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_distance.md @@ -1,40 +1,39 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_distance -/// The GRAPH\_DISTANCE\_TO function returns all paths and there distance within a graph. -/// -/// `GRAPH_DISTANCE_TO (graphName, startVertexExample, endVertexExample, options)` -/// -/// This function is a wrapper of [GRAPH\_SHORTEST\_PATH](#graphshortestpath). -/// It does not return the actual path but only the distance between two vertices. -/// -/// @EXAMPLES -/// -/// A route planner example, distance from all french to all german cities: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_DISTANCE_TO(" -/// | +"'routeplanner', {}, {}, { " + -/// | " weight : 'distance', endVertexCollectionRestriction : 'germanCity', " + -/// | "startVertexCollectionRestriction : 'frenchCity'}) RETURN [e.startVertex, e.vertex, " + -/// | "e.distance]" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, distance from Hamburg and Cologne to Lyon: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_DISTANCE_TO(" -/// | + "'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Hamburg'}], " + -/// | "'frenchCity/Lyon', " + -/// | "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance]" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_DISTANCE\_TO function returns all paths and there distance within a graph. + +`GRAPH_DISTANCE_TO (graphName, startVertexExample, endVertexExample, options)` + +This function is a wrapper of [GRAPH\_SHORTEST\_PATH](#graphshortestpath). +It does not return the actual path but only the distance between two vertices. + +@EXAMPLES + +A route planner example, distance from all french to all german cities: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_DISTANCE_TO(" +| +"'routeplanner', {}, {}, { " + +| " weight : 'distance', endVertexCollectionRestriction : 'germanCity', " + +| "startVertexCollectionRestriction : 'frenchCity'}) RETURN [e.startVertex, e.vertex, " + +| "e.distance]" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, distance from Hamburg and Cologne to Lyon: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDistanceTo2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_DISTANCE_TO(" +| + "'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Hamburg'}], " + +| "'frenchCity/Lyon', " + +| "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance]" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_eccentricity.md b/Documentation/DocuBlocks/JSF_aql_general_graph_eccentricity.md index 98b28c1369..79694fdd5b 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_eccentricity.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_eccentricity.md @@ -1,52 +1,51 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_eccentricity -/// -/// `GRAPH_ECCENTRICITY (graphName, options)` -/// -/// The GRAPH\_ECCENTRICITY function returns the normalized -/// [eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) -/// of the graphs vertices -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *options* (optional) : An object containing the following options: -/// * *direction* : The direction of the edges as a string. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible -/// values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) -/// (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight* : The name of the attribute of the edges containing the length as a string. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the eccentricity of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_ECCENTRICITY('routeplanner')").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the eccentricity of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ECCENTRICITY('routeplanner', {weight : 'distance'})" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_ECCENTRICITY (graphName, options)` + +The GRAPH\_ECCENTRICITY function returns the normalized +[eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) +of the graphs vertices + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *options* (optional) : An object containing the following options: + * *direction* : The direction of the edges as a string. +Possible values are *outbound*, *inbound* and *any* (default). + * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible +values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) + (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight* : The name of the attribute of the edges containing the length as a string. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the eccentricity of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_ECCENTRICITY('routeplanner')").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the eccentricity of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEccentricity2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ECCENTRICITY('routeplanner', {weight : 'distance'})" + ).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_edges.md b/Documentation/DocuBlocks/JSF_aql_general_graph_edges.md index 0aafa2afb9..c602fcdb42 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_edges.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_edges.md @@ -1,81 +1,80 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_edges -/// -/// `GRAPH_EDGES (graphName, vertexExample, options)` -/// -/// The GRAPH\_EDGES function returns all edges of the graph connected to the vertices -/// defined by the example. -/// -/// The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the -/// parameter vertexExamplex, *m* the average amount of edges of a vertex and *x* the maximal -/// depths. -/// Hence the default call would have a complexity of **O(n\*m)**; -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *vertexExample* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *options* (optional) : An object containing the following options: -/// * *direction* : The direction -/// of the edges as a string. Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeCollectionRestriction* : One or multiple edge -/// collection names. Only edges from these collections will be considered for the path. -/// * *startVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// start vertex of a path. -/// * *endVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// end vertex of a path. -/// * *edgeExamples* : A filter example -/// for the edges (see [example](#short-explanation-of-the-example-parameter)). -/// * *minDepth* : Defines the minimal length of a path from an edge -/// to a vertex (default is 1, which means only the edges directly connected to a vertex would -/// be returned). -/// * *maxDepth* : Defines the maximal length of a path from an edge -/// to a vertex (default is 1, which means only the edges directly connected to a vertex would -/// be returned). -/// * *maxIterations*: the maximum number of iterations that the traversal is -/// allowed to perform. It is sensible to set this number so unbounded traversals -/// will terminate. -/// * *includeData*: Defines if the result should contain only ids (false) or if all documents -/// should be fully extracted (true). By default this parameter is set to false, so only ids -/// will be returned. -/// -/// @EXAMPLES -/// -/// A route planner example, all edges to locations with a distance of either 700 or 600.: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_EDGES(" -/// | +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all outbound edges of Hamburg with a maximal depth of 2 : -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_EDGES(" -/// | +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Including the data: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_EDGES(" -/// | + "'routeplanner', 'germanCity/Hamburg', {direction : 'outbound'," -/// | + "maxDepth : 2, includeData: true}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_EDGES (graphName, vertexExample, options)` + +The GRAPH\_EDGES function returns all edges of the graph connected to the vertices +defined by the example. + +The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the +parameter vertexExamplex, *m* the average amount of edges of a vertex and *x* the maximal +depths. +Hence the default call would have a complexity of **O(n\*m)**; + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *vertexExample* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *options* (optional) : An object containing the following options: + * *direction* : The direction +of the edges as a string. Possible values are *outbound*, *inbound* and *any* (default). + * *edgeCollectionRestriction* : One or multiple edge + collection names. Only edges from these collections will be considered for the path. + * *startVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + start vertex of a path. + * *endVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + end vertex of a path. + * *edgeExamples* : A filter example +for the edges (see [example](#short-explanation-of-the-example-parameter)). + * *minDepth* : Defines the minimal length of a path from an edge + to a vertex (default is 1, which means only the edges directly connected to a vertex would + be returned). + * *maxDepth* : Defines the maximal length of a path from an edge + to a vertex (default is 1, which means only the edges directly connected to a vertex would + be returned). + * *maxIterations*: the maximum number of iterations that the traversal is + allowed to perform. It is sensible to set this number so unbounded traversals + will terminate. + * *includeData*: Defines if the result should contain only ids (false) or if all documents + should be fully extracted (true). By default this parameter is set to false, so only ids + will be returned. + +@EXAMPLES + +A route planner example, all edges to locations with a distance of either 700 or 600.: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_EDGES(" +| +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all outbound edges of Hamburg with a maximal depth of 2 : + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_EDGES(" +| +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Including the data: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdges3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_EDGES(" +| + "'routeplanner', 'germanCity/Hamburg', {direction : 'outbound'," +| + "maxDepth : 2, includeData: true}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_neighbors.md b/Documentation/DocuBlocks/JSF_aql_general_graph_neighbors.md index a608b2ed3e..8f517cef83 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_neighbors.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_neighbors.md @@ -1,70 +1,69 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_neighbors -/// The GRAPH\_NEIGHBORS function returns all neighbors of vertices. -/// -/// `GRAPH_NEIGHBORS (graphName, vertexExample, options)` -/// -/// By default only the direct neighbors (path length equals 1) are returned, but one can define -/// the range of the path length to the neighbors with the options *minDepth* and *maxDepth*. -/// The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the -/// parameter vertexExamplex, *m* the average amount of neighbors and *x* the maximal depths. -/// Hence the default call would have a complexity of **O(n\*m)**; -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *vertexExample* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *options* : An object containing the following options: -/// * *direction* : The direction -/// of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeExamples* : A filter example for the edges to -/// the neighbors (see [example](#short-explanation-of-the-example-parameter)). -/// * *neighborExamples* : An example for the desired neighbors -/// (see [example](#short-explanation-of-the-example-parameter)). -/// * *edgeCollectionRestriction* : One or multiple edge -/// collection names. Only edges from these collections will be considered for the path. -/// * *vertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be contained in the -/// result. This does not effect vertices on the path. -/// * *minDepth* : Defines the minimal -/// depth a path to a neighbor must have to be returned (default is 1). -/// * *maxDepth* : Defines the maximal -/// depth a path to a neighbor must have to be returned (default is 1). -/// * *maxIterations*: the maximum number of iterations that the traversal is -/// allowed to perform. It is sensible to set this number so unbounded traversals -/// will terminate at some point. -/// * *includeData* is a boolean value to define if the returned documents should be extracted -/// instead of returning their ids only. The default is *false*. -/// -/// Note: in ArangoDB versions prior to 2.6 *NEIGHBORS* returned the array of neighbor vertices with -/// all attributes and not just the vertex ids. To return to the same behavior, set the *includeData* -/// option to *true* in 2.6 and above. -/// -/// @EXAMPLES -/// -/// A route planner example, all neighbors of locations with a distance of either -/// 700 or 600.: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_NEIGHBORS(" -/// | +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all outbound neighbors of Hamburg with a maximal depth of 2 : -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_NEIGHBORS(" -/// | +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_NEIGHBORS function returns all neighbors of vertices. + +`GRAPH_NEIGHBORS (graphName, vertexExample, options)` + +By default only the direct neighbors (path length equals 1) are returned, but one can define +the range of the path length to the neighbors with the options *minDepth* and *maxDepth*. +The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the +parameter vertexExamplex, *m* the average amount of neighbors and *x* the maximal depths. +Hence the default call would have a complexity of **O(n\*m)**; + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *vertexExample* : An example for the desired + vertices (see [example](#short-explanation-of-the-example-parameter)). +* *options* : An object containing the following options: + * *direction* : The direction + of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *edgeExamples* : A filter example for the edges to + the neighbors (see [example](#short-explanation-of-the-example-parameter)). + * *neighborExamples* : An example for the desired neighbors + (see [example](#short-explanation-of-the-example-parameter)). + * *edgeCollectionRestriction* : One or multiple edge + collection names. Only edges from these collections will be considered for the path. + * *vertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be contained in the + result. This does not effect vertices on the path. + * *minDepth* : Defines the minimal + depth a path to a neighbor must have to be returned (default is 1). + * *maxDepth* : Defines the maximal + depth a path to a neighbor must have to be returned (default is 1). + * *maxIterations*: the maximum number of iterations that the traversal is + allowed to perform. It is sensible to set this number so unbounded traversals + will terminate at some point. + * *includeData* is a boolean value to define if the returned documents should be extracted + instead of returning their ids only. The default is *false*. + +Note: in ArangoDB versions prior to 2.6 *NEIGHBORS* returned the array of neighbor vertices with +all attributes and not just the vertex ids. To return to the same behavior, set the *includeData* +option to *true* in 2.6 and above. + +@EXAMPLES + +A route planner example, all neighbors of locations with a distance of either +700 or 600.: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_NEIGHBORS(" +| +"'routeplanner', {}, {edgeExamples : [{distance: 600}, {distance: 700}]}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all outbound neighbors of Hamburg with a maximal depth of 2 : + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphNeighbors2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_NEIGHBORS(" +| +"'routeplanner', 'germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_paths.md b/Documentation/DocuBlocks/JSF_aql_general_graph_paths.md index 82d434f77a..36721487bc 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_paths.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_paths.md @@ -1,46 +1,45 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_paths -/// The GRAPH\_PATHS function returns all paths of a graph. -/// -/// `GRAPH_PATHS (graphName, options)` -/// -/// The complexity of this method is **O(n\*n\*m)** with *n* being the amount of vertices in -/// the graph and *m* the average amount of connected edges; -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *options* : An object containing the following options: -/// * *direction* : The direction of the edges. Possible values are *any*, -/// *inbound* and *outbound* (default). -/// * *followCycles* (optional) : If set to *true* the query follows cycles in the graph, -/// default is false. -/// * *minLength* (optional) : Defines the minimal length a path must -/// have to be returned (default is 0). -/// * *maxLength* (optional) : Defines the maximal length a path must -/// have to be returned (default is 10). -/// -/// @EXAMPLES -/// -/// Return all paths of the graph "social": -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("social"); -/// db._query("RETURN GRAPH_PATHS('social')").toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Return all inbound paths of the graph "social" with a maximal -/// length of 1 and a minimal length of 2: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("social"); -/// | db._query( -/// | "RETURN GRAPH_PATHS('social', {direction : 'inbound', minLength : 1, maxLength : 2})" -/// ).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_PATHS function returns all paths of a graph. + +`GRAPH_PATHS (graphName, options)` + +The complexity of this method is **O(n\*n\*m)** with *n* being the amount of vertices in +the graph and *m* the average amount of connected edges; + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *options* : An object containing the following options: + * *direction* : The direction of the edges. Possible values are *any*, +*inbound* and *outbound* (default). + * *followCycles* (optional) : If set to *true* the query follows cycles in the graph, +default is false. + * *minLength* (optional) : Defines the minimal length a path must +have to be returned (default is 0). + * *maxLength* (optional) : Defines the maximal length a path must +have to be returned (default is 10). + +@EXAMPLES + +Return all paths of the graph "social": + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("social"); + db._query("RETURN GRAPH_PATHS('social')").toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Return all inbound paths of the graph "social" with a maximal +length of 1 and a minimal length of 2: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphPaths2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("social"); +| db._query( +| "RETURN GRAPH_PATHS('social', {direction : 'inbound', minLength : 1, maxLength : 2})" + ).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_radius.md b/Documentation/DocuBlocks/JSF_aql_general_graph_radius.md index ae1b9bb6c4..1dce0ad20c 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_radius.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_radius.md @@ -1,62 +1,61 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_radius -/// -/// `GRAPH_RADIUS (graphName, options)` -/// -/// *The GRAPH\_RADIUS function returns the -/// [radius](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) -/// of a graph.* -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// * *graphName* : The name of the graph as a string. -/// * *options* : An object containing the following options: -/// * *direction* : The direction of the edges. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible -/// values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) -/// (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight* : The name of the attribute of -/// the edges containing the length. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the radius of the graph. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_RADIUS('routeplanner')").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the radius of the graph. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// db._query("RETURN GRAPH_RADIUS('routeplanner', {weight : 'distance'})").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the radius of the graph regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_RADIUS(" -/// | + "'routeplanner', {direction : 'outbound', weight : 'distance'})" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`GRAPH_RADIUS (graphName, options)` + +*The GRAPH\_RADIUS function returns the +[radius](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) +of a graph.* + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +* *graphName* : The name of the graph as a string. +* *options* : An object containing the following options: + * *direction* : The direction of the edges. +Possible values are *outbound*, *inbound* and *any* (default). + * *algorithm* : The algorithm to calculate the shortest paths as a string. Possible +values are [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) + (default) and [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight* : The name of the attribute of +the edges containing the length. + * *defaultWeight* : Only used with the option *weight*. +If an edge does not have the attribute named as defined in option *weight* this default +is used as length. +If no default is supplied the default would be positive Infinity so the path and +hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the radius of the graph. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_RADIUS('routeplanner')").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the radius of the graph. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); + db._query("RETURN GRAPH_RADIUS('routeplanner', {weight : 'distance'})").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the radius of the graph regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRadius3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_RADIUS(" +| + "'routeplanner', {direction : 'outbound', weight : 'distance'})" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_shortest_paths.md b/Documentation/DocuBlocks/JSF_aql_general_graph_shortest_paths.md index d39d1631e8..b42a7bd6f3 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_shortest_paths.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_shortest_paths.md @@ -1,100 +1,99 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_shortest_paths -/// The GRAPH\_SHORTEST\_PATH function returns all shortest paths of a graph. -/// -/// `GRAPH_SHORTEST_PATH (graphName, startVertexExample, endVertexExample, options)` -/// -/// This function determines all shortest paths in a graph identified by *graphName*. -/// If one wants to call this function to receive nearly all shortest paths for a -/// graph the option *algorithm* should be set to -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) to -/// increase performance. -/// If no algorithm is provided in the options the function chooses the appropriate -/// one (either [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) -/// or [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)) according to its parameters. -/// The length of a path is by default the amount of edges from one start vertex to -/// an end vertex. The option weight allows the user to define an edge attribute -/// representing the length. -/// -/// The complexity of the function is described -/// [here](#the-complexity-of-the-shortest-path-algorithms). -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *startVertexExample* : An example for the desired start Vertices -/// (see [example](#short-explanation-of-the-example-parameter)). -/// * *endVertexExample* : An example for the desired -/// end Vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *options* (optional) : An object containing the following options: -/// * *direction* : The direction of the edges as a string. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeCollectionRestriction* : One or multiple edge -/// collection names. Only edges from these collections will be considered for the path. -/// * *startVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// start vertex of a path. -/// * *endVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// end vertex of a path. -/// * *edgeExamples* : A filter example for the -/// edges in the shortest paths -/// (see [example](#short-explanation-of-the-example-parameter)). -/// * *algorithm* : The algorithm to calculate -/// the shortest paths. If both start and end vertex examples are empty -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is -/// used, otherwise the default is [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight* : The name of the attribute of -/// the edges containing the length as a string. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path could -/// not be calculated. -/// * *stopAtFirstMatch* : Only useful if targetVertices is an example that matches -/// to more than one vertex. If so only the shortest path to -/// the closest of these target vertices is returned. -/// This flag is of special use if you have target pattern and -/// you want to know which vertex with this pattern is matched first. -/// * *includeData* : Triggers if only *_id*'s are returned (*false*, default) -/// or if data is included for all objects as well (*true*) -/// This will modify the content of *vertex*, *path.vertices* -/// and *path.edges*. -/// -/// NOTE: Since version 2.6 we have included a new optional parameter *includeData*. -/// This parameter triggers if the result contains the real data object *true* or -/// it just includes the *_id* values *false*. -/// The default value is *false* as it yields performance benefits. -/// -/// @EXAMPLES -/// -/// A route planner example, shortest distance from all german to all french cities: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_SHORTEST_PATH(" -/// | + "'routeplanner', {}, {}, {" + -/// | "weight : 'distance', endVertexCollectionRestriction : 'frenchCity', " + -/// | "includeData: true, " + -/// | "startVertexCollectionRestriction : 'germanCity'}) RETURN [e.startVertex, e.vertex._id, " + -/// | "e.distance, LENGTH(e.paths)]" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, shortest distance from Hamburg and Cologne to Lyon: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_SHORTEST_PATH(" -/// | +"'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], " + -/// | "'frenchCity/Lyon', " + -/// | "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance, LENGTH(e.paths)]" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_SHORTEST\_PATH function returns all shortest paths of a graph. + +`GRAPH_SHORTEST_PATH (graphName, startVertexExample, endVertexExample, options)` + +This function determines all shortest paths in a graph identified by *graphName*. +If one wants to call this function to receive nearly all shortest paths for a +graph the option *algorithm* should be set to +[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) to +increase performance. +If no algorithm is provided in the options the function chooses the appropriate +one (either [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) + or [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)) according to its parameters. +The length of a path is by default the amount of edges from one start vertex to +an end vertex. The option weight allows the user to define an edge attribute +representing the length. + +The complexity of the function is described +[here](#the-complexity-of-the-shortest-path-algorithms). + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *startVertexExample* : An example for the desired start Vertices + (see [example](#short-explanation-of-the-example-parameter)). +* *endVertexExample* : An example for the desired + end Vertices (see [example](#short-explanation-of-the-example-parameter)). +* *options* (optional) : An object containing the following options: + * *direction* : The direction of the edges as a string. + Possible values are *outbound*, *inbound* and *any* (default). + * *edgeCollectionRestriction* : One or multiple edge + collection names. Only edges from these collections will be considered for the path. + * *startVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + start vertex of a path. + * *endVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + end vertex of a path. + * *edgeExamples* : A filter example for the + edges in the shortest paths + (see [example](#short-explanation-of-the-example-parameter)). + * *algorithm* : The algorithm to calculate + the shortest paths. If both start and end vertex examples are empty + [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is + used, otherwise the default is [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight* : The name of the attribute of + the edges containing the length as a string. + * *defaultWeight* : Only used with the option *weight*. + If an edge does not have the attribute named as defined in option *weight* this default + is used as length. + If no default is supplied the default would be positive Infinity so the path could + not be calculated. + * *stopAtFirstMatch* : Only useful if targetVertices is an example that matches + to more than one vertex. If so only the shortest path to + the closest of these target vertices is returned. + This flag is of special use if you have target pattern and + you want to know which vertex with this pattern is matched first. + * *includeData* : Triggers if only *_id*'s are returned (*false*, default) + or if data is included for all objects as well (*true*) + This will modify the content of *vertex*, *path.vertices* + and *path.edges*. + +NOTE: Since version 2.6 we have included a new optional parameter *includeData*. +This parameter triggers if the result contains the real data object *true* or +it just includes the *_id* values *false*. +The default value is *false* as it yields performance benefits. + +@EXAMPLES + +A route planner example, shortest distance from all german to all french cities: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_SHORTEST_PATH(" +| + "'routeplanner', {}, {}, {" + +| "weight : 'distance', endVertexCollectionRestriction : 'frenchCity', " + +| "includeData: true, " + +| "startVertexCollectionRestriction : 'germanCity'}) RETURN [e.startVertex, e.vertex._id, " + +| "e.distance, LENGTH(e.paths)]" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, shortest distance from Hamburg and Cologne to Lyon: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphShortestPaths2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_SHORTEST_PATH(" +| +"'routeplanner', [{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], " + +| "'frenchCity/Lyon', " + +| "{weight : 'distance'}) RETURN [e.startVertex, e.vertex, e.distance, LENGTH(e.paths)]" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_traversal.md b/Documentation/DocuBlocks/JSF_aql_general_graph_traversal.md index 249ec32cc3..60d0f12641 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_traversal.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_traversal.md @@ -1,91 +1,90 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_traversal -/// The GRAPH\_TRAVERSAL function traverses through the graph. -/// -/// `GRAPH_TRAVERSAL (graphName, startVertexExample, direction, options)` -/// -/// This function performs traversals on the given graph. -/// -/// The complexity of this function strongly depends on the usage. -/// -/// *Parameters* -/// * *graphName* : The name of the graph as a string. -/// * *startVertexExample* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *direction* : The direction of the edges as a string. Possible values -/// are *outbound*, *inbound* and *any* (default). -/// * *options*: Object containing optional options. -/// -/// *Options*: -/// -/// * *strategy*: determines the visitation strategy. Possible values are -/// *depthfirst* and *breadthfirst*. Default is *breadthfirst*. -/// * *order*: determines the visitation order. Possible values are -/// *preorder* and *postorder*. -/// * *itemOrder*: determines the order in which connections returned by the -/// expander will be processed. Possible values are *forward* and *backward*. -/// * *maxDepth*: if set to a value greater than *0*, this will limit the -/// traversal to this maximum depth. -/// * *minDepth*: if set to a value greater than *0*, all vertices found on -/// a level below the *minDepth* level will not be included in the result. -/// * *maxIterations*: the maximum number of iterations that the traversal is -/// allowed to perform. It is sensible to set this number so unbounded traversals -/// will terminate at some point. -/// * *uniqueness*: an object that defines how repeated visitations of vertices should -/// be handled. The *uniqueness* object can have a sub-attribute *vertices*, and a -/// sub-attribute *edges*. Each sub-attribute can have one of the following values: -/// * *"none"*: no uniqueness constraints -/// * *"path"*: element is excluded if it is already contained in the current path. -/// This setting may be sensible for graphs that contain cycles (e.g. A -> B -> C -> A). -/// * *"global"*: element is excluded if it was already found/visited at any -/// point during the traversal. -/// * *filterVertices* An optional array of example vertex documents that the traversal will treat specially. -/// If no examples are given, the traversal will handle all encountered vertices equally. -/// If one or many vertex examples are given, the traversal will exclude any non-matching vertex from the -/// result and/or not descend into it. Optionally, filterVertices can contain a string containing the name -/// of a user-defined AQL function that should be responsible for filtering. -/// If so, the AQL function is expected to have the following signature: -/// -/// `function (config, vertex, path)` -/// -/// If a custom AQL function is used for filterVertices, it is expected to return one of the following values: -/// -/// * [ ]: Include the vertex in the result and descend into its connected edges -/// * [ "prune" ]: Will include the vertex in the result but not descend into its connected edges -/// * [ "exclude" ]: Will not include the vertex in the result but descend into its connected edges -/// * [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges -/// -/// * *vertexFilterMethod:* Only useful in conjunction with filterVertices and if no user-defined AQL function is used. -/// If specified, it will influence how vertices are handled that don't match the examples in filterVertices: -/// -/// * [ "prune" ]: Will include non-matching vertices in the result but not descend into them -/// * [ "exclude" ]: Will not include non-matching vertices in the result but descend into them -/// * [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges -/// -/// @EXAMPLES -/// -/// A route planner example, start a traversal from Hamburg : -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," + -/// | " 'outbound') RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, start a traversal from Hamburg with a max depth of 1 -/// so only the direct neighbors of Hamburg are returned: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," + -/// | " 'outbound', {maxDepth : 1}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_TRAVERSAL function traverses through the graph. + +`GRAPH_TRAVERSAL (graphName, startVertexExample, direction, options)` + +This function performs traversals on the given graph. + +The complexity of this function strongly depends on the usage. + +*Parameters* +* *graphName* : The name of the graph as a string. +* *startVertexExample* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *direction* : The direction of the edges as a string. Possible values +are *outbound*, *inbound* and *any* (default). +* *options*: Object containing optional options. + +*Options*: + +* *strategy*: determines the visitation strategy. Possible values are +*depthfirst* and *breadthfirst*. Default is *breadthfirst*. +* *order*: determines the visitation order. Possible values are +*preorder* and *postorder*. +* *itemOrder*: determines the order in which connections returned by the +expander will be processed. Possible values are *forward* and *backward*. +* *maxDepth*: if set to a value greater than *0*, this will limit the +traversal to this maximum depth. +* *minDepth*: if set to a value greater than *0*, all vertices found on +a level below the *minDepth* level will not be included in the result. +* *maxIterations*: the maximum number of iterations that the traversal is +allowed to perform. It is sensible to set this number so unbounded traversals +will terminate at some point. +* *uniqueness*: an object that defines how repeated visitations of vertices should +be handled. The *uniqueness* object can have a sub-attribute *vertices*, and a +sub-attribute *edges*. Each sub-attribute can have one of the following values: + * *"none"*: no uniqueness constraints + * *"path"*: element is excluded if it is already contained in the current path. + This setting may be sensible for graphs that contain cycles (e.g. A -> B -> C -> A). + * *"global"*: element is excluded if it was already found/visited at any + point during the traversal. +* *filterVertices* An optional array of example vertex documents that the traversal will treat specially. + If no examples are given, the traversal will handle all encountered vertices equally. + If one or many vertex examples are given, the traversal will exclude any non-matching vertex from the + result and/or not descend into it. Optionally, filterVertices can contain a string containing the name + of a user-defined AQL function that should be responsible for filtering. + If so, the AQL function is expected to have the following signature: + + `function (config, vertex, path)` + + If a custom AQL function is used for filterVertices, it is expected to return one of the following values: + + * [ ]: Include the vertex in the result and descend into its connected edges + * [ "prune" ]: Will include the vertex in the result but not descend into its connected edges + * [ "exclude" ]: Will not include the vertex in the result but descend into its connected edges + * [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges + +* *vertexFilterMethod:* Only useful in conjunction with filterVertices and if no user-defined AQL function is used. + If specified, it will influence how vertices are handled that don't match the examples in filterVertices: + + * [ "prune" ]: Will include non-matching vertices in the result but not descend into them + * [ "exclude" ]: Will not include non-matching vertices in the result but descend into them + * [ "prune", "exclude" ]: Will completely ignore the vertex and its connected edges + +@EXAMPLES + +A route planner example, start a traversal from Hamburg : + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," + +| " 'outbound') RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, start a traversal from Hamburg with a max depth of 1 +so only the direct neighbors of Hamburg are returned: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversal2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_TRAVERSAL('routeplanner', 'germanCity/Hamburg'," + +| " 'outbound', {maxDepth : 1}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_traversal_tree.md b/Documentation/DocuBlocks/JSF_aql_general_graph_traversal_tree.md index 9dd86e87bb..6e62ee2002 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_traversal_tree.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_traversal_tree.md @@ -1,50 +1,49 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_traversal_tree -/// The GRAPH\_TRAVERSAL\_TREE function traverses through the graph. -/// -/// `GRAPH_TRAVERSAL_TREE (graphName, startVertexExample, direction, connectName, options)` -/// This function creates a tree format from the result for a better visualization of -/// the path. -/// This function performs traversals on the given graph. -/// -/// The complexity of this function strongly depends on the usage. -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *startVertexExample* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *direction* : The direction of the edges as a string. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *connectName* : The result attribute which -/// contains the connection. -/// * *options* (optional) : An object containing options, see -/// [Graph Traversals](../Aql/GraphOperations.md#graphtraversal): -/// -/// @EXAMPLES -/// -/// A route planner example, start a traversal from Hamburg : -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg'," + -/// | " 'outbound', 'connnection') RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, start a traversal from Hamburg with a max depth of 1 so -/// only the direct neighbors of Hamburg are returned: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg',"+ -/// | " 'outbound', 'connnection', {maxDepth : 1}) RETURN e" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_TRAVERSAL\_TREE function traverses through the graph. + +`GRAPH_TRAVERSAL_TREE (graphName, startVertexExample, direction, connectName, options)` +This function creates a tree format from the result for a better visualization of +the path. +This function performs traversals on the given graph. + +The complexity of this function strongly depends on the usage. + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *startVertexExample* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *direction* : The direction of the edges as a string. + Possible values are *outbound*, *inbound* and *any* (default). +* *connectName* : The result attribute which + contains the connection. +* *options* (optional) : An object containing options, see + [Graph Traversals](../Aql/GraphOperations.md#graphtraversal): + +@EXAMPLES + +A route planner example, start a traversal from Hamburg : + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg'," + +| " 'outbound', 'connnection') RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, start a traversal from Hamburg with a max depth of 1 so + only the direct neighbors of Hamburg are returned: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphTraversalTree2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_TRAVERSAL_TREE('routeplanner', 'germanCity/Hamburg',"+ +| " 'outbound', 'connnection', {maxDepth : 1}) RETURN e" +).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_aql_general_graph_vertices.md b/Documentation/DocuBlocks/JSF_aql_general_graph_vertices.md index 2bbf922e6a..e91097aa72 100644 --- a/Documentation/DocuBlocks/JSF_aql_general_graph_vertices.md +++ b/Documentation/DocuBlocks/JSF_aql_general_graph_vertices.md @@ -1,45 +1,44 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_aql_general_graph_vertices -/// The GRAPH\_VERTICES function returns all vertices. -/// -/// `GRAPH_VERTICES (graphName, vertexExample, options)` -/// -/// According to the optional filters it will only return vertices that have -/// outbound, inbound or any (default) edges. -/// -/// *Parameters* -/// -/// * *graphName* : The name of the graph as a string. -/// * *vertexExample* : An example for the desired -/// vertices (see [example](#short-explanation-of-the-example-parameter)). -/// * *options* (optional) : An object containing the following options: -/// * *direction* : The direction of the edges as a string. Possible values are -/// *outbound*, *inbound* and *any* (default). -/// * *vertexCollectionRestriction* : One or multiple -/// vertex collections that should be considered. -/// -/// @EXAMPLES -/// -/// A route planner example, all vertices of the graph -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_VERTICES(" -/// +"'routeplanner', {}) RETURN e").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all vertices from collection *germanCity*. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | db._query("FOR e IN GRAPH_VERTICES(" -/// | +"'routeplanner', {}, {direction : 'any', vertexCollectionRestriction" + -/// " : 'germanCity'}) RETURN e").toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The GRAPH\_VERTICES function returns all vertices. + +`GRAPH_VERTICES (graphName, vertexExample, options)` + +According to the optional filters it will only return vertices that have +outbound, inbound or any (default) edges. + +*Parameters* + +* *graphName* : The name of the graph as a string. +* *vertexExample* : An example for the desired +vertices (see [example](#short-explanation-of-the-example-parameter)). +* *options* (optional) : An object containing the following options: + * *direction* : The direction of the edges as a string. Possible values are + *outbound*, *inbound* and *any* (default). + * *vertexCollectionRestriction* : One or multiple +vertex collections that should be considered. + +@EXAMPLES + +A route planner example, all vertices of the graph + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_VERTICES(" + +"'routeplanner', {}) RETURN e").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all vertices from collection *germanCity*. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertices2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| db._query("FOR e IN GRAPH_VERTICES(" +| +"'routeplanner', {}, {direction : 'any', vertexCollectionRestriction" + + " : 'germanCity'}) RETURN e").toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_body.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_body.md index b0d318738b..511f61aaf0 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_body.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_body.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_request_body -/// -/// `request.body()` -/// -/// Get the JSON parsed body of the request. If you need the raw version, please -/// refer to the *rawBody* function. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`request.body()` + +Get the JSON parsed body of the request. If you need the raw version, please +refer to the *rawBody* function. + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_cookie.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_cookie.md index 7cf22917c4..1e7af2cf60 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_cookie.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_cookie.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_request_cookie -/// -/// `request.cookie(name, cfg)` -/// -/// Read a cookie from the request. Optionally the cookie's signature can be verified. -/// -/// *Parameter* -/// -/// * *name*: the name of the cookie to read from the request. -/// * *cfg* (optional): an object with any of the following properties: -/// * *signed* (optional): an object with any of the following properties: -/// * *secret*: a secret string that was used to sign the cookie. -/// * *algorithm*: hashing algorithm that was used to sign the cookie. Default: *"sha256"*. -/// -/// If *signed* is a string, it will be used as the *secret* instead. -/// -/// If a *secret* is provided, a second cookie with the name *name + ".sig"* will -/// be read and its value will be verified as the cookie value's signature. -/// -/// If the cookie is not set or its signature is invalid, "undefined" will be returned instead. -/// -/// @EXAMPLES -/// -/// ``` -/// var sid = request.cookie("sid", {signed: "keyboardcat"}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`request.cookie(name, cfg)` + +Read a cookie from the request. Optionally the cookie's signature can be verified. + +*Parameter* + +* *name*: the name of the cookie to read from the request. +* *cfg* (optional): an object with any of the following properties: + * *signed* (optional): an object with any of the following properties: + * *secret*: a secret string that was used to sign the cookie. + * *algorithm*: hashing algorithm that was used to sign the cookie. Default: *"sha256"*. + +If *signed* is a string, it will be used as the *secret* instead. + +If a *secret* is provided, a second cookie with the name *name + ".sig"* will +be read and its value will be verified as the cookie value's signature. + +If the cookie is not set or its signature is invalid, "undefined" will be returned instead. + +@EXAMPLES + +``` +var sid = request.cookie("sid", {signed: "keyboardcat"}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_params.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_params.md index 045e7a337a..d4675e5b2d 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_params.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_params.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_request_params -/// -/// `request.params(key)` -/// -/// Get the parameters of the request. This process is two-fold: -/// -/// * If you have defined an URL like */test/:id* and the user requested -/// */test/1*, the call *params("id")* will return *1*. -/// * If you have defined an URL like */test* and the user gives a query -/// component, the query parameters will also be returned. So for example if -/// the user requested */test?a=2*, the call *params("a")* will return *2*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`request.params(key)` + +Get the parameters of the request. This process is two-fold: + +* If you have defined an URL like */test/:id* and the user requested + */test/1*, the call *params("id")* will return *1*. +* If you have defined an URL like */test* and the user gives a query + component, the query parameters will also be returned. So for example if + the user requested */test?a=2*, the call *params("a")* will return *2*. + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBody.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBody.md index 19af17ff0c..3b92949492 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBody.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBody.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_request_rawBody -/// -/// `request.rawBody()` -/// -/// The raw request body, not parsed. The body is returned as a UTF-8 string. -/// Note that this can only be used sensibly if the request body contains -/// valid UTF-8. If the request body is known to contain non-UTF-8 data, the -/// request body can be accessed by using `request.rawBodyBuffer`. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`request.rawBody()` + +The raw request body, not parsed. The body is returned as a UTF-8 string. +Note that this can only be used sensibly if the request body contains +valid UTF-8. If the request body is known to contain non-UTF-8 data, the +request body can be accessed by using `request.rawBodyBuffer`. + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBodyBuffer.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBodyBuffer.md index 30234f154e..8ab0857fcd 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBodyBuffer.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_rawBodyBuffer.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_request_rawBodyBuffer -/// -/// `request.rawBodyBuffer()` -/// -/// The raw request body, returned as a Buffer object. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`request.rawBodyBuffer()` + +The raw request body, returned as a Buffer object. + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_requestParts.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_requestParts.md index 68e91a8e23..1dbf43c8f3 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_requestParts.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_request_requestParts.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_request_requestParts -/// -/// `request.requestParts()` -/// -/// Returns an array containing the individual parts of a multi-part request. -/// Each part contains a `headers` attribute with all headers of the part, -/// and a `data` attribute with the content of the part in a Buffer object. -/// If the request is not a multi-part request, this function will throw an -/// error. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`request.requestParts()` + +Returns an array containing the individual parts of a multi-part request. +Each part contains a `headers` attribute with all headers of the part, +and a `data` attribute with the content of the part in a Buffer object. +If the request is not a multi-part request, this function will throw an +error. + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_cookie.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_cookie.md index a2bed4bf4a..030a5e5245 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_cookie.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_cookie.md @@ -1,33 +1,32 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_response_cookie -/// -/// `response.cookie(name, value, cfg)` -/// -/// Add a cookie to the response. Optionally the cookie can be signed. -/// -/// *Parameter* -/// -/// * *name*: the name of the cookie to add to the response. -/// * *value*: the value of the cookie to add to the response. -/// * *cfg* (optional): an object with any of the following properties: -/// * *ttl* (optional): the number of seconds until this cookie expires. -/// * *path* (optional): the cookie path. -/// * *domain* (optional): the cookie domain. -/// * *secure* (optional): mark the cookie as safe transport (HTTPS) only. -/// * *httpOnly* (optional): mark the cookie as HTTP(S) only. -/// * *signed* (optional): an object with any of the following properties: -/// * *secret*: a secret string to sign the cookie with. -/// * *algorithm*: hashing algorithm to sign the cookie with. Default: *"sha256"*. -/// -/// If *signed* is a string, it will be used as the *secret* instead. -/// -/// If a *secret* is provided, a second cookie with the name *name + ".sig"* will -/// be added to the response, containing the cookie's HMAC signature. -/// -/// @EXAMPLES -/// -/// ``` -/// response.cookie("sid", "abcdef", {signed: "keyboardcat"}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`response.cookie(name, value, cfg)` + +Add a cookie to the response. Optionally the cookie can be signed. + +*Parameter* + +* *name*: the name of the cookie to add to the response. +* *value*: the value of the cookie to add to the response. +* *cfg* (optional): an object with any of the following properties: + * *ttl* (optional): the number of seconds until this cookie expires. + * *path* (optional): the cookie path. + * *domain* (optional): the cookie domain. + * *secure* (optional): mark the cookie as safe transport (HTTPS) only. + * *httpOnly* (optional): mark the cookie as HTTP(S) only. + * *signed* (optional): an object with any of the following properties: + * *secret*: a secret string to sign the cookie with. + * *algorithm*: hashing algorithm to sign the cookie with. Default: *"sha256"*. + +If *signed* is a string, it will be used as the *secret* instead. + +If a *secret* is provided, a second cookie with the name *name + ".sig"* will +be added to the response, containing the cookie's HMAC signature. + +@EXAMPLES + +``` +response.cookie("sid", "abcdef", {signed: "keyboardcat"}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_json.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_json.md index ef6ee62170..1ef7eb3b0f 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_json.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_json.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_response_json -/// -/// `response.json(object)` -/// -/// Set the content type to JSON and the body to the JSON encoded *object* -/// you provided. -/// -/// @EXAMPLES -/// -/// ```js -/// response.json({'born': 'December 12, 1915'}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`response.json(object)` + +Set the content type to JSON and the body to the JSON encoded *object* +you provided. + +@EXAMPLES + +```js +response.json({'born': 'December 12, 1915'}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_send.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_send.md index e4065d2b3a..18f8aed574 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_send.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_send.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_response_send -/// -/// `response.send(value)` -/// -/// Sets the response body to the specified *value*. If *value* is a Buffer -/// object, the content type will be set to `application/octet-stream` if not -/// yet set. If *value* is a string, the content type will be set to `text/html` -/// if not yet set. If *value* is an object, it will be treated as in `res.json`. -/// -/// @EXAMPLES -/// -/// ```js -/// response.send({"born": "December 12, 1915"}); -/// response.send(new Buffer("some binary data")); -/// response.send("Hello World"); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`response.send(value)` + +Sets the response body to the specified *value*. If *value* is a Buffer +object, the content type will be set to `application/octet-stream` if not +yet set. If *value* is a string, the content type will be set to `text/html` +if not yet set. If *value* is an object, it will be treated as in `res.json`. + +@EXAMPLES + +```js +response.send({"born": "December 12, 1915"}); +response.send(new Buffer("some binary data")); +response.send("Hello World"); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_sendFile.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_sendFile.md index 901d89cc4c..38f0cc9773 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_sendFile.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_sendFile.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_response_sendFile -/// -/// `response.sendFile(filename, options)` -/// -/// Sets the content of the specified file as the response body. The filename -/// must be absolute. If no content type is yet set for the response, the -/// response's content type will be determined automatically based -/// on the filename extension. If no content type is known for the extension, -/// the content type will default to `application/octet-stream`. -/// -/// The `options` array can be used to control the behavior of sendFile. -/// Currently only the following option exists: -/// - `lastModified`: if set to true, the last modification date and time -/// of the file will be returned in the `Last-Modified` HTTP header -/// -/// @EXAMPLES -/// -/// ```js -/// response.sendFile('/tmp/results.json'); -/// response.sendFile(applicationContext.fileName('image.png'), { lastModified: true }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`response.sendFile(filename, options)` + +Sets the content of the specified file as the response body. The filename +must be absolute. If no content type is yet set for the response, the +response's content type will be determined automatically based +on the filename extension. If no content type is known for the extension, +the content type will default to `application/octet-stream`. + +The `options` array can be used to control the behavior of sendFile. +Currently only the following option exists: +- `lastModified`: if set to true, the last modification date and time + of the file will be returned in the `Last-Modified` HTTP header + +@EXAMPLES + +```js +response.sendFile('/tmp/results.json'); +response.sendFile(applicationContext.fileName('image.png'), { lastModified: true }); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_set.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_set.md index be1674f4de..4966167f92 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_set.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_set.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_response_set -/// -/// `response.set(key, value)` -/// -/// Set a header attribute, for example: -/// -/// @EXAMPLES -/// -/// ```js -/// response.set("Content-Length", 123); -/// response.set("Content-Type", "text/plain"); -/// ``` -/// -/// or alternatively: -/// -/// ```js -/// response.set({ -/// "Content-Length": "123", -/// "Content-Type": "text/plain" -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`response.set(key, value)` + +Set a header attribute, for example: + +@EXAMPLES + +```js +response.set("Content-Length", 123); +response.set("Content-Type", "text/plain"); +``` + +or alternatively: + +```js +response.set({ + "Content-Length": "123", + "Content-Type": "text/plain" +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_status.md b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_status.md index 74f993d90c..6abb858fe9 100644 --- a/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_status.md +++ b/Documentation/DocuBlocks/JSF_foxx_BaseMiddleware_response_status.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_BaseMiddleware_response_status -/// -/// `response.status(code)` -/// -/// Set the status *code* of your response, for example: -/// -/// @EXAMPLES -/// -/// ``` -/// response.status(404); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`response.status(code)` + +Set the status *code* of your response, for example: + +@EXAMPLES + +``` +response.status(404); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_errorResponse.md b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_errorResponse.md index 1036e8f38b..267f1ee756 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_errorResponse.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_errorResponse.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContextBuffer_errorResponse -/// -/// `Controller.allRoutes.errorResponse(errorClass, code, description)` -/// -/// This is equal to invoking `Route.errorResponse` on all routes bound to this controller. -/// -/// *Examples* -/// -/// ```js -/// app.allRoutes.errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!"); -/// -/// app.get("/foxx", function { -/// // Do something -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.allRoutes.errorResponse(errorClass, code, description)` + +This is equal to invoking `Route.errorResponse` on all routes bound to this controller. + +*Examples* + +```js +app.allRoutes.errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!"); + +app.get("/foxx", function { + // Do something +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIf.md b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIf.md index ce3eec92c3..cfd3660594 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIf.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIf.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContextBuffer_onlyIf -/// -/// `Controller.allRoutes.onlyIf(code, reason)` -/// -/// This is equal to invoking `Route.onlyIf` on all routes bound to this controller. -/// -/// *Examples* -/// -/// ```js -/// app.allRoutes.onlyIf(myPersonalCheck); -/// -/// app.get("/foxx", function { -/// // Do something -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.allRoutes.onlyIf(code, reason)` + +This is equal to invoking `Route.onlyIf` on all routes bound to this controller. + +*Examples* + +```js +app.allRoutes.onlyIf(myPersonalCheck); + +app.get("/foxx", function { + // Do something +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIfAuthenticated.md b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIfAuthenticated.md index e950792b28..f92afb0984 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIfAuthenticated.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_onlyIfAuthenticated.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContextBuffer_onlyIfAuthenticated -/// -/// `Controller.allRoutes.onlyIfAuthenticated(code, description)` -/// -/// This is equal to invoking `Route.onlyIfAuthenticated` on all routes bound to this controller. -/// -/// *Examples* -/// -/// ```js -/// app.allRoutes.onlyIfAuthenticated(401, "You need to be authenticated"); -/// -/// app.get("/foxx", function { -/// // Do something -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.allRoutes.onlyIfAuthenticated(code, description)` + +This is equal to invoking `Route.onlyIfAuthenticated` on all routes bound to this controller. + +*Examples* + +```js +app.allRoutes.onlyIfAuthenticated(401, "You need to be authenticated"); + +app.get("/foxx", function { + // Do something +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_pathParam.md b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_pathParam.md index 536021d3d2..0560cc6634 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_pathParam.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_pathParam.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContextBuffer_pathParam -/// -/// `Controller.allRoutes.pathParam(id, options)` -/// -/// This is equal to invoking `Route.pathParam` on all routes bound to this controller. -/// -/// *Examples* -/// -/// ```js -/// app.allRoutes.pathParam("id", joi.string().required().description("Id of the Foxx")); -/// -/// app.get("/foxx/:id", function { -/// // Secured by pathParam -/// }); -/// ``` -/// -/// You can also pass in a configuration object instead: -/// -/// ```js -/// app.allRoutes.pathParam("id", { -/// type: joi.string(), -/// required: true, -/// description: "Id of the Foxx" -/// }); -/// -/// app.get("/foxx/:id", function { -/// // Secured by pathParam -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.allRoutes.pathParam(id, options)` + +This is equal to invoking `Route.pathParam` on all routes bound to this controller. + +*Examples* + +```js +app.allRoutes.pathParam("id", joi.string().required().description("Id of the Foxx")); + +app.get("/foxx/:id", function { + // Secured by pathParam +}); +``` + +You can also pass in a configuration object instead: + +```js +app.allRoutes.pathParam("id", { + type: joi.string(), + required: true, + description: "Id of the Foxx" +}); + +app.get("/foxx/:id", function { + // Secured by pathParam +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_queryParam.md b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_queryParam.md index c7d1cd1fcb..de839cf880 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_queryParam.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContextBuffer_queryParam.md @@ -1,36 +1,35 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContextBuffer_queryParam -/// -/// `Controller.allRoutes.queryParam(id, options)` -/// -/// This is equal to invoking `Route.queryParam` on all routes bound to this controller. -/// -/// *Examples* -/// -/// ```js -/// app.allroutes.queryParam("id", -/// joi.string() -/// .required() -/// .description("Id of the Foxx") -/// .meta({allowMultiple: false}) -/// }); -/// -/// app.get("/foxx", function { -/// // Do something -/// }); -/// ``` -/// -/// You can also pass in a configuration object instead: -/// -/// ```js -/// app.allroutes.queryParam("id", { -/// type: joi.string().required().description("Id of the Foxx"), -/// allowMultiple: false -/// }); -/// -/// app.get("/foxx", function { -/// // Do something -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.allRoutes.queryParam(id, options)` + +This is equal to invoking `Route.queryParam` on all routes bound to this controller. + +*Examples* + +```js +app.allroutes.queryParam("id", + joi.string() + .required() + .description("Id of the Foxx") + .meta({allowMultiple: false}) +}); + +app.get("/foxx", function { + // Do something +}); +``` + +You can also pass in a configuration object instead: + +```js +app.allroutes.queryParam("id", { + type: joi.string().required().description("Id of the Foxx"), + allowMultiple: false +}); + +app.get("/foxx", function { + // Do something +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_bodyParam.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_bodyParam.md index 6db1801118..f1bed978e9 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_bodyParam.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_bodyParam.md @@ -1,77 +1,76 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_bodyParam -/// -/// `Route.bodyParam(paramName, options)` -/// -/// Defines that this route expects a JSON body when requested and binds it to -/// a pseudo parameter with the name `paramName`. -/// The body can than be read in the the handler using `req.params(paramName)` on the request object. -/// In the `options` parameter you can define how a valid request body should look like. -/// This definition can be done in two ways, either using *joi* directly. -/// Accessing the body in this case will give you a JSON object. -/// The other way is to use a Foxx *Model*. -/// Accessing the body in this case will give you an instance of this Model. -/// For both ways an entry for the body will be added in the Documentation in ArangoDBs WebInterface. -/// For information about how to annotate your models, see the Model section. -/// All requests sending a body that does not match the validation given this way -/// will automatically be rejected. -/// -/// You can also wrap the definition into an array, in this case this route -/// expects a body of type array containing arbitrary many valid objects. -/// Accessing the body parameter will then of course return an array of objects. -/// -/// Note: The behavior of `bodyParam` changes depending on the `rootElement` option -/// set in the [manifest](../Develop/Manifest.md). If it is set to `true`, it is -/// expected that the body is an -/// object with a key of the same name as the `paramName` argument. -/// The value of this object is either a single object or in the case of a multi -/// element an array of objects. -/// -/// *Parameter* -/// -/// * *paramName*: name of the body parameter in `req.parameters`. -/// * *options*: a joi schema or an object with the following properties: -/// * *description*: the documentation description of the request body. -/// * *type*: the Foxx model or joi schema to use. -/// * *allowInvalid* (optional): `true` if validation should be skipped. (Default: `false`) -/// -/// *Examples* -/// -/// ```js -/// app.post("/foxx", function (req, res) { -/// var foxxBody = req.parameters.foxxBody; -/// // Do something with foxxBody -/// }).bodyParam("foxxBody", { -/// description: "Body of the Foxx", -/// type: FoxxBodyModel -/// }); -/// ``` -/// -/// Using a joi schema: -/// -/// ```js -/// app.post("/foxx", function (req, res) { -/// var joiBody = req.parameters.joiBody; -/// // Do something with the number -/// }).bodyParam("joiBody", { -/// type: joi.number().integer().min(5), -/// description: "A number greater than five", -/// allowInvalid: false // default -/// }); -/// ``` -/// -/// Shorthand version: -/// -/// ```js -/// app.post("/foxx", function (req, res) { -/// var joiBody = req.parameters.joiBody; -/// // Do something with the number -/// }).bodyParam( -/// "joiBody", -/// joi.number().integer().min(5) -/// .description("A number greater than five") -/// .meta({allowInvalid: false}) // default -/// ); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Route.bodyParam(paramName, options)` + +Defines that this route expects a JSON body when requested and binds it to +a pseudo parameter with the name `paramName`. +The body can than be read in the the handler using `req.params(paramName)` on the request object. +In the `options` parameter you can define how a valid request body should look like. +This definition can be done in two ways, either using *joi* directly. +Accessing the body in this case will give you a JSON object. +The other way is to use a Foxx *Model*. +Accessing the body in this case will give you an instance of this Model. +For both ways an entry for the body will be added in the Documentation in ArangoDBs WebInterface. +For information about how to annotate your models, see the Model section. +All requests sending a body that does not match the validation given this way +will automatically be rejected. + +You can also wrap the definition into an array, in this case this route +expects a body of type array containing arbitrary many valid objects. +Accessing the body parameter will then of course return an array of objects. + +Note: The behavior of `bodyParam` changes depending on the `rootElement` option +set in the [manifest](../Develop/Manifest.md). If it is set to `true`, it is +expected that the body is an +object with a key of the same name as the `paramName` argument. +The value of this object is either a single object or in the case of a multi +element an array of objects. + +*Parameter* + + * *paramName*: name of the body parameter in `req.parameters`. + * *options*: a joi schema or an object with the following properties: + * *description*: the documentation description of the request body. + * *type*: the Foxx model or joi schema to use. + * *allowInvalid* (optional): `true` if validation should be skipped. (Default: `false`) + +*Examples* + +```js +app.post("/foxx", function (req, res) { + var foxxBody = req.parameters.foxxBody; + // Do something with foxxBody +}).bodyParam("foxxBody", { + description: "Body of the Foxx", + type: FoxxBodyModel +}); +``` + +Using a joi schema: + +```js +app.post("/foxx", function (req, res) { + var joiBody = req.parameters.joiBody; + // Do something with the number +}).bodyParam("joiBody", { + type: joi.number().integer().min(5), + description: "A number greater than five", + allowInvalid: false // default +}); +``` + +Shorthand version: + +```js +app.post("/foxx", function (req, res) { + var joiBody = req.parameters.joiBody; + // Do something with the number +}).bodyParam( + "joiBody", + joi.number().integer().min(5) + .description("A number greater than five") + .meta({allowInvalid: false}) // default +); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_errorResponse.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_errorResponse.md index a816269c40..c7a7efd5bc 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_errorResponse.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_errorResponse.md @@ -1,44 +1,43 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_errorResponse -/// -/// `Route.errorResponse(errorClassOrName, code, description, [callback])` -/// -/// Define a reaction to a thrown error for this route: If your handler throws an error -/// of the errorClass defined in `errorClassOrName` or the error has an attribute `name` equal to `errorClassOrName`, -/// it will be caught and the response object will be filled with the given -/// status code and a JSON with error set to your description as the body. -/// -/// If you want more control over the returned JSON, you can give an optional fourth -/// parameter in form of a function. It gets the error as an argument, the return -/// value will be transformed into JSON and then be used as the body. -/// The status code will be used as described above. The description will be used for -/// the documentation. -/// -/// It also adds documentation for this error response to the generated documentation. -/// -/// *Examples* -/// -/// ```js -/// /* define our own error type, FoxxyError */ -/// var FoxxyError = function (message) { -/// this.name = "FError"; -/// this.message = "the following FoxxyError occurred: " + message; -/// }; -/// FoxxyError.prototype = new Error(); -/// -/// app.get("/foxx", function { -/// /* throws a FoxxyError */ -/// throw new FoxxyError(); -/// }).errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!"); -/// -/// app.get("/foxx", function { -/// throw new FoxxyError("oops!"); -/// }).errorResponse("FError", 303, "This went completely wrong. Sorry!", function (e) { -/// return { -/// code: 123, -/// desc: e.message -/// }; -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Route.errorResponse(errorClassOrName, code, description, [callback])` + +Define a reaction to a thrown error for this route: If your handler throws an error +of the errorClass defined in `errorClassOrName` or the error has an attribute `name` equal to `errorClassOrName`, +it will be caught and the response object will be filled with the given +status code and a JSON with error set to your description as the body. + +If you want more control over the returned JSON, you can give an optional fourth +parameter in form of a function. It gets the error as an argument, the return +value will be transformed into JSON and then be used as the body. +The status code will be used as described above. The description will be used for +the documentation. + +It also adds documentation for this error response to the generated documentation. + +*Examples* + +```js +/* define our own error type, FoxxyError */ +var FoxxyError = function (message) { + this.name = "FError"; + this.message = "the following FoxxyError occurred: " + message; +}; +FoxxyError.prototype = new Error(); + +app.get("/foxx", function { + /* throws a FoxxyError */ + throw new FoxxyError(); +}).errorResponse(FoxxyError, 303, "This went completely wrong. Sorry!"); + +app.get("/foxx", function { + throw new FoxxyError("oops!"); +}).errorResponse("FError", 303, "This went completely wrong. Sorry!", function (e) { + return { + code: 123, + desc: e.message + }; +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_notes.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_notes.md index f8f2b3c2f4..8ddf0e408e 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_notes.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_notes.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_notes -/// -/// `Route.notes(...description)` -/// -/// Set the long description for this route in the documentation -// -/// *Examples* -/// -/// Version with comment: -/// -/// ```js -/// /** Short description -/// * -/// * Longer description -/// * with multiple lines -/// */ -/// app.get("/foxx", function() { -/// }); -/// ``` -/// -/// is identical to: -/// -/// ```js -/// app.get("/foxx", function() { -/// }) -/// .summary("Short description") -/// .notes(["Longer description", "with multiple lines"]); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Route.notes(...description)` + +Set the long description for this route in the documentation + +*Examples* + +Version with comment: + +```js +/** Short description + * + * Longer description + * with multiple lines + */ +app.get("/foxx", function() { +}); +``` + +is identical to: + +```js +app.get("/foxx", function() { +}) +.summary("Short description") +.notes(["Longer description", "with multiple lines"]); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIf.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIf.md index d9e130e042..ea43aa2a31 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIf.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIf.md @@ -1,21 +1,20 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_onlyIf -/// -/// `Route.onlyIf(check)` -/// -/// This functionality is used to secure a route by applying a checking function -/// on the request beforehand, for example the check authorization. -/// It expects `check` to be a function that takes the request object as first parameter. -/// This function is executed before the actual handler is invoked. -/// If `check` throws an error the actual handler will not be invoked. -/// Remember to provide an `errorResponse` on the route as well to define the behavior in this case. -/// -/// *Examples* -/// -/// ```js -/// app.get("/foxx", function { -/// // Do something -/// }).onlyIf(aFunction).errorResponse(ErrorClass, 303, "This went completely wrong. Sorry!"); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Route.onlyIf(check)` + +This functionality is used to secure a route by applying a checking function +on the request beforehand, for example the check authorization. +It expects `check` to be a function that takes the request object as first parameter. +This function is executed before the actual handler is invoked. +If `check` throws an error the actual handler will not be invoked. +Remember to provide an `errorResponse` on the route as well to define the behavior in this case. + +*Examples* + +```js +app.get("/foxx", function { + // Do something +}).onlyIf(aFunction).errorResponse(ErrorClass, 303, "This went completely wrong. Sorry!"); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIfAuthenticated.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIfAuthenticated.md index 28d8756867..18603131dc 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIfAuthenticated.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_onlyIfAuthenticated.md @@ -1,20 +1,19 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_onlyIfAuthenticated -/// -/// `FoxxController#onlyIfAuthenticated(code, reason)` -/// -/// Please activate sessions for this app if you want to use this function. -/// Or activate authentication (deprecated). -/// If the user is logged in, it will do nothing. Otherwise it will respond with -/// the status code and the reason you provided (the route handler won't be called). -/// This will also add the according documentation for this route. -/// -/// *Examples* -/// -/// ```js -/// app.get("/foxx", function { -/// // Do something -/// }).onlyIfAuthenticated(401, "You need to be authenticated"); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxController#onlyIfAuthenticated(code, reason)` + +Please activate sessions for this app if you want to use this function. +Or activate authentication (deprecated). +If the user is logged in, it will do nothing. Otherwise it will respond with +the status code and the reason you provided (the route handler won't be called). +This will also add the according documentation for this route. + +*Examples* + +```js +app.get("/foxx", function { + // Do something +}).onlyIfAuthenticated(401, "You need to be authenticated"); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_pathParam.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_pathParam.md index 7129a9c463..b438ff9ab5 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_pathParam.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_pathParam.md @@ -1,44 +1,43 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_pathParam -/// -/// `Route.pathParam(id, options)` -/// -/// If you defined a route "/foxx/:name", containing a parameter called `name` you can -/// constrain which format this parameter is allowed to have. -/// This format is defined using *joi* in the `options` parameter. -/// Using this function will at first allow you to access this parameter in your -/// route handler using `req.params(id)`, will reject any request having a paramter -/// that does not match the *joi* definition and creates a documentation for this -/// parameter in ArangoDBs WebInterface. -/// -/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi). -/// -/// *Parameter* -/// -/// * *id*: name of the param. -/// * *options*: a joi schema or an object with the following properties: -/// * *type*: a joi schema. -/// * *description*: documentation description for the parameter. -/// * *required* (optional): whether the parameter is required. Default: determined by *type*. -/// -/// *Examples* -/// -/// ```js -/// app.get("/foxx/:name", function { -/// // Do something -/// }).pathParam("name", joi.string().required().description("Name of the Foxx")); -/// ``` -/// -/// You can also pass in a configuration object instead: -/// -/// ```js -/// app.get("/foxx/:name", function { -/// // Do something -/// }).pathParam("name", { -/// type: joi.string(), -/// required: true, -/// description: "Name of the Foxx" -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Route.pathParam(id, options)` + +If you defined a route "/foxx/:name", containing a parameter called `name` you can +constrain which format this parameter is allowed to have. +This format is defined using *joi* in the `options` parameter. +Using this function will at first allow you to access this parameter in your +route handler using `req.params(id)`, will reject any request having a paramter +that does not match the *joi* definition and creates a documentation for this +parameter in ArangoDBs WebInterface. + +For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi). + +*Parameter* + +* *id*: name of the param. +* *options*: a joi schema or an object with the following properties: + * *type*: a joi schema. + * *description*: documentation description for the parameter. + * *required* (optional): whether the parameter is required. Default: determined by *type*. + +*Examples* + +```js +app.get("/foxx/:name", function { + // Do something +}).pathParam("name", joi.string().required().description("Name of the Foxx")); +``` + +You can also pass in a configuration object instead: + +```js +app.get("/foxx/:name", function { + // Do something +}).pathParam("name", { + type: joi.string(), + required: true, + description: "Name of the Foxx" +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_queryParam.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_queryParam.md index a23da71ce7..dc1b76859e 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_queryParam.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_queryParam.md @@ -1,53 +1,52 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_queryParam -/// -/// `Route.queryParam(id, options)` -/// -/// Describe a query parameter: -/// -/// If you defined a route "/foxx", you can allow a query paramter with the -/// name `id` on it and constrain the format of this parameter by giving it a *joi* type in the `options` parameter. -/// Using this function will at first allow you to access this parameter in your -/// route handler using `req.params(id)`, will reject any request having a paramter -/// that does not match the *joi* definition and creates a documentation for this -/// parameter in ArangoDBs WebInterface. -/// -/// For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi). -/// -/// You can also provide a description of this parameter and -/// whether you can provide the parameter multiple times. -/// -/// *Parameter* -/// -/// * *id*: name of the parameter -/// * *options*: a joi schema or an object with the following properties: -/// * *type*: a joi schema -/// * *description*: documentation description for this param. -/// * *required* (optional): whether the param is required. Default: determined by *type*. -/// * *allowMultiple* (optional): whether the param can be specified more than once. Default: `false`. -/// -/// *Examples* -/// -/// ```js -/// app.get("/foxx", function { -/// // Do something -/// }).queryParam("id", -/// joi.string() -/// .required() -/// .description("Id of the Foxx") -/// .meta({allowMultiple: false}) -/// }); -/// ``` -/// -/// You can also pass in a configuration object instead: -/// -/// ```js -/// app.get("/foxx", function { -/// // Do something -/// }).queryParam("id", { -/// type: joi.string().required().description("Id of the Foxx"), -/// allowMultiple: false -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Route.queryParam(id, options)` + +Describe a query parameter: + +If you defined a route "/foxx", you can allow a query paramter with the +name `id` on it and constrain the format of this parameter by giving it a *joi* type in the `options` parameter. +Using this function will at first allow you to access this parameter in your +route handler using `req.params(id)`, will reject any request having a paramter +that does not match the *joi* definition and creates a documentation for this +parameter in ArangoDBs WebInterface. + +For more information on *joi* see [the official Joi documentation](https://github.com/spumko/joi). + +You can also provide a description of this parameter and +whether you can provide the parameter multiple times. + +*Parameter* + +* *id*: name of the parameter +* *options*: a joi schema or an object with the following properties: + * *type*: a joi schema + * *description*: documentation description for this param. + * *required* (optional): whether the param is required. Default: determined by *type*. + * *allowMultiple* (optional): whether the param can be specified more than once. Default: `false`. + +*Examples* + +```js +app.get("/foxx", function { + // Do something +}).queryParam("id", + joi.string() + .required() + .description("Id of the Foxx") + .meta({allowMultiple: false}) +}); +``` + +You can also pass in a configuration object instead: + +```js +app.get("/foxx", function { + // Do something +}).queryParam("id", { + type: joi.string().required().description("Id of the Foxx"), + allowMultiple: false +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_RequestContext_summary.md b/Documentation/DocuBlocks/JSF_foxx_RequestContext_summary.md index ea882f0a1b..a96116bc94 100644 --- a/Documentation/DocuBlocks/JSF_foxx_RequestContext_summary.md +++ b/Documentation/DocuBlocks/JSF_foxx_RequestContext_summary.md @@ -1,36 +1,35 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_RequestContext_summary -/// -/// `Route.summary(description)` -/// -/// Set the summary for this route in the documentation. -/// Can't be longer than 8192 characters. -/// This is equal to using JavaDoc style comments right above your function. -/// If you provide both comment and `summary()` the call to `summary()` wins -/// and will be used. -/// -/// *Examples* -/// -/// Version with comment: -/// -/// ```js -/// /** Short description -/// * -/// * Longer description -/// * with multiple lines -/// */ -/// app.get("/foxx", function() { -/// }); -/// ``` -/// -/// is identical to: -/// -/// ```js -/// app.get("/foxx", function() { -/// }) -/// .summary("Short description") -/// .notes(["Longer description", "with multiple lines"]); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Route.summary(description)` + +Set the summary for this route in the documentation. +Can't be longer than 8192 characters. +This is equal to using JavaDoc style comments right above your function. +If you provide both comment and `summary()` the call to `summary()` wins +and will be used. + +*Examples* + +Version with comment: + +```js +/** Short description + * + * Longer description + * with multiple lines + */ +app.get("/foxx", function() { +}); +``` + +is identical to: + +```js +app.get("/foxx", function() { +}) +.summary("Short description") +.notes(["Longer description", "with multiple lines"]); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_activateAuthentication.md b/Documentation/DocuBlocks/JSF_foxx_controller_activateAuthentication.md index ad07a0cecf..f57737d685 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_activateAuthentication.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_activateAuthentication.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_activateAuthentication -/// -/// `Controller.activateAuthentication(opts)` -/// -/// To activate authentication for this controller, call this function before defining any routes. -/// In the `opts` object you can set the following keys: -/// -/// * *type*: Currently we only support *cookie*, but this will change in the future -/// * *cookieLifetime*: An integer. Lifetime of cookies in seconds -/// * *cookieName*: A string used as the name of the cookie -/// * *sessionLifetime*: An integer. Lifetime of sessions in seconds -/// -/// @EXAMPLES -/// -/// ```js -/// app.activateAuthentication({ -/// type: "cookie", -/// cookieLifetime: 360000, -/// cookieName: "my_cookie", -/// sessionLifetime: 400, -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.activateAuthentication(opts)` + +To activate authentication for this controller, call this function before defining any routes. +In the `opts` object you can set the following keys: + +* *type*: Currently we only support *cookie*, but this will change in the future +* *cookieLifetime*: An integer. Lifetime of cookies in seconds +* *cookieName*: A string used as the name of the cookie +* *sessionLifetime*: An integer. Lifetime of sessions in seconds + +@EXAMPLES + +```js +app.activateAuthentication({ + type: "cookie", + cookieLifetime: 360000, + cookieName: "my_cookie", + sessionLifetime: 400, +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_after.md b/Documentation/DocuBlocks/JSF_foxx_controller_after.md index 0da7c48fcc..90faa6db5c 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_after.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_after.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_after -/// -/// `Controller.after(path, callback)` -/// -/// Similar to `Controller.before(path, callback)` but `callback` will be invoked -/// after the request is handled in the specific route. -/// -/// @EXAMPLES -/// -/// ```js -/// app.after('/high/way', function(req, res) { -/// //Do some crazy response logging -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.after(path, callback)` + +Similar to `Controller.before(path, callback)` but `callback` will be invoked +after the request is handled in the specific route. + +@EXAMPLES + +```js +app.after('/high/way', function(req, res) { + //Do some crazy response logging +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_apiDocumentation.md b/Documentation/DocuBlocks/JSF_foxx_controller_apiDocumentation.md index d844ad9b50..6248796bb3 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_apiDocumentation.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_apiDocumentation.md @@ -1,63 +1,62 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_apiDocumentation -/// -/// `Controller.apiDocumentation(path, [opts])` -/// -/// Mounts the API documentation (Swagger) at the given `path`. -/// -/// Note that the `path` can use path parameters as usual but must not use any -/// wildcard (`*`) or optional (`:name?`) parameters. -/// -/// The optional **opts** can be an object with any of the following properties: -/// -/// * **before**: a function that will be executed before a request to -/// this endpoint is processed further. -/// * **appPath**: the mount point of the app for which documentation will be -/// shown. Default: the mount point of the active app. -/// * **indexFile**: file path or file name of the Swagger HTML file. -/// Default: `"index.html"`. -/// * **swaggerJson**: file path or file name of the Swagger API description JSON -/// file or a function `swaggerJson(req, res, opts)` that sends a Swagger API -/// description in JSON. Default: the built-in Swagger description generator. -/// * **swaggerRoot**: absolute path that will be used as the path path for any -/// relative paths of the documentation assets, **swaggerJson** file and -/// the **indexFile**. Default: the built-in Swagger distribution. -/// -/// If **opts** is a function, it will be used as the value of **opts.before**. -/// -/// If **opts.before** returns `false`, the request will not be processed -/// further. -/// -/// If **opts.before** returns an object, any properties will override the -/// equivalent properties of **opts** for the current request. -/// -/// Of course all **before**, **after** or **around** functions defined on the -/// controller will also be executed as usual. -/// -/// **Examples** -/// -/// ```js -/// controller.apiDocumentation('/my/dox'); -/// -/// ``` -/// -/// A request to `/my/dox` will be redirect to `/my/dox/index.html`, -/// which will show the API documentation of the active app. -/// -/// ```js -/// controller.apiDocumentation('/my/dox', function (req, res) { -/// if (!req.session.get('uid')) { -/// res.status(403); -/// res.json({error: 'only logged in users may see the API'}); -/// return false; -/// } -/// return {appPath: req.parameters.mount}; -/// }); -/// ``` -/// -/// A request to `/my/dox/index.html?mount=/_admin/aardvark` will show the -/// API documentation of the admin frontend (mounted at `/_admin/aardvark`). -/// If the user is not logged in, the error message will be shown instead. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.apiDocumentation(path, [opts])` + +Mounts the API documentation (Swagger) at the given `path`. + +Note that the `path` can use path parameters as usual but must not use any +wildcard (`*`) or optional (`:name?`) parameters. + +The optional **opts** can be an object with any of the following properties: + +* **before**: a function that will be executed before a request to + this endpoint is processed further. +* **appPath**: the mount point of the app for which documentation will be + shown. Default: the mount point of the active app. +* **indexFile**: file path or file name of the Swagger HTML file. + Default: `"index.html"`. +* **swaggerJson**: file path or file name of the Swagger API description JSON + file or a function `swaggerJson(req, res, opts)` that sends a Swagger API + description in JSON. Default: the built-in Swagger description generator. +* **swaggerRoot**: absolute path that will be used as the path path for any + relative paths of the documentation assets, **swaggerJson** file and + the **indexFile**. Default: the built-in Swagger distribution. + +If **opts** is a function, it will be used as the value of **opts.before**. + +If **opts.before** returns `false`, the request will not be processed +further. + +If **opts.before** returns an object, any properties will override the +equivalent properties of **opts** for the current request. + +Of course all **before**, **after** or **around** functions defined on the +controller will also be executed as usual. + +**Examples** + +```js +controller.apiDocumentation('/my/dox'); + +``` + +A request to `/my/dox` will be redirect to `/my/dox/index.html`, +which will show the API documentation of the active app. + +```js +controller.apiDocumentation('/my/dox', function (req, res) { + if (!req.session.get('uid')) { + res.status(403); + res.json({error: 'only logged in users may see the API'}); + return false; + } + return {appPath: req.parameters.mount}; +}); +``` + +A request to `/my/dox/index.html?mount=/_admin/aardvark` will show the +API documentation of the admin frontend (mounted at `/_admin/aardvark`). +If the user is not logged in, the error message will be shown instead. + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_around.md b/Documentation/DocuBlocks/JSF_foxx_controller_around.md index db319ec8e9..e1a2b8493c 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_around.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_around.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_around -/// -/// `Controller.around(path, callback)` -/// -/// Similar to `Controller.before(path, callback)` `callback` will be invoked -/// instead of the specific handler. -/// `callback` takes two additional paramaters `opts` and `next` where -/// `opts` contains options assigned to the route and `next` is a function. -/// Whenever you call `next` in `callback` the specific handler is invoked, -/// if you do not call `next` the specific handler will not be invoked at all. -/// So using around you can execute code before and after a specific handler -/// and even call the handler only under certain circumstances. -/// If you omit `path` `callback` will be called on every request. -/// -/// @EXAMPLES -/// -/// ```js -/// app.around('/high/way', function(req, res, opts, next) { -/// //Do some crazy request logging -/// next(); -/// //Do some more crazy request logging -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.around(path, callback)` + +Similar to `Controller.before(path, callback)` `callback` will be invoked +instead of the specific handler. +`callback` takes two additional paramaters `opts` and `next` where +`opts` contains options assigned to the route and `next` is a function. +Whenever you call `next` in `callback` the specific handler is invoked, +if you do not call `next` the specific handler will not be invoked at all. +So using around you can execute code before and after a specific handler +and even call the handler only under certain circumstances. +If you omit `path` `callback` will be called on every request. + +@EXAMPLES + +```js +app.around('/high/way', function(req, res, opts, next) { + //Do some crazy request logging + next(); + //Do some more crazy request logging +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_before.md b/Documentation/DocuBlocks/JSF_foxx_controller_before.md index a6c1627a20..ae8e97ae41 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_before.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_before.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_before -/// -/// `Controller.before(path, callback)` -/// -/// Defines an additional function on the route `path` which will be executed -/// before the callback defined for a specific HTTP verb is executed. -/// The `callback` function has the same signature as the `callback` in the -/// specific route. -/// You can also omit the `path`, in this case `callback` will be executed -/// before handleing any request in this Controller. -/// -/// If `callback` returns the Boolean value `false`, the route handling -/// will not proceed. You can use this to intercept invalid or unauthorized -/// requests and prevent them from being passed to the matching routes. -/// -/// @EXAMPLES -/// -/// ```js -/// app.before('/high/way', function(req, res) { -/// //Do some crazy request logging -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.before(path, callback)` + +Defines an additional function on the route `path` which will be executed +before the callback defined for a specific HTTP verb is executed. +The `callback` function has the same signature as the `callback` in the +specific route. +You can also omit the `path`, in this case `callback` will be executed +before handleing any request in this Controller. + +If `callback` returns the Boolean value `false`, the route handling +will not proceed. You can use this to intercept invalid or unauthorized +requests and prevent them from being passed to the matching routes. + +@EXAMPLES + +```js +app.before('/high/way', function(req, res) { + //Do some crazy request logging +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_changePassword.md b/Documentation/DocuBlocks/JSF_foxx_controller_changePassword.md index 2144c1f27f..46a72bf9e4 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_changePassword.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_changePassword.md @@ -1,33 +1,32 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_changePassword -/// -/// FoxxController#changePassword(route, opts)` -/// -/// Add a route for the logged in user to change the password. -/// You can provide further customizations via the -/// the options: -/// -/// * *passwordField* can be used to adjust the expected attribute -/// in the *post* request. It defaults to *password*. -/// * *onSuccess* is a function that you can define to do something if the change was -/// successful. This includes sending a response to the user. This defaults to a -/// function that returns a JSON with *notice* set to "Changed password!". -/// * *onError* is a function that you can define to do something if the login did not -/// work. This includes sending a response to the user. This defaults to a function -/// that sets the response to 401 and returns a JSON with *error* set to -/// "No session was found". -/// -/// Both *onSuccess* and *onError* should take request and result as arguments. -/// -/// @EXAMPLES -/// -/// ```js -/// app.changePassword('/changePassword', { -/// onSuccess(req, res) { -/// res.json({"success": true}); -/// } -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +FoxxController#changePassword(route, opts)` + +Add a route for the logged in user to change the password. +You can provide further customizations via the +the options: + +* *passwordField* can be used to adjust the expected attribute + in the *post* request. It defaults to *password*. +* *onSuccess* is a function that you can define to do something if the change was + successful. This includes sending a response to the user. This defaults to a + function that returns a JSON with *notice* set to "Changed password!". +* *onError* is a function that you can define to do something if the login did not + work. This includes sending a response to the user. This defaults to a function + that sets the response to 401 and returns a JSON with *error* set to + "No session was found". + +Both *onSuccess* and *onError* should take request and result as arguments. + +@EXAMPLES + +```js +app.changePassword('/changePassword', { + onSuccess(req, res) { + res.json({"success": true}); + } +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_delete.md b/Documentation/DocuBlocks/JSF_foxx_controller_delete.md index 4158ff0860..3054b8fdb3 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_delete.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_delete.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_delete -/// -/// `Controller.delete(path, callback)` -/// -/// Defines a new route on `path` that handles requests from the HTTP verb `delete`. -/// This route can also be 'parameterized' like `/goose/:barn`. -/// In this case you can later get the value the user provided for `barn` -/// via the `params` function in the `request`. -/// The function defined in `callback` will be invoked whenever this type of -/// request is recieved. -/// `callback` get's two arguments `request` and `response`, see below for further -/// information about these objects. -/// -/// @EXAMPLES -/// -/// ```js -/// app.delete('/goose/barn', function (req, res) { -/// // Take this request and deal with it! -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.delete(path, callback)` + +Defines a new route on `path` that handles requests from the HTTP verb `delete`. +This route can also be 'parameterized' like `/goose/:barn`. +In this case you can later get the value the user provided for `barn` +via the `params` function in the `request`. +The function defined in `callback` will be invoked whenever this type of +request is recieved. +`callback` get's two arguments `request` and `response`, see below for further +information about these objects. + +@EXAMPLES + +```js +app.delete('/goose/barn', function (req, res) { + // Take this request and deal with it! +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_extend.md b/Documentation/DocuBlocks/JSF_foxx_controller_extend.md index 2196212f12..f9403e2360 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_extend.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_extend.md @@ -1,45 +1,44 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_extend -/// -/// `Controller.extend(extensions)` -/// -/// Extends all functions to define routes in this controller. -/// This allows to combine several route extensions with the invocation -/// of a single function. -/// This is especially useful if you use the same input parameter in several routes of -/// your controller and want to apply the same validation, documentation and error handling -/// for it. -/// -/// The `extensions` parameter is a JSON object with arbitrary keys. -/// Each key is used as the name of the function you want to define (you cannot overwrite -/// internal functions like `pathParam`) and the value is a function that will be invoked. -/// This function can get arbitrary many arguments and the `this` of the function is bound -/// to the route definition object (e.g. you can use `this.pathParam()`). -/// Your newly defined function is chainable similar to the internal functions. -/// -/// **Examples** -/// -/// Define a validator for a queryParameter, including documentation and errorResponses -/// in a single command: -/// -/// ```js -/// controller.extend({ -/// myParam: function (maxValue) { -/// this.queryParam("value", {type: joi.number().required()}); -/// this.onlyIf(function(req) { -/// var v = req.param("value"); -/// if (v > maxValue) { -/// throw new NumberTooLargeError(); -/// } -/// }); -/// this.errorResponse(NumberTooLargeError, 400, "The given value is too large"); -/// } -/// }); -/// -/// controller.get("/goose/barn", function(req, res) { -/// // Will only be invoked if the request has parameter value and it is less or equal 5. -/// }).myParam(5); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.extend(extensions)` + +Extends all functions to define routes in this controller. +This allows to combine several route extensions with the invocation +of a single function. +This is especially useful if you use the same input parameter in several routes of +your controller and want to apply the same validation, documentation and error handling +for it. + +The `extensions` parameter is a JSON object with arbitrary keys. +Each key is used as the name of the function you want to define (you cannot overwrite +internal functions like `pathParam`) and the value is a function that will be invoked. +This function can get arbitrary many arguments and the `this` of the function is bound +to the route definition object (e.g. you can use `this.pathParam()`). +Your newly defined function is chainable similar to the internal functions. + +**Examples** + +Define a validator for a queryParameter, including documentation and errorResponses +in a single command: + +```js +controller.extend({ + myParam: function (maxValue) { + this.queryParam("value", {type: joi.number().required()}); + this.onlyIf(function(req) { + var v = req.param("value"); + if (v > maxValue) { + throw new NumberTooLargeError(); + } + }); + this.errorResponse(NumberTooLargeError, 400, "The given value is too large"); + } +}); + +controller.get("/goose/barn", function(req, res) { + // Will only be invoked if the request has parameter value and it is less or equal 5. +}).myParam(5); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_get.md b/Documentation/DocuBlocks/JSF_foxx_controller_get.md index 1250b30c0d..48f988ff37 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_get.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_get.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_get -/// -/// `Controller.get(path, callback)` -/// -/// Defines a new route on `path` that handles requests from the HTTP verb `get`. -/// This route can also be 'parameterized' like `/goose/:barn`. -/// In this case you can later get the value the user provided for `barn` -/// via the `params` function in the `request`. -/// The function defined in `callback` will be invoked whenever this type of -/// request is recieved. -/// `callback` get's two arguments `request` and `response`, see below for further -/// information about these objects. -/// -/// @EXAMPLES -/// -/// ```js -/// app.get('/goose/barn', function (req, res) { -/// // Take this request and deal with it! -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.get(path, callback)` + +Defines a new route on `path` that handles requests from the HTTP verb `get`. +This route can also be 'parameterized' like `/goose/:barn`. +In this case you can later get the value the user provided for `barn` +via the `params` function in the `request`. +The function defined in `callback` will be invoked whenever this type of +request is recieved. +`callback` get's two arguments `request` and `response`, see below for further +information about these objects. + +@EXAMPLES + +```js +app.get('/goose/barn', function (req, res) { + // Take this request and deal with it! +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_head.md b/Documentation/DocuBlocks/JSF_foxx_controller_head.md index 4e18d62aa5..dfa4f742fb 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_head.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_head.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_head -/// -/// `Controller.head(path, callback)` -/// -/// Defines a new route on `path` that handles requests from the HTTP verb `head`. -/// This route can also be 'parameterized' like `/goose/:barn`. -/// In this case you can later get the value the user provided for `barn` -/// via the `params` function in the `request`. -/// The function defined in `callback` will be invoked whenever this type of -/// request is recieved. -/// `callback` get's two arguments `request` and `response`, see below for further -/// information about these objects. -/// -/// @EXAMPLES -/// -/// ```js -/// app.head('/goose/barn', function (req, res) { -/// // Take this request and deal with it! -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.head(path, callback)` + +Defines a new route on `path` that handles requests from the HTTP verb `head`. +This route can also be 'parameterized' like `/goose/:barn`. +In this case you can later get the value the user provided for `barn` +via the `params` function in the `request`. +The function defined in `callback` will be invoked whenever this type of +request is recieved. +`callback` get's two arguments `request` and `response`, see below for further +information about these objects. + +@EXAMPLES + +```js +app.head('/goose/barn', function (req, res) { + // Take this request and deal with it! +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_initializer.md b/Documentation/DocuBlocks/JSF_foxx_controller_initializer.md index 2ada067567..fe9502c8ee 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_initializer.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_initializer.md @@ -1,21 +1,20 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_initializer -/// -/// `new Controller(applicationContext, options)` -/// -/// This creates a new Controller. The first argument is the controller -/// context available in the variable *applicationContext*. The second one is an -/// options array with the following attributes: -/// -/// * *urlPrefix*: All routes you define within will be prefixed with it. -/// -/// @EXAMPLES -/// -/// ```js -/// app = new Controller(applicationContext, { -/// urlPrefix: "/meadow" -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`new Controller(applicationContext, options)` + +This creates a new Controller. The first argument is the controller +context available in the variable *applicationContext*. The second one is an +options array with the following attributes: + +* *urlPrefix*: All routes you define within will be prefixed with it. + +@EXAMPLES + +```js +app = new Controller(applicationContext, { + urlPrefix: "/meadow" +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_login.md b/Documentation/DocuBlocks/JSF_foxx_controller_login.md index 545f91f4e5..618d638620 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_login.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_login.md @@ -1,33 +1,32 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_login -/// -/// `FoxxController#login(path, opts)` -/// -/// Add a route for the login. You can provide further customizations via the -/// the options: -/// -/// * *usernameField* and *passwordField* can be used to adjust the expected attributes -/// in the *post* request. They default to *username* and *password*. -/// * *onSuccess* is a function that you can define to do something if the login was -/// successful. This includes sending a response to the user. This defaults to a -/// function that returns a JSON with *user* set to the identifier of the user and -/// * *key* set to the session key. -/// * *onError* is a function that you can define to do something if the login did not -/// work. This includes sending a response to the user. This defaults to a function -/// that sets the response to 401 and returns a JSON with *error* set to -/// "Username or Password was wrong". -/// -/// Both *onSuccess* and *onError* should take request and result as arguments. -/// -/// @EXAMPLES -/// -/// ```js -/// app.login('/login', { -/// onSuccess(req, res) { -/// res.json({"success": true}); -/// } -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxController#login(path, opts)` + +Add a route for the login. You can provide further customizations via the +the options: + +* *usernameField* and *passwordField* can be used to adjust the expected attributes + in the *post* request. They default to *username* and *password*. +* *onSuccess* is a function that you can define to do something if the login was + successful. This includes sending a response to the user. This defaults to a + function that returns a JSON with *user* set to the identifier of the user and +* *key* set to the session key. +* *onError* is a function that you can define to do something if the login did not + work. This includes sending a response to the user. This defaults to a function + that sets the response to 401 and returns a JSON with *error* set to + "Username or Password was wrong". + +Both *onSuccess* and *onError* should take request and result as arguments. + +@EXAMPLES + +```js +app.login('/login', { + onSuccess(req, res) { + res.json({"success": true}); + } +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_logout.md b/Documentation/DocuBlocks/JSF_foxx_controller_logout.md index 0ec9ee0081..20219de328 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_logout.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_logout.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_logout -/// -/// `FoxxController#logout(path, opts)` -/// -/// This works pretty similar to the logout function and adds a path to your -/// app for the logout functionality. You can customize it with a custom *onSuccess* -/// and *onError* function: -/// -/// * *onSuccess* is a function that you can define to do something if the logout was -/// successful. This includes sending a response to the user. This defaults to a -/// function that returns a JSON with *message* set to "logged out". -/// * *onError* is a function that you can define to do something if the logout did not -/// work. This includes sending a response to the user. This defaults to a function -/// that sets the response to 401 and returns a JSON with *error* set to -/// "No session was found". -/// -/// Both *onSuccess* and *onError* should take request and result as arguments. -/// -/// -/// @EXAMPLES -/// -/// ```js -/// app.logout('/logout', { -/// onSuccess(req, res) { -/// res.json({"message": "Bye, Bye"}); -/// } -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxController#logout(path, opts)` + +This works pretty similar to the logout function and adds a path to your +app for the logout functionality. You can customize it with a custom *onSuccess* +and *onError* function: + +* *onSuccess* is a function that you can define to do something if the logout was + successful. This includes sending a response to the user. This defaults to a + function that returns a JSON with *message* set to "logged out". +* *onError* is a function that you can define to do something if the logout did not + work. This includes sending a response to the user. This defaults to a function + that sets the response to 401 and returns a JSON with *error* set to + "No session was found". + +Both *onSuccess* and *onError* should take request and result as arguments. + + +@EXAMPLES + +```js +app.logout('/logout', { + onSuccess(req, res) { + res.json({"message": "Bye, Bye"}); + } +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_patch.md b/Documentation/DocuBlocks/JSF_foxx_controller_patch.md index 4003950955..24abe5fec6 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_patch.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_patch.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_patch -/// -/// `Controller.patch(path, callback)` -/// -/// Defines a new route on `path` that handles requests from the HTTP verb `patch`. -/// This route can also be 'parameterized' like `/goose/:barn`. -/// In this case you can later get the value the user provided for `barn` -/// via the `params` function in the `request`. -/// The function defined in `callback` will be invoked whenever this type of -/// request is recieved. -/// `callback` get's two arguments `request` and `response`, see below for further -/// information about these objects. -/// -/// @EXAMPLES -/// -/// ```js -/// app.patch('/goose/barn', function (req, res) { -/// // Take this request and deal with it! -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.patch(path, callback)` + +Defines a new route on `path` that handles requests from the HTTP verb `patch`. +This route can also be 'parameterized' like `/goose/:barn`. +In this case you can later get the value the user provided for `barn` +via the `params` function in the `request`. +The function defined in `callback` will be invoked whenever this type of +request is recieved. +`callback` get's two arguments `request` and `response`, see below for further +information about these objects. + +@EXAMPLES + +```js +app.patch('/goose/barn', function (req, res) { + // Take this request and deal with it! +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_post.md b/Documentation/DocuBlocks/JSF_foxx_controller_post.md index 77dbba6033..5300469250 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_post.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_post.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_post -/// -/// `Controller.post(path, callback)` -/// -/// Defines a new route on `path` that handles requests from the HTTP verb `post`. -/// This route can also be 'parameterized' like `/goose/:barn`. -/// In this case you can later get the value the user provided for `barn` -/// via the `params` function in the `request`. -/// The function defined in `callback` will be invoked whenever this type of -/// request is recieved. -/// `callback` get's two arguments `request` and `response`, see below for further -/// information about these objects. -/// -/// @EXAMPLES -/// -/// ```js -/// app.post('/goose/barn', function (req, res) { -/// // Take this request and deal with it! -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.post(path, callback)` + +Defines a new route on `path` that handles requests from the HTTP verb `post`. +This route can also be 'parameterized' like `/goose/:barn`. +In this case you can later get the value the user provided for `barn` +via the `params` function in the `request`. +The function defined in `callback` will be invoked whenever this type of +request is recieved. +`callback` get's two arguments `request` and `response`, see below for further +information about these objects. + +@EXAMPLES + +```js +app.post('/goose/barn', function (req, res) { + // Take this request and deal with it! +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_put.md b/Documentation/DocuBlocks/JSF_foxx_controller_put.md index ae6179c9db..325b46f62b 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_put.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_put.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_put -/// -/// `Controller.put(path, callback)` -/// -/// Defines a new route on `path` that handles requests from the HTTP verb `put`. -/// This route can also be 'parameterized' like `/goose/:barn`. -/// In this case you can later get the value the user provided for `barn` -/// via the `params` function in the `request`. -/// The function defined in `callback` will be invoked whenever this type of -/// request is recieved. -/// `callback` get's two arguments `request` and `response`, see below for further -/// information about these objects. -/// -/// @EXAMPLES -/// -/// ```js -/// app.put('/goose/barn', function (req, res) { -/// // Take this request and deal with it! -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`Controller.put(path, callback)` + +Defines a new route on `path` that handles requests from the HTTP verb `put`. +This route can also be 'parameterized' like `/goose/:barn`. +In this case you can later get the value the user provided for `barn` +via the `params` function in the `request`. +The function defined in `callback` will be invoked whenever this type of +request is recieved. +`callback` get's two arguments `request` and `response`, see below for further +information about these objects. + +@EXAMPLES + +```js +app.put('/goose/barn', function (req, res) { + // Take this request and deal with it! +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_controller_register.md b/Documentation/DocuBlocks/JSF_foxx_controller_register.md index 29e8a6c823..643c277a83 100644 --- a/Documentation/DocuBlocks/JSF_foxx_controller_register.md +++ b/Documentation/DocuBlocks/JSF_foxx_controller_register.md @@ -1,43 +1,42 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_controller_register -/// -/// `FoxxController#register(path, opts)` -/// -/// This works pretty similar to the logout function and adds a path to your -/// app for the register functionality. You can customize it with a custom *onSuccess* -/// and *onError* function: -/// -/// * *onSuccess* is a function that you can define to do something if the registration was -/// successful. This includes sending a response to the user. This defaults to a -/// function that returns a JSON with *user* set to the created user document. -/// * *onError* is a function that you can define to do something if the registration did not -/// work. This includes sending a response to the user. This defaults to a function -/// that sets the response to 401 and returns a JSON with *error* set to -/// "Registration failed". -/// -/// Both *onSuccess* and *onError* should take request and result as arguments. -/// -/// You can also set the fields containing the username and password via *usernameField* -/// (defaults to *username*) and *passwordField* (defaults to *password*). -/// If you want to accept additional attributes for the user document, use the option -/// *acceptedAttributes* and set it to an array containing strings with the names of -/// the additional attributes you want to accept. All other attributes in the request -/// will be ignored. -/// -/// If you want default attributes for the accepted attributes or set additional fields -/// (for example *admin*) use the option *defaultAttributes* which should be a hash -/// mapping attribute names to default values. -/// -/// @EXAMPLES -/// -/// ```js -/// app.register('/logout', { -/// acceptedAttributes: ['name'], -/// defaultAttributes: { -/// admin: false -/// } -/// }); -/// ``` -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxController#register(path, opts)` + +This works pretty similar to the logout function and adds a path to your +app for the register functionality. You can customize it with a custom *onSuccess* +and *onError* function: + +* *onSuccess* is a function that you can define to do something if the registration was + successful. This includes sending a response to the user. This defaults to a + function that returns a JSON with *user* set to the created user document. +* *onError* is a function that you can define to do something if the registration did not + work. This includes sending a response to the user. This defaults to a function + that sets the response to 401 and returns a JSON with *error* set to + "Registration failed". + +Both *onSuccess* and *onError* should take request and result as arguments. + +You can also set the fields containing the username and password via *usernameField* +(defaults to *username*) and *passwordField* (defaults to *password*). +If you want to accept additional attributes for the user document, use the option +*acceptedAttributes* and set it to an array containing strings with the names of +the additional attributes you want to accept. All other attributes in the request +will be ignored. + +If you want default attributes for the accepted attributes or set additional fields +(for example *admin*) use the option *defaultAttributes* which should be a hash +mapping attribute names to default values. + +@EXAMPLES + +```js +app.register('/logout', { + acceptedAttributes: ['name'], + defaultAttributes: { + admin: false + } +}); +``` + + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_attributes.md b/Documentation/DocuBlocks/JSF_foxx_model_attributes.md index 2da1bf11fa..7a4ba7c1f2 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_attributes.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_attributes.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_attributes -/// -/// `model.attributes` -/// -/// The *attributes* property is the internal hash containing the model's state. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`model.attributes` + +The *attributes* property is the internal hash containing the model's state. + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_errors.md b/Documentation/DocuBlocks/JSF_foxx_model_errors.md index c6dfc1491e..378399f5ed 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_errors.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_errors.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_errors -/// -/// `model.errors` -/// -/// The *errors* property maps the names of any invalid attributes to their -/// corresponding validation error. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`model.errors` + +The *errors* property maps the names of any invalid attributes to their +corresponding validation error. + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_extend.md b/Documentation/DocuBlocks/JSF_foxx_model_extend.md index df2e8710b4..b066221976 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_extend.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_extend.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_extend -/// -/// `FoxxModel#extend(instanceProperties, classProperties)` -/// -/// Extend the Model prototype to add or overwrite methods. -/// The first object contains the properties to be defined on the instance, -/// the second object those to be defined on the prototype. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxModel#extend(instanceProperties, classProperties)` + +Extend the Model prototype to add or overwrite methods. +The first object contains the properties to be defined on the instance, +the second object those to be defined on the prototype. + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_forClient.md b/Documentation/DocuBlocks/JSF_foxx_model_forClient.md index 1c77b4e98d..88f81ccb77 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_forClient.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_forClient.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_forClient -/// -/// `FoxxModel#forClient()` -/// -/// Return a copy of the model which you can send to the client. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxModel#forClient()` + +Return a copy of the model which you can send to the client. + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_forDB.md b/Documentation/DocuBlocks/JSF_foxx_model_forDB.md index e73b37b5ce..9fa87c546a 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_forDB.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_forDB.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_forDB -/// -/// `FoxxModel#forDB()` -/// -/// Return a copy of the model which can be saved into ArangoDB -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxModel#forDB()` + +Return a copy of the model which can be saved into ArangoDB + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_get.md b/Documentation/DocuBlocks/JSF_foxx_model_get.md index fd0673c488..178fcba8da 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_get.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_get.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_get -/// -/// `FoxxModel#get(name)` -/// -/// Get the value of an attribute -/// -/// @EXAMPLES -/// -/// ```js -/// instance = new Model({ -/// a: 1 -/// }); -/// -/// instance.get("a"); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxModel#get(name)` + +Get the value of an attribute + +@EXAMPLES + +```js +instance = new Model({ + a: 1 +}); + +instance.get("a"); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_has.md b/Documentation/DocuBlocks/JSF_foxx_model_has.md index d43ce0b30d..017bb49b0b 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_has.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_has.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_has -/// -/// `FoxxModel#has(name)` -/// -/// Returns true if the attribute is set to a non-null or non-undefined value. -/// -/// @EXAMPLES -/// -/// ```js -/// instance = new Model({ -/// a: 1 -/// }); -/// -/// instance.has("a"); //=> true -/// instance.has("b"); //=> false -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxModel#has(name)` + +Returns true if the attribute is set to a non-null or non-undefined value. + +@EXAMPLES + +```js +instance = new Model({ + a: 1 +}); + +instance.has("a"); //=> true +instance.has("b"); //=> false +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_initializer.md b/Documentation/DocuBlocks/JSF_foxx_model_initializer.md index 270c2f8049..09656452f4 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_initializer.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_initializer.md @@ -1,16 +1,15 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_initializer -/// -/// `new FoxxModel(data)` -/// -/// If you initialize a model, you can give it initial *data* as an object. -/// -/// @EXAMPLES -/// -/// ```js -/// instance = new Model({ -/// a: 1 -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`new FoxxModel(data)` + +If you initialize a model, you can give it initial *data* as an object. + +@EXAMPLES + +```js +instance = new Model({ + a: 1 +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_isvalid.md b/Documentation/DocuBlocks/JSF_foxx_model_isvalid.md index 3c10bdf804..3e7bbc3fdd 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_isvalid.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_isvalid.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_isvalid -/// -/// `model.isValid` -/// -/// The *isValid* flag indicates whether the model's state is currently valid. -/// If the model does not have a schema, it will always be considered valid. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`model.isValid` + +The *isValid* flag indicates whether the model's state is currently valid. +If the model does not have a schema, it will always be considered valid. + diff --git a/Documentation/DocuBlocks/JSF_foxx_model_set.md b/Documentation/DocuBlocks/JSF_foxx_model_set.md index e99929221a..83018dc85c 100644 --- a/Documentation/DocuBlocks/JSF_foxx_model_set.md +++ b/Documentation/DocuBlocks/JSF_foxx_model_set.md @@ -1,21 +1,20 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_model_set -/// -/// `FoxxModel#set(name, value)` -/// -/// Set the value of an attribute or multiple attributes at once -/// -/// @EXAMPLES -/// -/// ```js -/// instance = new Model({ -/// a: 1 -/// }); -/// -/// instance.set("a", 2); -/// instance.set({ -/// b: 2 -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`FoxxModel#set(name, value)` + +Set the value of an attribute or multiple attributes at once + +@EXAMPLES + +```js +instance = new Model({ + a: 1 +}); + +instance.set("a", 2); +instance.set({ + b: 2 +}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_all.md b/Documentation/DocuBlocks/JSF_foxx_repository_all.md index ffefe88fb7..42b6c38e5f 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_all.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_all.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_all -/// `FoxxRepository#all()` -/// -/// Returns an array of models that matches the given example. You can provide -/// both a skip and a limit value. -/// -/// **Warning:** ArangoDB doesn't guarantee a specific order in this case, to make -/// this really useful we have to explicitly provide something to order by. -/// -/// *Parameter* -/// -/// * *options* (optional): -/// * *skip* (optional): skips the first given number of models. -/// * *limit* (optional): only returns at most the given number of models. -/// -/// @EXAMPLES -/// -/// ```javascript -/// var myModel = repository.all({ skip: 4, limit: 2 }); -/// myModel[0].get('name'); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#all()` + +Returns an array of models that matches the given example. You can provide +both a skip and a limit value. + +**Warning:** ArangoDB doesn't guarantee a specific order in this case, to make +this really useful we have to explicitly provide something to order by. + +*Parameter* + +* *options* (optional): + * *skip* (optional): skips the first given number of models. + * *limit* (optional): only returns at most the given number of models. + +@EXAMPLES + +```javascript +var myModel = repository.all({ skip: 4, limit: 2 }); +myModel[0].get('name'); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_any.md b/Documentation/DocuBlocks/JSF_foxx_repository_any.md index 67bbbcfca4..a0ae861490 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_any.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_any.md @@ -1,13 +1,12 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_any -/// `FoxxRepository#any()` -/// -/// Returns a random model from this repository (or null if there is none). -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.any(); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#any()` + +Returns a random model from this repository (or null if there is none). + +@EXAMPLES + +```javascript +repository.any(); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_byExample.md b/Documentation/DocuBlocks/JSF_foxx_repository_byExample.md index ee87b561ec..467443a5b5 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_byExample.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_byExample.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_byExample -/// `FoxxRepository#byExample(example)` -/// -/// Returns an array of models for the given ID. -/// -/// @EXAMPLES -/// -/// ```javascript -/// var myModel = repository.byExample({ amazing: true }); -/// myModel[0].get('name'); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#byExample(example)` + +Returns an array of models for the given ID. + +@EXAMPLES + +```javascript +var myModel = repository.byExample({ amazing: true }); +myModel[0].get('name'); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_byId.md b/Documentation/DocuBlocks/JSF_foxx_repository_byId.md index 86184aced8..9510192228 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_byId.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_byId.md @@ -1,17 +1,16 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_byId -/// `FoxxRepository#byId(id)` -/// -/// Returns the model for the given ID ("collection/key") or "key". -/// -/// @EXAMPLES -/// -/// ```javascript -/// var byIdModel = repository.byId('test/12411'); -/// byIdModel.get('name'); -/// -/// var byKeyModel = repository.byId('12412'); -/// byKeyModel.get('name'); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#byId(id)` + +Returns the model for the given ID ("collection/key") or "key". + +@EXAMPLES + +```javascript +var byIdModel = repository.byId('test/12411'); +byIdModel.get('name'); + +var byKeyModel = repository.byId('12412'); +byKeyModel.get('name'); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_collection.md b/Documentation/DocuBlocks/JSF_foxx_repository_collection.md index b18c4e97ef..f8d5fa50d2 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_collection.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_collection.md @@ -1,5 +1,4 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_collection -/// The wrapped ArangoDB collection object. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The wrapped ArangoDB collection object. + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_count.md b/Documentation/DocuBlocks/JSF_foxx_repository_count.md index 3daeeaf760..d8377238aa 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_count.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_count.md @@ -1,13 +1,12 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_count -/// `FoxxRepository#count()` -/// -/// Returns the number of entries in this collection. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.count(); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#count()` + +Returns the number of entries in this collection. + +@EXAMPLES + +```javascript +repository.count(); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_exists.md b/Documentation/DocuBlocks/JSF_foxx_repository_exists.md index 3209007759..d1191ea8c5 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_exists.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_exists.md @@ -1,13 +1,12 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_exists -/// `FoxxRepository#exists(id)` -/// -/// Checks whether a model with the given ID or key exists. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.exists(model.get('_id')); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#exists(id)` + +Checks whether a model with the given ID or key exists. + +@EXAMPLES + +```javascript +repository.exists(model.get('_id')); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_firstExample.md b/Documentation/DocuBlocks/JSF_foxx_repository_firstExample.md index 338aa1f2c5..26213331d2 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_firstExample.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_firstExample.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_firstExample -/// `FoxxRepository#firstExample(example)` -/// -/// Returns the first model that matches the given example. -/// -/// @EXAMPLES -/// -/// ```javascript -/// var myModel = repository.firstExample({ amazing: true }); -/// myModel.get('name'); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#firstExample(example)` + +Returns the first model that matches the given example. + +@EXAMPLES + +```javascript +var myModel = repository.firstExample({ amazing: true }); +myModel.get('name'); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_fulltext.md b/Documentation/DocuBlocks/JSF_foxx_repository_fulltext.md index 9fd01e6d2b..0b37defe70 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_fulltext.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_fulltext.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_fulltext -/// `FoxxRepository#fulltext(attribute, query, options)` -/// -/// Returns all models whose attribute *attribute* matches the search query -/// *query*. -/// -/// In order to use the fulltext method, a fulltext index must be defined on -/// the repository. If multiple fulltext indexes are defined on the repository -/// for the attribute, the most capable one will be selected. -/// If no fulltext index is present, the method will not be available. -/// -/// *Parameter* -/// -/// * *attribute*: model attribute to perform a search on. -/// * *query*: query to match the attribute against. -/// * *options* (optional): -/// * *limit* (optional): number of models to return. Defaults to all. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.fulltext("text", "word", {limit: 1}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#fulltext(attribute, query, options)` + +Returns all models whose attribute *attribute* matches the search query +*query*. + +In order to use the fulltext method, a fulltext index must be defined on +the repository. If multiple fulltext indexes are defined on the repository +for the attribute, the most capable one will be selected. +If no fulltext index is present, the method will not be available. + +*Parameter* + +* *attribute*: model attribute to perform a search on. +* *query*: query to match the attribute against. +* *options* (optional): + * *limit* (optional): number of models to return. Defaults to all. + +@EXAMPLES + +```javascript +repository.fulltext("text", "word", {limit: 1}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_initializer.md b/Documentation/DocuBlocks/JSF_foxx_repository_initializer.md index f423f487c6..c32e7296cf 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_initializer.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_initializer.md @@ -1,46 +1,45 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_initializer -/// `new FoxxRepository(collection, opts)` -/// -/// Create a new instance of Repository. -/// -/// A Foxx Repository is always initialized with a collection object. You can get -/// your collection object by asking your Foxx.Controller for it: the -/// *collection* method takes the name of the collection (and will prepend -/// the prefix of your application). It also takes two optional arguments: -/// -/// 1. Model: The prototype of a model. If you do not provide it, it will default -/// to Foxx.Model -/// 2. Prefix: You can provide the prefix of the application if you need it in -/// your Repository (for some AQL queries probably) -/// -/// If the Model has any static methods named after the lifecycle events, they -/// will automatically be registered as listeners to the events emitted by this -/// repository. -/// -/// **Examples** -/// -/// ```js -/// instance = new Repository(appContext.collection("my_collection")); -/// // or: -/// instance = new Repository(appContext.collection("my_collection"), { -/// model: MyModelPrototype -/// }); -/// ``` -/// -/// Example with listeners: -/// -/// ```js -/// var ValidatedModel = Model.extend({ -/// schema: {...} -/// }, { -/// beforeSave(modelInstance) { -/// if (!modelInstance.valid) { -/// throw new Error('Refusing to save: model is not valid!'); -/// } -/// } -/// }); -/// instance = new Repository(collection, {model: ValidatedModel}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`new FoxxRepository(collection, opts)` + +Create a new instance of Repository. + +A Foxx Repository is always initialized with a collection object. You can get +your collection object by asking your Foxx.Controller for it: the +*collection* method takes the name of the collection (and will prepend +the prefix of your application). It also takes two optional arguments: + +1. Model: The prototype of a model. If you do not provide it, it will default +to Foxx.Model +2. Prefix: You can provide the prefix of the application if you need it in +your Repository (for some AQL queries probably) + +If the Model has any static methods named after the lifecycle events, they +will automatically be registered as listeners to the events emitted by this +repository. + +**Examples** + +```js +instance = new Repository(appContext.collection("my_collection")); + or: +instance = new Repository(appContext.collection("my_collection"), { + model: MyModelPrototype +}); +``` + +Example with listeners: + +```js +var ValidatedModel = Model.extend({ + schema: {...} +}, { + beforeSave(modelInstance) { + if (!modelInstance.valid) { + throw new Error('Refusing to save: model is not valid!'); + } + } +}); +instance = new Repository(collection, {model: ValidatedModel}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_model.md b/Documentation/DocuBlocks/JSF_foxx_repository_model.md index 4585b3a740..9e39367121 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_model.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_model.md @@ -1,5 +1,4 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_model -/// The model of this repository. Formerly called "modelPrototype". -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The model of this repository. Formerly called "modelPrototype". + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_modelSchema.md b/Documentation/DocuBlocks/JSF_foxx_repository_modelSchema.md index ffd4810e2d..4494e27d1f 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_modelSchema.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_modelSchema.md @@ -1,5 +1,4 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_modelSchema -/// The schema of this repository's model. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The schema of this repository's model. + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_near.md b/Documentation/DocuBlocks/JSF_foxx_repository_near.md index 4ab89f8629..409eeeefbb 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_near.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_near.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_near -/// `FoxxRepository#near(latitude, longitude, options)` -/// -/// Finds models near the coordinate *(latitude, longitude)*. The returned -/// list is sorted by distance with the nearest model coming first. -/// -/// For geo queries it is required that a geo index is present in the -/// repository. If no geo index is present, the methods will not be available. -/// -/// *Parameter* -/// -/// * *latitude*: latitude of the coordinate. -/// * *longitude*: longitude of the coordinate. -/// * *options* (optional): -/// * *geo* (optional): name of the specific geo index to use. -/// * *distance* (optional): If set to a truthy value, the returned models -/// will have an additional property containing the distance between the -/// given coordinate and the model. If the value is a string, that value -/// will be used as the property name, otherwise the name defaults to *"distance"*. -/// * *limit* (optional): number of models to return. Defaults to *100*. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.near(0, 0, {geo: "home", distance: true, limit: 10}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#near(latitude, longitude, options)` + +Finds models near the coordinate *(latitude, longitude)*. The returned +list is sorted by distance with the nearest model coming first. + +For geo queries it is required that a geo index is present in the +repository. If no geo index is present, the methods will not be available. + +*Parameter* + +* *latitude*: latitude of the coordinate. +* *longitude*: longitude of the coordinate. +* *options* (optional): + * *geo* (optional): name of the specific geo index to use. + * *distance* (optional): If set to a truthy value, the returned models + will have an additional property containing the distance between the + given coordinate and the model. If the value is a string, that value + will be used as the property name, otherwise the name defaults to *"distance"*. + * *limit* (optional): number of models to return. Defaults to *100*. + +@EXAMPLES + +```javascript +repository.near(0, 0, {geo: "home", distance: true, limit: 10}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_prefix.md b/Documentation/DocuBlocks/JSF_foxx_repository_prefix.md index e4fd239bed..bcbabafb08 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_prefix.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_prefix.md @@ -1,6 +1,5 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_prefix -/// The prefix of the application. This is useful if you want to construct AQL -/// queries for example. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +The prefix of the application. This is useful if you want to construct AQL +queries for example. + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_range.md b/Documentation/DocuBlocks/JSF_foxx_repository_range.md index 1e9fa4395a..900462b6bd 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_range.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_range.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_range -/// `FoxxRepository#range(attribute, left, right)` -/// -/// Returns all models in the repository such that the attribute is greater -/// than or equal to *left* and strictly less than *right*. -/// -/// For range queries it is required that a skiplist index is present for the -/// queried attribute. If no skiplist index is present on the attribute, the -/// method will not be available. -/// -/// *Parameter* -/// -/// * *attribute*: attribute to query. -/// * *left*: lower bound of the value range (inclusive). -/// * *right*: upper bound of the value range (exclusive). -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.range("age", 10, 13); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#range(attribute, left, right)` + +Returns all models in the repository such that the attribute is greater +than or equal to *left* and strictly less than *right*. + +For range queries it is required that a skiplist index is present for the +queried attribute. If no skiplist index is present on the attribute, the +method will not be available. + +*Parameter* + +* *attribute*: attribute to query. +* *left*: lower bound of the value range (inclusive). +* *right*: upper bound of the value range (exclusive). + +@EXAMPLES + +```javascript +repository.range("age", 10, 13); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_remove.md b/Documentation/DocuBlocks/JSF_foxx_repository_remove.md index f51b2f7349..ceddb80817 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_remove.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_remove.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_remove -/// `FoxxRepository#remove(model)` -/// -/// Remove the model from the repository. -/// Expects a model. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.remove(myModel); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#remove(model)` + +Remove the model from the repository. +Expects a model. + +@EXAMPLES + +```javascript +repository.remove(myModel); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_removeByExample.md b/Documentation/DocuBlocks/JSF_foxx_repository_removeByExample.md index 176839cf86..209c0eabc9 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_removeByExample.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_removeByExample.md @@ -1,13 +1,12 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_removeByExample -/// `FoxxRepository#removeByExample(example)` -/// -/// Find all documents that fit this example and remove them. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.removeByExample({ toBeDeleted: true }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#removeByExample(example)` + +Find all documents that fit this example and remove them. + +@EXAMPLES + +```javascript +repository.removeByExample({ toBeDeleted: true }); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_removeById.md b/Documentation/DocuBlocks/JSF_foxx_repository_removeById.md index b13a53fad0..63b1ed6320 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_removeById.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_removeById.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_removeById -/// `FoxxRepository#removeById(id)` -/// -/// Remove the document with the given ID ("collection/key") or "key". -/// Expects an ID or key of an existing document. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.removeById('test/12121'); -/// repository.removeById('12122'); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#removeById(id)` + +Remove the document with the given ID ("collection/key") or "key". +Expects an ID or key of an existing document. + +@EXAMPLES + +```javascript +repository.removeById('test/12121'); +repository.removeById('12122'); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_replace.md b/Documentation/DocuBlocks/JSF_foxx_repository_replace.md index 8ee41bee20..f7903abe29 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_replace.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_replace.md @@ -1,16 +1,15 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_replace -/// `FoxxRepository#replace(model)` -/// -/// Find the model in the database by its *_id* and replace it with this version. -/// Expects a model. Sets the revision of the model. -/// Returns the model. -/// -/// @EXAMPLES -/// -/// ```javascript -/// myModel.set('name', 'Jan Steemann'); -/// repository.replace(myModel); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#replace(model)` + +Find the model in the database by its *_id* and replace it with this version. +Expects a model. Sets the revision of the model. +Returns the model. + +@EXAMPLES + +```javascript +myModel.set('name', 'Jan Steemann'); +repository.replace(myModel); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_replaceByExample.md b/Documentation/DocuBlocks/JSF_foxx_repository_replaceByExample.md index 578990adc4..8c7b64d505 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_replaceByExample.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_replaceByExample.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_replaceByExample -/// `FoxxRepository#replaceByExample(example, object)` -/// -/// Find every matching item by example and replace it with the attributes in -/// the provided object. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.replaceByExample({ replaceMe: true }, myNewModel); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#replaceByExample(example, object)` + +Find every matching item by example and replace it with the attributes in +the provided object. + +@EXAMPLES + +```javascript +repository.replaceByExample({ replaceMe: true }, myNewModel); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_replaceById.md b/Documentation/DocuBlocks/JSF_foxx_repository_replaceById.md index b8c09f76d6..3bdf78a375 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_replaceById.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_replaceById.md @@ -1,17 +1,16 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_replaceById -/// `FoxxRepository#replaceById(id, object)` -/// -/// Find the item in the database by the given ID ("collection/key") or "key" -/// and replace it with the given object's attributes. -/// -/// If the object is a model, updates the model's revision and returns the model. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.replaceById('test/123345', myNewModel); -/// repository.replaceById('123346', myNewModel); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#replaceById(id, object)` + +Find the item in the database by the given ID ("collection/key") or "key" +and replace it with the given object's attributes. + +If the object is a model, updates the model's revision and returns the model. + +@EXAMPLES + +```javascript +repository.replaceById('test/123345', myNewModel); +repository.replaceById('123346', myNewModel); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_save.md b/Documentation/DocuBlocks/JSF_foxx_repository_save.md index f2214a9b9d..aa2bbd132e 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_save.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_save.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_save -/// `FoxxRepository#save(model)` -/// -/// Saves a model into the database. -/// Expects a model. Will set the ID and Rev on the model. -/// Returns the model. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.save(my_model); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#save(model)` + +Saves a model into the database. +Expects a model. Will set the ID and Rev on the model. +Returns the model. + +@EXAMPLES + +```javascript +repository.save(my_model); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_update.md b/Documentation/DocuBlocks/JSF_foxx_repository_update.md index f90f448ec6..6e95fcd8cc 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_update.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_update.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_update -/// `FoxxRepository#update(model, object)` -/// -/// Find the model in the database by its *_id* and update it with the given object. -/// Expects a model. Sets the revision of the model and updates its properties. -/// Returns the model. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.update(myModel, {name: 'Jan Steeman'}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#update(model, object)` + +Find the model in the database by its *_id* and update it with the given object. +Expects a model. Sets the revision of the model and updates its properties. +Returns the model. + +@EXAMPLES + +```javascript +repository.update(myModel, {name: 'Jan Steeman'}); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_updateByExample.md b/Documentation/DocuBlocks/JSF_foxx_repository_updateByExample.md index 1857b5c8c5..3680216b60 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_updateByExample.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_updateByExample.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_updateByExample -/// `FoxxRepository#updateByExample(example, object)` -/// -/// Find every matching item by example and update it with the attributes in -/// the provided object. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.updateByExample({ findMe: true }, { newAttribute: 'awesome' }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#updateByExample(example, object)` + +Find every matching item by example and update it with the attributes in +the provided object. + +@EXAMPLES + +```javascript +repository.updateByExample({ findMe: true }, { newAttribute: 'awesome' }); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_updateById.md b/Documentation/DocuBlocks/JSF_foxx_repository_updateById.md index bc4151ac24..d2360c1c72 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_updateById.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_updateById.md @@ -1,17 +1,16 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_updateById -/// `FoxxRepository#updateById(id, object)` -/// -/// Find an item by ID ("collection/key") or "key" and update it with the -/// attributes in the provided object. -/// -/// If the object is a model, updates the model's revision and returns the model. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.updateById('test/12131', { newAttribute: 'awesome' }); -/// repository.updateById('12132', { newAttribute: 'awesomer' }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#updateById(id, object)` + +Find an item by ID ("collection/key") or "key" and update it with the +attributes in the provided object. + +If the object is a model, updates the model's revision and returns the model. + +@EXAMPLES + +```javascript +repository.updateById('test/12131', { newAttribute: 'awesome' }); +repository.updateById('12132', { newAttribute: 'awesomer' }); +``` + diff --git a/Documentation/DocuBlocks/JSF_foxx_repository_within.md b/Documentation/DocuBlocks/JSF_foxx_repository_within.md index 997f120c65..7e8522d509 100644 --- a/Documentation/DocuBlocks/JSF_foxx_repository_within.md +++ b/Documentation/DocuBlocks/JSF_foxx_repository_within.md @@ -1,31 +1,30 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_foxx_repository_within -/// `FoxxRepository#within(latitude, longitude, radius, options)` -/// -/// Finds models within the distance *radius* from the coordinate -/// *(latitude, longitude)*. The returned list is sorted by distance with the -/// nearest model coming first. -/// -/// For geo queries it is required that a geo index is present in the -/// repository. If no geo index is present, the methods will not be available. -/// -/// *Parameter* -/// -/// * *latitude*: latitude of the coordinate. -/// * *longitude*: longitude of the coordinate. -/// * *radius*: maximum distance from the coordinate. -/// * *options* (optional): -/// * *geo* (optional): name of the specific geo index to use. -/// * *distance* (optional): If set to a truthy value, the returned models -/// will have an additional property containing the distance between the -/// given coordinate and the model. If the value is a string, that value -/// will be used as the property name, otherwise the name defaults to *"distance"*. -/// * *limit* (optional): number of models to return. Defaults to *100*. -/// -/// @EXAMPLES -/// -/// ```javascript -/// repository.within(0, 0, 2000 * 1000, {geo: "home", distance: true, limit: 10}); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +`FoxxRepository#within(latitude, longitude, radius, options)` + +Finds models within the distance *radius* from the coordinate +*(latitude, longitude)*. The returned list is sorted by distance with the +nearest model coming first. + +For geo queries it is required that a geo index is present in the +repository. If no geo index is present, the methods will not be available. + +*Parameter* + +* *latitude*: latitude of the coordinate. +* *longitude*: longitude of the coordinate. +* *radius*: maximum distance from the coordinate. +* *options* (optional): + * *geo* (optional): name of the specific geo index to use. + * *distance* (optional): If set to a truthy value, the returned models + will have an additional property containing the distance between the + given coordinate and the model. If the value is a string, that value + will be used as the property name, otherwise the name defaults to *"distance"*. + * *limit* (optional): number of models to return. Defaults to *100*. + +@EXAMPLES + +```javascript +repository.within(0, 0, 2000 * 1000, {geo: "home", distance: true, limit: 10}); +``` + diff --git a/Documentation/DocuBlocks/JSF_general_graph__addVertexCollection.md b/Documentation/DocuBlocks/JSF_general_graph__addVertexCollection.md index ecf0593d30..56f52fcb7a 100644 --- a/Documentation/DocuBlocks/JSF_general_graph__addVertexCollection.md +++ b/Documentation/DocuBlocks/JSF_general_graph__addVertexCollection.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph__addVertexCollection -/// @brief Add a vertex collection to the graph -/// -/// `graph._addVertexCollection(vertexCollectionName, createCollection)` -/// -/// 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 -/// definition of the graph, an error will be thrown. -/// -/// @PARAMS -/// -/// @PARAM{vertexCollectionName, string, required} -/// Name of vertex collection. -/// -/// @PARAM{createCollection, boolean, optional} -/// If true the collection will be created if it does not exist. Default: true. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph__addVertexCollection} -/// var graph_module = require("@arangodb/general-graph"); -/// ~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} -/// var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); -/// var graph = graph_module._create("myGraph", [ed1]); -/// graph._addVertexCollection("myVC3", true); -/// ~ db._drop("myVC3"); -/// ~ var blub = graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Add a vertex collection to the graph + +`graph._addVertexCollection(vertexCollectionName, createCollection)` + +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 +definition of the graph, an error will be thrown. + +@PARAMS + +@PARAM{vertexCollectionName, string, required} +Name of vertex collection. + +@PARAM{createCollection, boolean, optional} +If true the collection will be created if it does not exist. Default: true. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph__addVertexCollection} + var graph_module = require("@arangodb/general-graph"); +~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} + var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); + var graph = graph_module._create("myGraph", [ed1]); + graph._addVertexCollection("myVC3", true); +~ db._drop("myVC3"); +~ var blub = graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph__deleteEdgeDefinition.md b/Documentation/DocuBlocks/JSF_general_graph__deleteEdgeDefinition.md index f10ba94434..ddd7bfb1be 100644 --- a/Documentation/DocuBlocks/JSF_general_graph__deleteEdgeDefinition.md +++ b/Documentation/DocuBlocks/JSF_general_graph__deleteEdgeDefinition.md @@ -1,49 +1,48 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph__deleteEdgeDefinition -/// @brief Delete one relation definition -/// -/// `graph_module._deleteEdgeDefinition(edgeCollectionName, dropCollection)` -/// -/// Deletes a relation definition defined by the edge collection of a graph. If the -/// collections defined in the edge definition (collection, from, to) are not used -/// in another edge definition of the graph, they will be moved to the orphanage. -/// -/// @PARAMS -/// -/// @PARAM{edgeCollectionName, string, required} -/// Name of edge collection in the relation definition. -/// @PARAM{dropCollection, boolean, optional} -/// Define if the edge collection should be dropped. Default false. -/// -/// @EXAMPLES -/// -/// Remove an edge definition but keep the edge collection: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph__deleteEdgeDefinition} -/// var graph_module = require("@arangodb/general-graph") -/// ~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} -/// var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); -/// var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]); -/// var graph = graph_module._create("myGraph", [ed1, ed2]); -/// graph._deleteEdgeDefinition("myEC1"); -/// db._collection("myEC1"); -/// ~ db._drop("myEC1"); -/// ~ var blub = graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Remove an edge definition and drop the edge collection: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph__deleteEdgeDefinitionWithDrop} -/// var graph_module = require("@arangodb/general-graph") -/// ~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} -/// var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); -/// var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]); -/// var graph = graph_module._create("myGraph", [ed1, ed2]); -/// graph._deleteEdgeDefinition("myEC1", true); -/// db._collection("myEC1"); -/// ~ db._drop("myEC1"); -/// ~ var blub = graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Delete one relation definition + +`graph_module._deleteEdgeDefinition(edgeCollectionName, dropCollection)` + +Deletes a relation definition defined by the edge collection of a graph. If the +collections defined in the edge definition (collection, from, to) are not used +in another edge definition of the graph, they will be moved to the orphanage. + +@PARAMS + +@PARAM{edgeCollectionName, string, required} +Name of edge collection in the relation definition. +@PARAM{dropCollection, boolean, optional} +Define if the edge collection should be dropped. Default false. + +@EXAMPLES + +Remove an edge definition but keep the edge collection: + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph__deleteEdgeDefinition} + var graph_module = require("@arangodb/general-graph") +~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} + var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); + var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]); + var graph = graph_module._create("myGraph", [ed1, ed2]); + graph._deleteEdgeDefinition("myEC1"); + db._collection("myEC1"); +~ db._drop("myEC1"); +~ var blub = graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Remove an edge definition and drop the edge collection: + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph__deleteEdgeDefinitionWithDrop} + var graph_module = require("@arangodb/general-graph") +~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} + var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); + var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]); + var graph = graph_module._create("myGraph", [ed1, ed2]); + graph._deleteEdgeDefinition("myEC1", true); + db._collection("myEC1"); +~ db._drop("myEC1"); +~ var blub = graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph__editEdgeDefinition.md b/Documentation/DocuBlocks/JSF_general_graph__editEdgeDefinition.md index 676b0f3268..ee9318da2d 100644 --- a/Documentation/DocuBlocks/JSF_general_graph__editEdgeDefinition.md +++ b/Documentation/DocuBlocks/JSF_general_graph__editEdgeDefinition.md @@ -1,33 +1,32 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph__editEdgeDefinition -/// @brief Modify an relation definition -/// -/// `graph_module._editEdgeDefinition(edgeDefinition)` -/// -/// 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. -/// Vertex Collections of the replaced edge definition that are not used in the new -/// definition will transform to an orphan. Orphans that are used in this new edge -/// definition will be deleted from the list of orphans. Other graphs with the same edge -/// definition will be modified, too. -/// -/// @PARAMS -/// -/// @PARAM{edgeDefinition, object, required} -/// The edge definition to replace the existing edge -/// definition with the same attribute *collection*. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph__editEdgeDefinition} -/// var graph_module = require("@arangodb/general-graph") -/// ~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} -/// var original = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); -/// var modified = graph_module._relation("myEC1", ["myVC2"], ["myVC3"]); -/// var graph = graph_module._create("myGraph", [original]); -/// graph._editEdgeDefinitions(modified); -/// ~ var blub = graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Modify an relation definition + +`graph_module._editEdgeDefinition(edgeDefinition)` + +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. +Vertex Collections of the replaced edge definition that are not used in the new +definition will transform to an orphan. Orphans that are used in this new edge +definition will be deleted from the list of orphans. Other graphs with the same edge +definition will be modified, too. + +@PARAMS + +@PARAM{edgeDefinition, object, required} +The edge definition to replace the existing edge +definition with the same attribute *collection*. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph__editEdgeDefinition} + var graph_module = require("@arangodb/general-graph") +~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} + var original = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); + var modified = graph_module._relation("myEC1", ["myVC2"], ["myVC3"]); + var graph = graph_module._create("myGraph", [original]); + graph._editEdgeDefinitions(modified); +~ var blub = graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph__extendEdgeDefinitions.md b/Documentation/DocuBlocks/JSF_general_graph__extendEdgeDefinitions.md index 6cd48a71df..1bd5f14d6f 100644 --- a/Documentation/DocuBlocks/JSF_general_graph__extendEdgeDefinitions.md +++ b/Documentation/DocuBlocks/JSF_general_graph__extendEdgeDefinitions.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph__extendEdgeDefinitions -/// @brief Add another edge definition to the graph -/// -/// `graph._extendEdgeDefinitions(edgeDefinition)` -/// -/// 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 -/// the edge definition to add is already used in the graph or used in a different -/// graph with different *from* and/or *to* collections an error is thrown. -/// -/// @PARAMS -/// -/// @PARAM{edgeDefinition, object, required} -/// The relation definition to extend the graph -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph__extendEdgeDefinitions} -/// var graph_module = require("@arangodb/general-graph") -/// ~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} -/// var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); -/// var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]); -/// var graph = graph_module._create("myGraph", [ed1]); -/// graph._extendEdgeDefinitions(ed2); -/// ~ var blub = graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Add another edge definition to the graph + +`graph._extendEdgeDefinitions(edgeDefinition)` + +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 +the edge definition to add is already used in the graph or used in a different +graph with different *from* and/or *to* collections an error is thrown. + +@PARAMS + +@PARAM{edgeDefinition, object, required} +The relation definition to extend the graph + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph__extendEdgeDefinitions} + var graph_module = require("@arangodb/general-graph") +~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} + var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); + var ed2 = graph_module._relation("myEC2", ["myVC1"], ["myVC3"]); + var graph = graph_module._create("myGraph", [ed1]); + graph._extendEdgeDefinitions(ed2); +~ var blub = graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph__orphanCollections.md b/Documentation/DocuBlocks/JSF_general_graph__orphanCollections.md index f5c92884f1..4ce178c7c0 100644 --- a/Documentation/DocuBlocks/JSF_general_graph__orphanCollections.md +++ b/Documentation/DocuBlocks/JSF_general_graph__orphanCollections.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph__orphanCollections -/// @brief Get all orphan collections -/// -/// `graph._orphanCollections()` -/// -/// Returns all vertex collections of the graph that are not used in any edge definition. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph__orphanCollections} -/// var graph_module = require("@arangodb/general-graph") -/// ~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} -/// var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); -/// var graph = graph_module._create("myGraph", [ed1]); -/// graph._addVertexCollection("myVC3", true); -/// graph._orphanCollections(); -/// ~ var blub = graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get all orphan collections + +`graph._orphanCollections()` + +Returns all vertex collections of the graph that are not used in any edge definition. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph__orphanCollections} + var graph_module = require("@arangodb/general-graph") +~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} + var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); + var graph = graph_module._create("myGraph", [ed1]); + graph._addVertexCollection("myVC3", true); + graph._orphanCollections(); +~ var blub = graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph__removeVertexCollection.md b/Documentation/DocuBlocks/JSF_general_graph__removeVertexCollection.md index 7e2b7a6360..0f316b1faf 100644 --- a/Documentation/DocuBlocks/JSF_general_graph__removeVertexCollection.md +++ b/Documentation/DocuBlocks/JSF_general_graph__removeVertexCollection.md @@ -1,37 +1,36 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph__removeVertexCollection -/// @brief Remove a vertex collection from the graph -/// -/// `graph._removeVertexCollection(vertexCollectionName, dropCollection)` -/// -/// Removes a vertex collection from the graph. -/// Only collections not used in any relation definition can be removed. -/// Optionally the collection can be deleted, if it is not used in any other graph. -/// -/// @PARAMS -/// -/// @PARAM{vertexCollectionName, string, required} -/// Name of vertex collection. -/// -/// @PARAM{dropCollection, boolean, optional} -/// If true the collection will be dropped if it is -/// not used in any other graph. Default: false. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph__removeVertexCollections} -/// var graph_module = require("@arangodb/general-graph") -/// ~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} -/// var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); -/// var graph = graph_module._create("myGraph", [ed1]); -/// graph._addVertexCollection("myVC3", true); -/// graph._addVertexCollection("myVC4", true); -/// graph._orphanCollections(); -/// graph._removeVertexCollection("myVC3"); -/// graph._orphanCollections(); -/// ~ db._drop("myVC3"); -/// ~ var blub = graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Remove a vertex collection from the graph + +`graph._removeVertexCollection(vertexCollectionName, dropCollection)` + +Removes a vertex collection from the graph. +Only collections not used in any relation definition can be removed. +Optionally the collection can be deleted, if it is not used in any other graph. + +@PARAMS + +@PARAM{vertexCollectionName, string, required} +Name of vertex collection. + +@PARAM{dropCollection, boolean, optional} +If true the collection will be dropped if it is +not used in any other graph. Default: false. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph__removeVertexCollections} + var graph_module = require("@arangodb/general-graph") +~ if (graph_module._exists("myGraph")){var blub = graph_module._drop("myGraph", true);} + var ed1 = graph_module._relation("myEC1", ["myVC1"], ["myVC2"]); + var graph = graph_module._create("myGraph", [ed1]); + graph._addVertexCollection("myVC3", true); + graph._addVertexCollection("myVC4", true); + graph._orphanCollections(); + graph._removeVertexCollection("myVC3"); + graph._orphanCollections(); +~ db._drop("myVC3"); +~ var blub = graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_absolute_betweenness.md b/Documentation/DocuBlocks/JSF_general_graph_absolute_betweenness.md index 7380e0d47d..08011544db 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_absolute_betweenness.md +++ b/Documentation/DocuBlocks/JSF_general_graph_absolute_betweenness.md @@ -1,59 +1,58 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_absolute_betweenness -/// @brief Get the -/// [betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) -/// of all vertices in the graph. -/// -/// `graph._absoluteBetweenness(vertexExample, options)` -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @PARAMS -/// -/// @PARAM{vertexExample, object, optional} -/// Filter the vertices, see [Definition of examples](#definition-of-examples) -/// -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *weight*: The name of the attribute of the edges containing the weight. -/// * *defaultWeight*: Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as weight. -/// If no default is supplied the default would be positive infinity so the path and -/// hence the betweeness can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the absolute betweenness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsBetweenness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._absoluteBetweenness({}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute betweenness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsBetweenness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._absoluteBetweenness({weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute betweenness of all cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsBetweenness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._absoluteBetweenness({direction : 'outbound', weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the +[betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) +of all vertices in the graph. + +`graph._absoluteBetweenness(vertexExample, options)` + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@PARAMS + +@PARAM{vertexExample, object, optional} +Filter the vertices, see [Definition of examples](#definition-of-examples) + +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *weight*: The name of the attribute of the edges containing the weight. + * *defaultWeight*: Only used with the option *weight*. + If an edge does not have the attribute named as defined in option *weight* this default + is used as weight. + If no default is supplied the default would be positive infinity so the path and + hence the betweeness can not be calculated. + +@EXAMPLES + +A route planner example, the absolute betweenness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsBetweenness1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._absoluteBetweenness({}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute betweenness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsBetweenness2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._absoluteBetweenness({weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute betweenness of all cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsBetweenness3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._absoluteBetweenness({direction : 'outbound', weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_absolute_closeness.md b/Documentation/DocuBlocks/JSF_general_graph_absolute_closeness.md index 86d2e95752..84ebef8ee5 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_absolute_closeness.md +++ b/Documentation/DocuBlocks/JSF_general_graph_absolute_closeness.md @@ -1,73 +1,72 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_absolute_closeness -/// @brief Get the -/// [closeness](http://en.wikipedia.org/wiki/Centrality#Closeness_centrality) -/// of the vertices defined by the examples. -/// -/// `graph._absoluteCloseness(vertexExample, options)` -/// -/// The function accepts an id, an example, a list of examples or even an empty -/// example as parameter for *vertexExample*. -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @PARAMS -/// -/// @PARAM{vertexExample, object, optional} -/// Filter the vertices, see [Definition of examples](#definition-of-examples) -/// -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeCollectionRestriction* : One or a list of edge-collection names that should be -/// considered to be on the path. -/// * *startVertexCollectionRestriction* : One or a list of vertex-collection names that should be -/// considered for source vertices. -/// * *endVertexCollectionRestriction* : One or a list of vertex-collection names that should be -/// considered for target vertices. -/// * *edgeExamples*: Filter the edges to be followed, see [Definition of examples](#definition-of-examples) -/// * *algorithm*: The algorithm to calculate the shortest paths, possible values are -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and -/// [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight*: The name of the attribute of the edges containing the weight. -/// * *defaultWeight*: Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as weight. -/// If no default is supplied the default would be positive infinity so the path and -/// hence the closeness can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the absolute closeness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsCloseness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._absoluteCloseness({}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute closeness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsCloseness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._absoluteCloseness({}, {weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute closeness of all German Cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsCloseness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// | graph._absoluteCloseness({}, {startVertexCollectionRestriction : 'germanCity', -/// direction : 'outbound', weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the +[closeness](http://en.wikipedia.org/wiki/Centrality#Closeness_centrality) +of the vertices defined by the examples. + +`graph._absoluteCloseness(vertexExample, options)` + +The function accepts an id, an example, a list of examples or even an empty +example as parameter for *vertexExample*. + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@PARAMS + +@PARAM{vertexExample, object, optional} +Filter the vertices, see [Definition of examples](#definition-of-examples) + +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *edgeCollectionRestriction* : One or a list of edge-collection names that should be + considered to be on the path. + * *startVertexCollectionRestriction* : One or a list of vertex-collection names that should be + considered for source vertices. + * *endVertexCollectionRestriction* : One or a list of vertex-collection names that should be + considered for target vertices. + * *edgeExamples*: Filter the edges to be followed, see [Definition of examples](#definition-of-examples) + * *algorithm*: The algorithm to calculate the shortest paths, possible values are + [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and + [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight*: The name of the attribute of the edges containing the weight. + * *defaultWeight*: Only used with the option *weight*. + If an edge does not have the attribute named as defined in option *weight* this default + is used as weight. + If no default is supplied the default would be positive infinity so the path and + hence the closeness can not be calculated. + +@EXAMPLES + +A route planner example, the absolute closeness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsCloseness1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._absoluteCloseness({}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute closeness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsCloseness2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._absoluteCloseness({}, {weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute closeness of all German Cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsCloseness3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); +| graph._absoluteCloseness({}, {startVertexCollectionRestriction : 'germanCity', + direction : 'outbound', weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_absolute_eccentricity.md b/Documentation/DocuBlocks/JSF_general_graph_absolute_eccentricity.md index f36879de2f..62f36c8a73 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_absolute_eccentricity.md +++ b/Documentation/DocuBlocks/JSF_general_graph_absolute_eccentricity.md @@ -1,75 +1,74 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_absolute_eccentricity -/// @brief Get the -/// [eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) -/// of the vertices defined by the examples. -/// -/// `graph._absoluteEccentricity(vertexExample, options)` -/// -/// The function accepts an id, an example, a list of examples or even an empty -/// example as parameter for vertexExample. -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @PARAMS -/// -/// @PARAM{vertexExample, object, optional} -/// Filter the vertices, see [Definition of examples](#definition-of-examples) -/// -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeCollectionRestriction* : One or a list of edge-collection names that should be -/// considered to be on the path. -/// * *startVertexCollectionRestriction* : One or a list of vertex-collection names that should be -/// considered for source vertices. -/// * *endVertexCollectionRestriction* : One or a list of vertex-collection names that should be -/// considered for target vertices. -/// * *edgeExamples*: Filter the edges to be followed, see [Definition of examples](#definition-of-examples) -/// * *algorithm*: The algorithm to calculate the shortest paths, possible values are -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and -/// [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight*: The name of the attribute of the edges containing the weight. -/// * *defaultWeight*: Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as weight. -/// If no default is supplied the default would be positive infinity so the path and -/// hence the eccentricity can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the absolute eccentricity of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsEccentricity1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// | db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY(" -/// | + "'routeplanner', {})" -/// ).toArray(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute eccentricity of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsEccentricity2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._absoluteEccentricity({}, {weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the absolute eccentricity of all cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsEccentricity3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// | graph._absoluteEccentricity({}, {startVertexCollectionRestriction : 'germanCity', -/// direction : 'outbound', weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the +[eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) +of the vertices defined by the examples. + +`graph._absoluteEccentricity(vertexExample, options)` + +The function accepts an id, an example, a list of examples or even an empty +example as parameter for vertexExample. + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@PARAMS + +@PARAM{vertexExample, object, optional} +Filter the vertices, see [Definition of examples](#definition-of-examples) + +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *edgeCollectionRestriction* : One or a list of edge-collection names that should be + considered to be on the path. + * *startVertexCollectionRestriction* : One or a list of vertex-collection names that should be + considered for source vertices. + * *endVertexCollectionRestriction* : One or a list of vertex-collection names that should be + considered for target vertices. + * *edgeExamples*: Filter the edges to be followed, see [Definition of examples](#definition-of-examples) + * *algorithm*: The algorithm to calculate the shortest paths, possible values are + [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and + [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight*: The name of the attribute of the edges containing the weight. + * *defaultWeight*: Only used with the option *weight*. + If an edge does not have the attribute named as defined in option *weight* this default + is used as weight. + If no default is supplied the default would be positive infinity so the path and + hence the eccentricity can not be calculated. + +@EXAMPLES + +A route planner example, the absolute eccentricity of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsEccentricity1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); +| db._query("RETURN GRAPH_ABSOLUTE_ECCENTRICITY(" +| + "'routeplanner', {})" + ).toArray(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute eccentricity of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsEccentricity2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._absoluteEccentricity({}, {weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the absolute eccentricity of all cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAbsEccentricity3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); +| graph._absoluteEccentricity({}, {startVertexCollectionRestriction : 'germanCity', + direction : 'outbound', weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_betweenness.md b/Documentation/DocuBlocks/JSF_general_graph_betweenness.md index 5d3b09970d..422014ae72 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_betweenness.md +++ b/Documentation/DocuBlocks/JSF_general_graph_betweenness.md @@ -1,43 +1,42 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_betweenness -/// @brief Get the normalized -/// [betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) -/// of graphs vertices. -/// -/// `graph_module._betweenness(options)` -/// -/// Similar to [_absoluteBetweeness](#absolutebetweenness) but returns normalized values. -/// -/// @EXAMPLES -/// -/// A route planner example, the betweenness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleBetweenness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._betweenness(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the betweenness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleBetweenness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._betweenness({weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the betweenness of all cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleBetweenness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._betweenness({direction : 'outbound', weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the normalized +[betweenness](http://en.wikipedia.org/wiki/Betweenness_centrality) +of graphs vertices. + +`graph_module._betweenness(options)` + +Similar to [_absoluteBetweeness](#absolutebetweenness) but returns normalized values. + +@EXAMPLES + +A route planner example, the betweenness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleBetweenness1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._betweenness(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the betweenness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleBetweenness2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._betweenness({weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the betweenness of all cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleBetweenness3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._betweenness({direction : 'outbound', weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_closeness.md b/Documentation/DocuBlocks/JSF_general_graph_closeness.md index 0355feaac1..1f95a351fd 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_closeness.md +++ b/Documentation/DocuBlocks/JSF_general_graph_closeness.md @@ -1,46 +1,45 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_closeness -/// @brief Get the normalized -/// [closeness](http://en.wikipedia.org/wiki/Centrality#Closeness_centrality) -/// of graphs vertices. -/// -/// `graph._closeness(options)` -/// -/// Similar to [_absoluteCloseness](#absolutecloseness) but returns a normalized value. -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @EXAMPLES -/// -/// A route planner example, the normalized closeness of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCloseness1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._closeness(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the closeness of all locations. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCloseness2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._closeness({weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the closeness of all cities regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCloseness3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._closeness({direction : 'outbound', weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the normalized +[closeness](http://en.wikipedia.org/wiki/Centrality#Closeness_centrality) +of graphs vertices. + +`graph._closeness(options)` + +Similar to [_absoluteCloseness](#absolutecloseness) but returns a normalized value. + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@EXAMPLES + +A route planner example, the normalized closeness of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCloseness1} +var examples = require("@arangodb/graph-examples/example-graph.js"); +var graph = examples.loadGraph("routeplanner"); +graph._closeness(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the closeness of all locations. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCloseness2} +var examples = require("@arangodb/graph-examples/example-graph.js"); +var graph = examples.loadGraph("routeplanner"); +graph._closeness({weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the closeness of all cities regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCloseness3} +var examples = require("@arangodb/graph-examples/example-graph.js"); +var graph = examples.loadGraph("routeplanner"); +graph._closeness({direction : 'outbound', weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_common_neighbors.md b/Documentation/DocuBlocks/JSF_general_graph_common_neighbors.md index 335595d1d8..2bd3167883 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_common_neighbors.md +++ b/Documentation/DocuBlocks/JSF_general_graph_common_neighbors.md @@ -1,42 +1,41 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_common_neighbors -/// @brief Get all common neighbors of the vertices defined by the examples. -/// -/// `graph._commonNeighbors(vertex1Example, vertex2Examples, optionsVertex1, optionsVertex2)` -/// -/// This function returns the intersection of *graph_module._neighbors(vertex1Example, optionsVertex1)* -/// and *graph_module._neighbors(vertex2Example, optionsVertex2)*. -/// For parameter documentation see [_neighbors](#neighbors). -/// -/// The complexity of this method is **O(n\*m^x)** with *n* being the maximal amount of vertices -/// defined by the parameters vertexExamples, *m* the average amount of neighbors and *x* the -/// maximal depths. -/// Hence the default call would have a complexity of **O(n\*m)**; -/// -/// @EXAMPLES -/// -/// A route planner example, all common neighbors of capitals. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighbors1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._commonNeighbors({isCapital : true}, {isCapital : true}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all common outbound neighbors of Hamburg with any other location -/// which have a maximal depth of 2 : -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighbors2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// | graph._commonNeighbors( -/// | 'germanCity/Hamburg', -/// | {}, -/// | {direction : 'outbound', maxDepth : 2}, -/// {direction : 'outbound', maxDepth : 2}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get all common neighbors of the vertices defined by the examples. + +`graph._commonNeighbors(vertex1Example, vertex2Examples, optionsVertex1, optionsVertex2)` + +This function returns the intersection of *graph_module._neighbors(vertex1Example, optionsVertex1)* +and *graph_module._neighbors(vertex2Example, optionsVertex2)*. +For parameter documentation see [_neighbors](#neighbors). + +The complexity of this method is **O(n\*m^x)** with *n* being the maximal amount of vertices +defined by the parameters vertexExamples, *m* the average amount of neighbors and *x* the +maximal depths. +Hence the default call would have a complexity of **O(n\*m)**; + +@EXAMPLES + +A route planner example, all common neighbors of capitals. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighbors1} +var examples = require("@arangodb/graph-examples/example-graph.js"); +var graph = examples.loadGraph("routeplanner"); +graph._commonNeighbors({isCapital : true}, {isCapital : true}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all common outbound neighbors of Hamburg with any other location +which have a maximal depth of 2 : + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighbors2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); +| graph._commonNeighbors( +| 'germanCity/Hamburg', +| {}, +| {direction : 'outbound', maxDepth : 2}, + {direction : 'outbound', maxDepth : 2}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_common_properties.md b/Documentation/DocuBlocks/JSF_general_graph_common_properties.md index 84aaa051cd..377e0cd592 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_common_properties.md +++ b/Documentation/DocuBlocks/JSF_general_graph_common_properties.md @@ -1,50 +1,49 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_common_properties -/// @brief Get the vertices of the graph that share common properties. -/// -/// `graph._commonProperties(vertex1Example, vertex2Examples, options)` -/// -/// The function accepts an id, an example, a list of examples or even an empty -/// example as parameter for vertex1Example and vertex2Example. -/// -/// The complexity of this method is **O(n)** with *n* being the maximal amount of vertices -/// defined by the parameters vertexExamples. -/// -/// @PARAMS -/// -/// @PARAM{vertex1Examples, object, optional} -/// Filter the set of source vertices, see [Definition of examples](#definition-of-examples) -/// -/// @PARAM{vertex2Examples, object, optional} -/// Filter the set of vertices compared to, see [Definition of examples](#definition-of-examples) -/// -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *vertex1CollectionRestriction* : One or a list of vertex-collection names that should be -/// searched for source vertices. -/// * *vertex2CollectionRestriction* : One or a list of vertex-collection names that should be -/// searched for compare vertices. -/// * *ignoreProperties* : One or a list of attribute names of a document that should be ignored. -/// -/// @EXAMPLES -/// -/// A route planner example, all locations with the same properties: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleProperties1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._commonProperties({}, {}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all cities which share same properties except for population. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleProperties2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._commonProperties({}, {}, {ignoreProperties: 'population'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the vertices of the graph that share common properties. + +`graph._commonProperties(vertex1Example, vertex2Examples, options)` + +The function accepts an id, an example, a list of examples or even an empty +example as parameter for vertex1Example and vertex2Example. + +The complexity of this method is **O(n)** with *n* being the maximal amount of vertices +defined by the parameters vertexExamples. + +@PARAMS + +@PARAM{vertex1Examples, object, optional} +Filter the set of source vertices, see [Definition of examples](#definition-of-examples) + +@PARAM{vertex2Examples, object, optional} +Filter the set of vertices compared to, see [Definition of examples](#definition-of-examples) + +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *vertex1CollectionRestriction* : One or a list of vertex-collection names that should be + searched for source vertices. + * *vertex2CollectionRestriction* : One or a list of vertex-collection names that should be + searched for compare vertices. + * *ignoreProperties* : One or a list of attribute names of a document that should be ignored. + +@EXAMPLES + +A route planner example, all locations with the same properties: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleProperties1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._commonProperties({}, {}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all cities which share same properties except for population. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleProperties2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._commonProperties({}, {}, {ignoreProperties: 'population'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_connectingEdges.md b/Documentation/DocuBlocks/JSF_general_graph_connectingEdges.md index 316d5af255..c521b5d6b6 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_connectingEdges.md +++ b/Documentation/DocuBlocks/JSF_general_graph_connectingEdges.md @@ -1,38 +1,37 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_connectingEdges -/// @brief Get all connecting edges between 2 groups of vertices defined by the examples -/// -/// `graph._connectingEdges(vertexExample, vertexExample2, options)` -/// -/// The function accepts an id, an example, a list of examples or even an empty -/// example as parameter for vertexExample. -/// -/// @PARAMS -/// -/// @PARAM{vertexExample1, object, optional} -/// See [Definition of examples](Functions.md#definition-of-examples) -/// @PARAM{vertexExample2, object, optional} -/// See [Definition of examples](Functions.md#definition-of-examples) -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *edgeExamples*: Filter the edges, see [Definition of examples](Functions.md#definition-of-examples) -/// * *edgeCollectionRestriction* : One or a list of edge-collection names that should be -/// considered to be on the path. -/// * *vertex1CollectionRestriction* : One or a list of vertex-collection names that should be -/// considered on the intermediate vertex steps. -/// * *vertex2CollectionRestriction* : One or a list of vertex-collection names that should be -/// considered on the intermediate vertex steps. -/// -/// @EXAMPLES -/// -/// A route planner example, all connecting edges between capitals. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleConnectingEdges1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._getConnectingEdges({isCapital : true}, {isCapital : true}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get all connecting edges between 2 groups of vertices defined by the examples + +`graph._connectingEdges(vertexExample, vertexExample2, options)` + +The function accepts an id, an example, a list of examples or even an empty +example as parameter for vertexExample. + +@PARAMS + +@PARAM{vertexExample1, object, optional} +See [Definition of examples](Functions.md#definition-of-examples) +@PARAM{vertexExample2, object, optional} +See [Definition of examples](Functions.md#definition-of-examples) +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *edgeExamples*: Filter the edges, see [Definition of examples](Functions.md#definition-of-examples) + * *edgeCollectionRestriction* : One or a list of edge-collection names that should be + considered to be on the path. + * *vertex1CollectionRestriction* : One or a list of vertex-collection names that should be + considered on the intermediate vertex steps. + * *vertex2CollectionRestriction* : One or a list of vertex-collection names that should be + considered on the intermediate vertex steps. + +@EXAMPLES + +A route planner example, all connecting edges between capitals. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleConnectingEdges1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._getConnectingEdges({isCapital : true}, {isCapital : true}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_count_common_neighbors.md b/Documentation/DocuBlocks/JSF_general_graph_count_common_neighbors.md index a3fed75854..474f931887 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_count_common_neighbors.md +++ b/Documentation/DocuBlocks/JSF_general_graph_count_common_neighbors.md @@ -1,34 +1,33 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_count_common_neighbors -/// @brief Get the amount of common neighbors of the vertices defined by the examples. -/// -/// `graph._countCommonNeighbors(vertex1Example, vertex2Examples, optionsVertex1, optionsVertex2)` -/// -/// Similar to [_commonNeighbors](#commonneighbors) but returns count instead of the elements. -/// -/// @EXAMPLES -/// -/// A route planner example, all common neighbors of capitals. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighborsAmount1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// var example = { isCapital: true }; -/// var options = { includeData: true }; -/// graph._countCommonNeighbors(example, example, options, options); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all common outbound neighbors of Hamburg with any other location -/// which have a maximal depth of 2 : -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighborsAmount2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// var options = { direction: 'outbound', maxDepth: 2, includeData: true }; -/// graph._countCommonNeighbors('germanCity/Hamburg', {}, options, options); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the amount of common neighbors of the vertices defined by the examples. + +`graph._countCommonNeighbors(vertex1Example, vertex2Examples, optionsVertex1, optionsVertex2)` + +Similar to [_commonNeighbors](#commonneighbors) but returns count instead of the elements. + +@EXAMPLES + +A route planner example, all common neighbors of capitals. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighborsAmount1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + var example = { isCapital: true }; + var options = { includeData: true }; + graph._countCommonNeighbors(example, example, options, options); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all common outbound neighbors of Hamburg with any other location +which have a maximal depth of 2 : + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleCommonNeighborsAmount2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + var options = { direction: 'outbound', maxDepth: 2, includeData: true }; + graph._countCommonNeighbors('germanCity/Hamburg', {}, options, options); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_count_common_properties.md b/Documentation/DocuBlocks/JSF_general_graph_count_common_properties.md index 1ba4f9e238..e1c9a17f23 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_count_common_properties.md +++ b/Documentation/DocuBlocks/JSF_general_graph_count_common_properties.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_count_common_properties -/// @brief Get the amount of vertices of the graph that share common properties. -/// -/// `graph._countCommonProperties(vertex1Example, vertex2Examples, options)` -/// -/// Similar to [_commonProperties](#commonproperties) but returns count instead of -/// the objects. -/// -/// @EXAMPLES -/// -/// A route planner example, all locations with the same properties: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAmountProperties1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._countCommonProperties({}, {}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all German cities which share same properties except for population. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAmountProperties2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// | graph._countCommonProperties({}, {}, {vertex1CollectionRestriction : 'germanCity', -/// vertex2CollectionRestriction : 'germanCity' ,ignoreProperties: 'population'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the amount of vertices of the graph that share common properties. + +`graph._countCommonProperties(vertex1Example, vertex2Examples, options)` + +Similar to [_commonProperties](#commonproperties) but returns count instead of +the objects. + +@EXAMPLES + +A route planner example, all locations with the same properties: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAmountProperties1} +var examples = require("@arangodb/graph-examples/example-graph.js"); +var graph = examples.loadGraph("routeplanner"); +graph._countCommonProperties({}, {}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all German cities which share same properties except for population. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleAmountProperties2} +var examples = require("@arangodb/graph-examples/example-graph.js"); +var graph = examples.loadGraph("routeplanner"); +| graph._countCommonProperties({}, {}, {vertex1CollectionRestriction : 'germanCity', + vertex2CollectionRestriction : 'germanCity' ,ignoreProperties: 'population'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_create.md b/Documentation/DocuBlocks/JSF_general_graph_create.md index d3d6305049..3ad5b474f2 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_create.md +++ b/Documentation/DocuBlocks/JSF_general_graph_create.md @@ -1,56 +1,55 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_create -/// @brief Create a graph -/// -/// `graph_module._create(graphName, edgeDefinitions, orphanCollections)` -/// -/// 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. -/// Optionally a list of vertex collections can be added, which are not used in any edge definition. -/// These collections are referred to as orphan collections within this chapter. -/// All collections used within the creation process are created if they do not exist. -/// -/// @PARAMS -/// -/// @PARAM{graphName, string, required} -/// Unique identifier of the graph -/// -/// @PARAM{edgeDefinitions, array, optional} -/// List of relation definition objects -/// -/// @PARAM{orphanCollections, array, optional} -/// List of additional vertex collection names -/// -/// @EXAMPLES -/// -/// Create an empty graph, edge definitions can be added at runtime: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraph} -/// var graph_module = require("@arangodb/general-graph"); -/// graph = graph_module._create("myGraph"); -/// ~ graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Create a graph using an edge collection `edges` and a single vertex collection `vertices` -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphSingle} -/// ~ db._drop("edges"); -/// ~ db._drop("vertices"); -/// var graph_module = require("@arangodb/general-graph"); -/// var edgeDefinitions = [ { collection: "edges", "from": [ "vertices" ], "to" : [ "vertices" ] } ]; -/// graph = graph_module._create("myGraph", edgeDefinitions); -/// ~ graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Create a graph with edge definitions and orphan collections: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraph2} -/// var graph_module = require("@arangodb/general-graph"); -/// | graph = graph_module._create("myGraph", -/// [graph_module._relation("myRelation", ["male", "female"], ["male", "female"])], ["sessions"]); -/// ~ graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Create a graph + +`graph_module._create(graphName, edgeDefinitions, orphanCollections)` + +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. +Optionally a list of vertex collections can be added, which are not used in any edge definition. +These collections are referred to as orphan collections within this chapter. +All collections used within the creation process are created if they do not exist. + +@PARAMS + +@PARAM{graphName, string, required} +Unique identifier of the graph + +@PARAM{edgeDefinitions, array, optional} +List of relation definition objects + +@PARAM{orphanCollections, array, optional} +List of additional vertex collection names + +@EXAMPLES + +Create an empty graph, edge definitions can be added at runtime: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraph} + var graph_module = require("@arangodb/general-graph"); + graph = graph_module._create("myGraph"); +~ graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Create a graph using an edge collection `edges` and a single vertex collection `vertices` + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphSingle} +~ db._drop("edges"); +~ db._drop("vertices"); + var graph_module = require("@arangodb/general-graph"); + var edgeDefinitions = [ { collection: "edges", "from": [ "vertices" ], "to" : [ "vertices" ] } ]; + graph = graph_module._create("myGraph", edgeDefinitions); +~ graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Create a graph with edge definitions and orphan collections: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraph2} + var graph_module = require("@arangodb/general-graph"); +| graph = graph_module._create("myGraph", + [graph_module._relation("myRelation", ["male", "female"], ["male", "female"])], ["sessions"]); +~ graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_create_graph_example1.md b/Documentation/DocuBlocks/JSF_general_graph_create_graph_example1.md index e9dbdee4bf..06edfcbf33 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_create_graph_example1.md +++ b/Documentation/DocuBlocks/JSF_general_graph_create_graph_example1.md @@ -1,21 +1,20 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_create_graph_example1 -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph_create_graph_example1} -/// var graph_module = require("@arangodb/general-graph"); -/// var edgeDefinitions = graph_module._edgeDefinitions(); -/// graph_module._extendEdgeDefinitions(edgeDefinitions, graph_module._relation("friend_of", "Customer", "Customer")); -/// | graph_module._extendEdgeDefinitions( -/// | edgeDefinitions, graph_module._relation( -/// "has_bought", ["Customer", "Company"], ["Groceries", "Electronics"])); -/// graph_module._create("myStore", edgeDefinitions); -/// ~ graph_module._drop("myStore"); -/// ~ db._drop("Electronics"); -/// ~ db._drop("Customer"); -/// ~ db._drop("Groceries"); -/// ~ db._drop("Company"); -/// ~ db._drop("has_bought"); -/// ~ db._drop("friend_of"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph_create_graph_example1} + var graph_module = require("@arangodb/general-graph"); + var edgeDefinitions = graph_module._edgeDefinitions(); + graph_module._extendEdgeDefinitions(edgeDefinitions, graph_module._relation("friend_of", "Customer", "Customer")); +| graph_module._extendEdgeDefinitions( +| edgeDefinitions, graph_module._relation( + "has_bought", ["Customer", "Company"], ["Groceries", "Electronics"])); + graph_module._create("myStore", edgeDefinitions); +~ graph_module._drop("myStore"); +~ db._drop("Electronics"); +~ db._drop("Customer"); +~ db._drop("Groceries"); +~ db._drop("Company"); +~ db._drop("has_bought"); +~ db._drop("friend_of"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_create_graph_example2.md b/Documentation/DocuBlocks/JSF_general_graph_create_graph_example2.md index 3b4a33fc0f..5cde8592b5 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_create_graph_example2.md +++ b/Documentation/DocuBlocks/JSF_general_graph_create_graph_example2.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_create_graph_example2 -/// @EXAMPLE_ARANGOSH_OUTPUT{general_graph_create_graph_example2} -/// var graph_module = require("@arangodb/general-graph"); -/// | var edgeDefinitions = graph_module._edgeDefinitions( -/// | graph_module._relation("friend_of", ["Customer"], ["Customer"]), graph_module._relation( -/// "has_bought", ["Customer", "Company"], ["Groceries", "Electronics"])); -/// graph_module._create("myStore", edgeDefinitions); -/// ~ graph_module._drop("myStore"); -/// ~ db._drop("Electronics"); -/// ~ db._drop("Customer"); -/// ~ db._drop("Groceries"); -/// ~ db._drop("Company"); -/// ~ db._drop("has_bought"); -/// ~ db._drop("friend_of"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@EXAMPLE_ARANGOSH_OUTPUT{general_graph_create_graph_example2} + var graph_module = require("@arangodb/general-graph"); +| var edgeDefinitions = graph_module._edgeDefinitions( +| graph_module._relation("friend_of", ["Customer"], ["Customer"]), graph_module._relation( + "has_bought", ["Customer", "Company"], ["Groceries", "Electronics"])); + graph_module._create("myStore", edgeDefinitions); +~ graph_module._drop("myStore"); +~ db._drop("Electronics"); +~ db._drop("Customer"); +~ db._drop("Groceries"); +~ db._drop("Company"); +~ db._drop("has_bought"); +~ db._drop("friend_of"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_diameter.md b/Documentation/DocuBlocks/JSF_general_graph_diameter.md index 65772f7388..82ee06a245 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_diameter.md +++ b/Documentation/DocuBlocks/JSF_general_graph_diameter.md @@ -1,59 +1,58 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_diameter -/// @brief Get the -/// [diameter](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) -/// of a graph. -/// -/// `graph._diameter(graphName, options)` -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @PARAMS -/// -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *algorithm*: The algorithm to calculate the shortest paths, possible values are -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and -/// [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight*: The name of the attribute of the edges containing the weight. -/// * *defaultWeight*: Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as weight. -/// If no default is supplied the default would be positive infinity so the path and -/// hence the radius can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the diameter of the graph. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDiameter1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._diameter(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the diameter of the graph. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDiameter2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._diameter({weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the diameter of the graph regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDiameter3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._diameter({direction : 'outbound', weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the +[diameter](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) +of a graph. + +`graph._diameter(graphName, options)` + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@PARAMS + +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *algorithm*: The algorithm to calculate the shortest paths, possible values are + [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and + [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight*: The name of the attribute of the edges containing the weight. + * *defaultWeight*: Only used with the option *weight*. + If an edge does not have the attribute named as defined in option *weight* this default + is used as weight. + If no default is supplied the default would be positive infinity so the path and + hence the radius can not be calculated. + +@EXAMPLES + +A route planner example, the diameter of the graph. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDiameter1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._diameter(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the diameter of the graph. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDiameter2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._diameter({weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the diameter of the graph regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDiameter3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._diameter({direction : 'outbound', weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_directedRelation.md b/Documentation/DocuBlocks/JSF_general_graph_directedRelation.md index 7745e03ada..d3fc898be2 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_directedRelation.md +++ b/Documentation/DocuBlocks/JSF_general_graph_directedRelation.md @@ -1,34 +1,33 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_directedRelation -/// @brief Define a directed relation. -/// -/// `graph_module._directedRelation(relationName, fromVertexCollections, toVertexCollections)` -/// -/// 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*. -/// -/// @PARAMS -/// -/// @PARAM{relationName, string, required} -/// The name of the edge collection where the edges should be stored. -/// Will be created if it does not yet exist. -/// -/// @PARAM{fromVertexCollections, array, required} -/// One or a list of collection names. Source vertices for the edges -/// have to be stored in these collections. Collections will be created if they do not exist. -/// -/// @PARAM{toVertexCollections, array, required} -/// One or a list of collection names. Target vertices for the edges -/// have to be stored in these collections. Collections will be created if they do not exist. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDirectedRelationDefinition} -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._directedRelation("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Define a directed relation. + +`graph_module._directedRelation(relationName, fromVertexCollections, toVertexCollections)` + +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*. + +@PARAMS + +@PARAM{relationName, string, required} + The name of the edge collection where the edges should be stored. + Will be created if it does not yet exist. + +@PARAM{fromVertexCollections, array, required} + One or a list of collection names. Source vertices for the edges + have to be stored in these collections. Collections will be created if they do not exist. + +@PARAM{toVertexCollections, array, required} + One or a list of collection names. Target vertices for the edges + have to be stored in these collections. Collections will be created if they do not exist. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDirectedRelationDefinition} + var graph_module = require("@arangodb/general-graph"); + graph_module._directedRelation("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_distance_to.md b/Documentation/DocuBlocks/JSF_general_graph_distance_to.md index e321ed9a68..77e834226b 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_distance_to.md +++ b/Documentation/DocuBlocks/JSF_general_graph_distance_to.md @@ -1,33 +1,32 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_distance_to -/// @brief The _distanceTo function returns all paths and there distance within a graph. -/// -/// `graph._distanceTo(startVertexExample, endVertexExample, options)` -/// -/// This function is a wrapper of [graph._shortestPath](#shortestpath). -/// It does not return the actual path but only the distance between two vertices. -/// -/// @EXAMPLES -/// -/// A route planner example, shortest distance from all german to all french cities: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDistanceTo1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | g._distanceTo({}, {}, {weight : 'distance', endVertexCollectionRestriction : 'frenchCity', -/// startVertexCollectionRestriction : 'germanCity'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, shortest distance from Hamburg and Cologne to Lyon: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDistanceTo2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | g._distanceTo([{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], 'frenchCity/Lyon', -/// {weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief The _distanceTo function returns all paths and there distance within a graph. + +`graph._distanceTo(startVertexExample, endVertexExample, options)` + +This function is a wrapper of [graph._shortestPath](#shortestpath). +It does not return the actual path but only the distance between two vertices. + +@EXAMPLES + +A route planner example, shortest distance from all german to all french cities: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDistanceTo1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| g._distanceTo({}, {}, {weight : 'distance', endVertexCollectionRestriction : 'frenchCity', + startVertexCollectionRestriction : 'germanCity'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, shortest distance from Hamburg and Cologne to Lyon: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleDistanceTo2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| g._distanceTo([{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], 'frenchCity/Lyon', + {weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_drop.md b/Documentation/DocuBlocks/JSF_general_graph_drop.md index fcca8bc1aa..3f39486b8d 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_drop.md +++ b/Documentation/DocuBlocks/JSF_general_graph_drop.md @@ -1,49 +1,48 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_drop -/// @brief Remove a graph -/// -/// `graph_module._drop(graphName, dropCollections)` -/// -/// A graph can be dropped by its name. -/// This will automatically drop all collections contained in the graph as -/// long as they are not used within other graphs. -/// To drop the collections, the optional parameter *drop-collections* can be set to *true*. -/// -/// @PARAMS -/// -/// @PARAM{graphName, string, required} -/// Unique identifier of the graph -/// -/// @PARAM{dropCollections, boolean, optional} -/// Define if collections should be dropped (default: false) -/// -/// @EXAMPLES -/// -/// Drop a graph and keep collections: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDropGraphKeep} -/// ~ var examples = require("@arangodb/graph-examples/example-graph.js"); -/// ~ var g1 = examples.loadGraph("social"); -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._drop("social"); -/// db._collection("female"); -/// db._collection("male"); -/// db._collection("relation"); -/// ~ db._drop("female"); -/// ~ db._drop("male"); -/// ~ db._drop("relation"); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphDropGraphDropCollections} -/// ~ var examples = require("@arangodb/graph-examples/example-graph.js"); -/// ~ var g1 = examples.loadGraph("social"); -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._drop("social", true); -/// db._collection("female"); -/// db._collection("male"); -/// db._collection("relation"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Remove a graph + +`graph_module._drop(graphName, dropCollections)` + +A graph can be dropped by its name. +This will automatically drop all collections contained in the graph as +long as they are not used within other graphs. +To drop the collections, the optional parameter *drop-collections* can be set to *true*. + +@PARAMS + +@PARAM{graphName, string, required} +Unique identifier of the graph + +@PARAM{dropCollections, boolean, optional} +Define if collections should be dropped (default: false) + +@EXAMPLES + +Drop a graph and keep collections: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDropGraphKeep} +~ var examples = require("@arangodb/graph-examples/example-graph.js"); +~ var g1 = examples.loadGraph("social"); + var graph_module = require("@arangodb/general-graph"); + graph_module._drop("social"); + db._collection("female"); + db._collection("male"); + db._collection("relation"); +~ db._drop("female"); +~ db._drop("male"); +~ db._drop("relation"); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphDropGraphDropCollections} +~ var examples = require("@arangodb/graph-examples/example-graph.js"); +~ var g1 = examples.loadGraph("social"); + var graph_module = require("@arangodb/general-graph"); + graph_module._drop("social", true); + db._collection("female"); + db._collection("male"); + db._collection("relation"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_eccentricity.md b/Documentation/DocuBlocks/JSF_general_graph_eccentricity.md index eb196e06b8..0adc3a7924 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_eccentricity.md +++ b/Documentation/DocuBlocks/JSF_general_graph_eccentricity.md @@ -1,35 +1,34 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_eccentricity -/// @brief Get the normalized -/// [eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) -/// of the vertices defined by the examples. -/// -/// `graph._eccentricity(vertexExample, options)` -/// -/// Similar to [_absoluteEccentricity](#absoluteeccentricity) but returns a normalized result. -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @EXAMPLES -/// -/// A route planner example, the eccentricity of all locations. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleEccentricity2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._eccentricity(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the weighted eccentricity. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleEccentricity3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._eccentricity({weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the normalized +[eccentricity](http://en.wikipedia.org/wiki/Distance_%28graph_theory%29) +of the vertices defined by the examples. + +`graph._eccentricity(vertexExample, options)` + +Similar to [_absoluteEccentricity](#absoluteeccentricity) but returns a normalized result. + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@EXAMPLES + +A route planner example, the eccentricity of all locations. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleEccentricity2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._eccentricity(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the weighted eccentricity. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleEccentricity3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._eccentricity({weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_remove.md b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_remove.md index 3f5e7921c9..c6c5c4c85c 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_remove.md +++ b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_remove.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_edge_collection_remove -/// @brief Removes an edge in collection edgeCollectionName -/// -/// `graph.edgeCollectionName.remove(edgeId, options)` -/// -/// If this edge is used as a vertex by another edge, the other edge will be removed (recursively). -/// -/// @PARAMS -/// -/// @PARAM{edgeId, string, required} -/// *_id* attribute of the edge -/// -/// @PARAM{options, object, optional} -/// See [collection documentation](../Documents/DocumentMethods.md) -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionRemove} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.relation.save("female/alice", "female/diana", {_key: "aliceAndDiana"}); -/// db._exists("relation/aliceAndDiana") -/// graph.relation.remove("relation/aliceAndDiana") -/// db._exists("relation/aliceAndDiana") -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Removes an edge in collection edgeCollectionName + +`graph.edgeCollectionName.remove(edgeId, options)` + +If this edge is used as a vertex by another edge, the other edge will be removed (recursively). + +@PARAMS + +@PARAM{edgeId, string, required} +*_id* attribute of the edge + +@PARAM{options, object, optional} +See [collection documentation](../Documents/DocumentMethods.md) + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionRemove} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.relation.save("female/alice", "female/diana", {_key: "aliceAndDiana"}); + db._exists("relation/aliceAndDiana") + graph.relation.remove("relation/aliceAndDiana") + db._exists("relation/aliceAndDiana") +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_replace.md b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_replace.md index 0f682bdf5a..cb4d688f06 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_replace.md +++ b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_replace.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_edge_collection_replace -/// @brief Replaces the data of an edge in collection edgeCollectionName -/// -/// `graph.edgeCollectionName.replace(edgeId, data, options)` -/// -/// @PARAMS -/// -/// @PARAM{edgeId, string, required} -/// *_id* attribute of the edge -/// -/// @PARAM{data, object, required} -/// JSON data of the edge -/// -/// @PARAM{options, object, optional} -/// See [collection documentation](../Documents/DocumentMethods.md) -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionReplace} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.relation.save("female/alice", "female/diana", {typo: "nose", _key: "aliceAndDiana"}); -/// graph.relation.replace("relation/aliceAndDiana", {type: "knows"}); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Replaces the data of an edge in collection edgeCollectionName + +`graph.edgeCollectionName.replace(edgeId, data, options)` + +@PARAMS + +@PARAM{edgeId, string, required} +*_id* attribute of the edge + +@PARAM{data, object, required} +JSON data of the edge + +@PARAM{options, object, optional} +See [collection documentation](../Documents/DocumentMethods.md) + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionReplace} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.relation.save("female/alice", "female/diana", {typo: "nose", _key: "aliceAndDiana"}); + graph.relation.replace("relation/aliceAndDiana", {type: "knows"}); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_save.md b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_save.md index 01460e0cd1..f0369c04b6 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_save.md +++ b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_save.md @@ -1,43 +1,42 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_edge_collection_save -/// @brief Creates an edge from vertex *from* to vertex *to* in collection edgeCollectionName -/// -/// `graph.edgeCollectionName.save(from, to, data, options)` -/// -/// @PARAMS -/// -/// @PARAM{from, string, required} -/// *_id* attribute of the source vertex -/// -/// @PARAM{to, string, required} -/// *_id* attribute of the target vertex -/// -/// @PARAM{data, object, required} -/// JSON data of the edge -/// -/// @PARAM{options, object, optional} -/// See [collection documentation](../Edges/README.md) -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionSave1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.relation.save("male/bob", "female/alice", {type: "married", _key: "bobAndAlice"}); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// If the collections of *from* and *to* are not defined in an edge definition of the graph, -/// the edge will not be stored. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionSave2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// | graph.relation.save( -/// | "relation/aliceAndBob", -/// | "female/alice", -/// {type: "married", _key: "bobAndAlice"}); // xpError(ERROR_GRAPH_INVALID_EDGE) -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Creates an edge from vertex *from* to vertex *to* in collection edgeCollectionName + +`graph.edgeCollectionName.save(from, to, data, options)` + +@PARAMS + +@PARAM{from, string, required} +*_id* attribute of the source vertex + +@PARAM{to, string, required} +*_id* attribute of the target vertex + +@PARAM{data, object, required} +JSON data of the edge + +@PARAM{options, object, optional} +See [collection documentation](../Edges/README.md) + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionSave1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.relation.save("male/bob", "female/alice", {type: "married", _key: "bobAndAlice"}); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +If the collections of *from* and *to* are not defined in an edge definition of the graph, +the edge will not be stored. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionSave2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + | graph.relation.save( + | "relation/aliceAndBob", + | "female/alice", + {type: "married", _key: "bobAndAlice"}); // xpError(ERROR_GRAPH_INVALID_EDGE) +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_update.md b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_update.md index 446b9ebb4b..4b63da6a17 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_edge_collection_update.md +++ b/Documentation/DocuBlocks/JSF_general_graph_edge_collection_update.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_edge_collection_update -/// @brief Updates the data of an edge in collection edgeCollectionName -/// -/// `graph.edgeCollectionName.update(edgeId, data, options)` -/// -/// @PARAMS -/// -/// @PARAM{edgeId, string, required} -/// *_id* attribute of the edge -/// -/// @PARAM{data, object, required} -/// JSON data of the edge -/// -/// @PARAM{options, object, optional} -/// See [collection documentation](../Documents/DocumentMethods.md) -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionUpdate} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.relation.save("female/alice", "female/diana", {type: "knows", _key: "aliceAndDiana"}); -/// graph.relation.update("relation/aliceAndDiana", {type: "quarrelled", _key: "aliceAndDiana"}); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Updates the data of an edge in collection edgeCollectionName + +`graph.edgeCollectionName.update(edgeId, data, options)` + +@PARAMS + +@PARAM{edgeId, string, required} +*_id* attribute of the edge + +@PARAM{data, object, required} +JSON data of the edge + +@PARAM{options, object, optional} +See [collection documentation](../Documents/DocumentMethods.md) + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeCollectionUpdate} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.relation.save("female/alice", "female/diana", {type: "knows", _key: "aliceAndDiana"}); + graph.relation.update("relation/aliceAndDiana", {type: "quarrelled", _key: "aliceAndDiana"}); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_edge_definitions.md b/Documentation/DocuBlocks/JSF_general_graph_edge_definitions.md index 330fe1756e..14d77f6332 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_edge_definitions.md +++ b/Documentation/DocuBlocks/JSF_general_graph_edge_definitions.md @@ -1,25 +1,24 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_edge_definitions -/// @brief Create a list of edge definitions to construct a graph. -/// -/// `graph_module._edgeDefinitions(relation1, relation2, ..., relationN)` -/// -/// 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. -/// -/// @PARAMS -/// -/// @PARAM{relationX, object, optional} -/// An object representing a definition of one relation in the graph -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeDefinitions} -/// var graph_module = require("@arangodb/general-graph"); -/// directed_relation = graph_module._relation("lives_in", "user", "city"); -/// undirected_relation = graph_module._relation("knows", "user", "user"); -/// edgedefinitions = graph_module._edgeDefinitions(directed_relation, undirected_relation); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Create a list of edge definitions to construct a graph. + +`graph_module._edgeDefinitions(relation1, relation2, ..., relationN)` + +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. + +@PARAMS + +@PARAM{relationX, object, optional} +An object representing a definition of one relation in the graph + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeDefinitions} + var graph_module = require("@arangodb/general-graph"); + directed_relation = graph_module._relation("lives_in", "user", "city"); + undirected_relation = graph_module._relation("knows", "user", "user"); + edgedefinitions = graph_module._edgeDefinitions(directed_relation, undirected_relation); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_edges.md b/Documentation/DocuBlocks/JSF_general_graph_edges.md index f08f321b0c..49da6ad72a 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_edges.md +++ b/Documentation/DocuBlocks/JSF_general_graph_edges.md @@ -1,39 +1,38 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_edges -/// @brief Select some edges from the graph. -/// -/// `graph._edges(examples)` -/// -/// Creates an AQL statement to select a subset of the edges stored in the graph. -/// This is one of the entry points for the fluent AQL interface. -/// It will return a mutable AQL statement which can be further refined, using the -/// functions described below. -/// The resulting set of edges can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// In the examples the *toArray* function is used to print the result. -/// The description of this function can be found below. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph._edges().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered edges: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgesFiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph._edges({type: "married"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select some edges from the graph. + +`graph._edges(examples)` + +Creates an AQL statement to select a subset of the edges stored in the graph. +This is one of the entry points for the fluent AQL interface. +It will return a mutable AQL statement which can be further refined, using the +functions described below. +The resulting set of edges can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +In the examples the *toArray* function is used to print the result. +The description of this function can be found below. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph._edges().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered edges: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgesFiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph._edges({type: "married"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_extend_edge_definitions.md b/Documentation/DocuBlocks/JSF_general_graph_extend_edge_definitions.md index 4cc933cb33..d06533a2a3 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_extend_edge_definitions.md +++ b/Documentation/DocuBlocks/JSF_general_graph_extend_edge_definitions.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_extend_edge_definitions -/// @brief Extend the list of edge definitions to construct a graph. -/// -/// `graph_module._extendEdgeDefinitions(edgeDefinitions, relation1, relation2, ..., relationN)` -/// -/// 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. -/// -/// @PARAMS -/// -/// @PARAM{edgeDefinitions, array, required} -/// A list of relation definition objects. -/// -/// @PARAM{relationX, object, required} -/// An object representing a definition of one relation in the graph -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeDefinitionsExtend} -/// var graph_module = require("@arangodb/general-graph"); -/// directed_relation = graph_module._relation("lives_in", "user", "city"); -/// undirected_relation = graph_module._relation("knows", "user", "user"); -/// edgedefinitions = graph_module._edgeDefinitions(directed_relation); -/// edgedefinitions = graph_module._extendEdgeDefinitions(undirected_relation); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Extend the list of edge definitions to construct a graph. + +`graph_module._extendEdgeDefinitions(edgeDefinitions, relation1, relation2, ..., relationN)` + +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. + +@PARAMS + +@PARAM{edgeDefinitions, array, required} +A list of relation definition objects. + +@PARAM{relationX, object, required} +An object representing a definition of one relation in the graph + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphEdgeDefinitionsExtend} + var graph_module = require("@arangodb/general-graph"); + directed_relation = graph_module._relation("lives_in", "user", "city"); + undirected_relation = graph_module._relation("knows", "user", "user"); + edgedefinitions = graph_module._edgeDefinitions(directed_relation); + edgedefinitions = graph_module._extendEdgeDefinitions(undirected_relation); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_count.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_count.md index 09fd5b4582..476c680e29 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_count.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_count.md @@ -1,25 +1,24 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_count -/// @brief Returns the number of returned elements if the query is executed. -/// -/// `graph_query.count()` -/// -/// This function determines the amount of elements to be expected within the result of the query. -/// It can be used at the beginning of execution of the query -/// before using *next()* or in between *next()* calls. -/// The query object maintains a cursor of the query for you. -/// *count()* does not change the cursor position. -/// -/// @EXAMPLES -/// -/// To count the number of matched elements: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLCount} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices(); -/// query.count(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Returns the number of returned elements if the query is executed. + +`graph_query.count()` + +This function determines the amount of elements to be expected within the result of the query. +It can be used at the beginning of execution of the query +before using *next()* or in between *next()* calls. +The query object maintains a cursor of the query for you. +*count()* does not change the cursor position. + +@EXAMPLES + +To count the number of matched elements: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLCount} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices(); + query.count(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_edges.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_edges.md index 551eada0d9..31fd77267a 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_edges.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_edges.md @@ -1,53 +1,52 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_edges -/// @brief Select all edges for the vertices selected before. -/// -/// `graph_query.edges(examples)` -/// -/// Creates an AQL statement to select all edges for each of the vertices selected -/// in the step before. -/// This will include *inbound* as well as *outbound* edges. -/// The resulting set of edges can be filtered by defining one or more *examples*. -/// -/// The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the -/// parameter vertexExamplex, *m* the average amount of edges of a vertex and *x* the maximal depths. -/// Hence the default call would have a complexity of **O(n\*m)**; -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// To request unfiltered edges: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLEdgesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.edges().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered edges by a single example: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLEdgesFilteredSingle} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.edges({type: "married"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered edges by multiple examples: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLEdgesFilteredMultiple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.edges([{type: "married"}, {type: "friend"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select all edges for the vertices selected before. + +`graph_query.edges(examples)` + +Creates an AQL statement to select all edges for each of the vertices selected +in the step before. +This will include *inbound* as well as *outbound* edges. +The resulting set of edges can be filtered by defining one or more *examples*. + +The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the +parameter vertexExamplex, *m* the average amount of edges of a vertex and *x* the maximal depths. +Hence the default call would have a complexity of **O(n\*m)**; + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +To request unfiltered edges: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLEdgesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.edges().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered edges by a single example: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLEdgesFilteredSingle} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.edges({type: "married"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered edges by multiple examples: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLEdgesFilteredMultiple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.edges([{type: "married"}, {type: "friend"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_filter.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_filter.md index 2dd092498b..c7c2aecf10 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_filter.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_filter.md @@ -1,57 +1,56 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_filter -/// @brief Filter the result of the query -/// -/// `graph_query.filter(examples)` -/// -/// This can be used to further specfiy the expected result of the query. -/// The result set is reduced to the set of elements that matches the given *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// Request vertices unfiltered: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLUnfilteredVertices} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.toVertices().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Request vertices filtered: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFilteredVertices} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.toVertices().filter({name: "Alice"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Request edges unfiltered: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLUnfilteredEdges} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.toVertices().outEdges().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Request edges filtered: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFilteredEdges} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.toVertices().outEdges().filter({type: "married"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Filter the result of the query + +`graph_query.filter(examples)` + +This can be used to further specfiy the expected result of the query. +The result set is reduced to the set of elements that matches the given *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +Request vertices unfiltered: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLUnfilteredVertices} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.toVertices().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Request vertices filtered: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFilteredVertices} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.toVertices().filter({name: "Alice"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Request edges unfiltered: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLUnfilteredEdges} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.toVertices().outEdges().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Request edges filtered: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFilteredEdges} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.toVertices().outEdges().filter({type: "married"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_fromVertices.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_fromVertices.md index e3635e5531..111096fecc 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_fromVertices.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_fromVertices.md @@ -1,49 +1,48 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_fromVertices -/// @brief Select all source vertices of the edges selected before. -/// -/// `graph_query.fromVertices(examples)` -/// -/// Creates an AQL statement to select the set of vertices where the edges selected -/// in the step before start at. -/// This includes all vertices contained in *_from* attribute of the edges. -/// The resulting set of vertices can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// To request unfiltered source vertices: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFromVerticesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.fromVertices().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered source vertices by a single example: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFromVerticesFilteredSingle} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.fromVertices({name: "Alice"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered source vertices by multiple examples: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFromVerticesFilteredMultiple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.fromVertices([{name: "Alice"}, {name: "Charly"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select all source vertices of the edges selected before. + +`graph_query.fromVertices(examples)` + +Creates an AQL statement to select the set of vertices where the edges selected +in the step before start at. +This includes all vertices contained in *_from* attribute of the edges. +The resulting set of vertices can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +To request unfiltered source vertices: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFromVerticesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.fromVertices().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered source vertices by a single example: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFromVerticesFilteredSingle} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.fromVertices({name: "Alice"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered source vertices by multiple examples: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLFromVerticesFilteredMultiple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.fromVertices([{name: "Alice"}, {name: "Charly"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_hasNext.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_hasNext.md index 476a6fd016..e859ade8f5 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_hasNext.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_hasNext.md @@ -1,39 +1,38 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_hasNext -/// @brief Checks if the query has further results. -/// -/// `graph_query.hasNext()` -/// -/// The generated statement maintains a cursor for you. -/// If this cursor is already present *hasNext()* will -/// use this cursors position to determine if there are -/// further results available. -/// If the query has not yet been executed *hasNext()* -/// will execute it and create the cursor for you. -/// -/// @EXAMPLES -/// -/// Start query execution with hasNext: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLHasNext} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices(); -/// query.hasNext(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Iterate over the result as long as it has more elements: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLHasNextIteration} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices(); -/// | while (query.hasNext()) { -/// | var entry = query.next(); -/// | // Do something with the entry -/// } -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Checks if the query has further results. + +`graph_query.hasNext()` + +The generated statement maintains a cursor for you. +If this cursor is already present *hasNext()* will +use this cursors position to determine if there are +further results available. +If the query has not yet been executed *hasNext()* +will execute it and create the cursor for you. + +@EXAMPLES + +Start query execution with hasNext: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLHasNext} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices(); + query.hasNext(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Iterate over the result as long as it has more elements: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLHasNextIteration} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices(); +| while (query.hasNext()) { +| var entry = query.next(); +| // Do something with the entry + } +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_inEdges.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_inEdges.md index 6520df8332..d8ea8889cb 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_inEdges.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_inEdges.md @@ -1,49 +1,48 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_inEdges -/// @brief Select all inbound edges for the vertices selected before. -/// -/// `graph_query.inEdges(examples)` -/// -/// -/// Creates an AQL statement to select all *inbound* edges for each of the vertices selected -/// in the step before. -/// The resulting set of edges can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// To request unfiltered inbound edges: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLInEdgesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.inEdges().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered inbound edges by a single example: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLInEdgesFilteredSingle} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.inEdges({type: "married"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered inbound edges by multiple examples: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLInEdgesFilteredMultiple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.inEdges([{type: "married"}, {type: "friend"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select all inbound edges for the vertices selected before. + +`graph_query.inEdges(examples)` + + +Creates an AQL statement to select all *inbound* edges for each of the vertices selected +in the step before. +The resulting set of edges can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +To request unfiltered inbound edges: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLInEdgesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.inEdges().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered inbound edges by a single example: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLInEdgesFilteredSingle} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.inEdges({type: "married"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered inbound edges by multiple examples: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLInEdgesFilteredMultiple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.inEdges([{type: "married"}, {type: "friend"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_neighbors.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_neighbors.md index ae31547fb7..6889ced11b 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_neighbors.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_neighbors.md @@ -1,59 +1,58 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_neighbors -/// @brief Select all neighbors of the vertices selected in the step before. -/// -/// `graph_query.neighbors(examples, options)` -/// -/// Creates an AQL statement to select all neighbors for each of the vertices selected -/// in the step before. -/// The resulting set of vertices can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeExamples*: Filter the edges to be followed, see [Definition of examples](#definition-of-examples) -/// * *edgeCollectionRestriction* : One or a list of edge-collection names that should be -/// considered to be on the path. -/// * *vertexCollectionRestriction* : One or a list of vertex-collection names that should be -/// considered on the intermediate vertex steps. -/// * *minDepth*: Defines the minimal number of intermediate steps to neighbors (default is 1). -/// * *maxDepth*: Defines the maximal number of intermediate steps to neighbors (default is 1). -/// -/// @EXAMPLES -/// -/// To request unfiltered neighbors: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNeighborsUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices({name: "Alice"}); -/// query.neighbors().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered neighbors by a single example: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNeighborsFilteredSingle} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices({name: "Alice"}); -/// query.neighbors({name: "Bob"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered neighbors by multiple examples: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNeighborsFilteredMultiple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.vertices([{name: "Bob"}, {name: "Charly"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select all neighbors of the vertices selected in the step before. + +`graph_query.neighbors(examples, options)` + +Creates an AQL statement to select all neighbors for each of the vertices selected +in the step before. +The resulting set of vertices can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@PARAM{options, object, optional} + An object defining further options. Can have the following values: + * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *edgeExamples*: Filter the edges to be followed, see [Definition of examples](#definition-of-examples) + * *edgeCollectionRestriction* : One or a list of edge-collection names that should be + considered to be on the path. + * *vertexCollectionRestriction* : One or a list of vertex-collection names that should be + considered on the intermediate vertex steps. + * *minDepth*: Defines the minimal number of intermediate steps to neighbors (default is 1). + * *maxDepth*: Defines the maximal number of intermediate steps to neighbors (default is 1). + +@EXAMPLES + +To request unfiltered neighbors: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNeighborsUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices({name: "Alice"}); + query.neighbors().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered neighbors by a single example: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNeighborsFilteredSingle} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices({name: "Alice"}); + query.neighbors({name: "Bob"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered neighbors by multiple examples: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNeighborsFilteredMultiple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.vertices([{name: "Bob"}, {name: "Charly"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_next.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_next.md index 923b4803b1..c1d2f2ac62 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_next.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_next.md @@ -1,42 +1,41 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_next -/// @brief Request the next element in the result. -/// -/// `graph_query.next()` -/// -/// The generated statement maintains a cursor for you. -/// If this cursor is already present *next()* will -/// use this cursors position to deliver the next result. -/// Also the cursor position will be moved by one. -/// If the query has not yet been executed *next()* -/// will execute it and create the cursor for you. -/// It will throw an error of your query has no further results. -/// -/// @EXAMPLES -/// -/// Request some elements with next: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNext} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices(); -/// query.next(); -/// query.next(); -/// query.next(); -/// query.next(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// The cursor is recreated if the query is changed: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNextRecreate} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices(); -/// query.next(); -/// query.edges(); -/// query.next(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Request the next element in the result. + +`graph_query.next()` + +The generated statement maintains a cursor for you. +If this cursor is already present *next()* will +use this cursors position to deliver the next result. +Also the cursor position will be moved by one. +If the query has not yet been executed *next()* +will execute it and create the cursor for you. +It will throw an error of your query has no further results. + +@EXAMPLES + +Request some elements with next: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNext} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices(); + query.next(); + query.next(); + query.next(); + query.next(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +The cursor is recreated if the query is changed: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLNextRecreate} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices(); + query.next(); + query.edges(); + query.next(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_outEdges.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_outEdges.md index ec77d2d756..31894f9885 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_outEdges.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_outEdges.md @@ -1,48 +1,47 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_outEdges -/// @brief Select all outbound edges for the vertices selected before. -/// -/// `graph_query.outEdges(examples)` -/// -/// Creates an AQL statement to select all *outbound* edges for each of the vertices selected -/// in the step before. -/// The resulting set of edges can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// To request unfiltered outbound edges: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLOutEdgesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.outEdges().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered outbound edges by a single example: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLOutEdgesFilteredSingle} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.outEdges({type: "married"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered outbound edges by multiple examples: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLOutEdgesFilteredMultiple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); -/// query.outEdges([{type: "married"}, {type: "friend"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select all outbound edges for the vertices selected before. + +`graph_query.outEdges(examples)` + +Creates an AQL statement to select all *outbound* edges for each of the vertices selected +in the step before. +The resulting set of edges can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +To request unfiltered outbound edges: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLOutEdgesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.outEdges().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered outbound edges by a single example: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLOutEdgesFilteredSingle} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.outEdges({type: "married"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered outbound edges by multiple examples: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLOutEdgesFilteredMultiple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices([{name: "Alice"}, {name: "Bob"}]); + query.outEdges([{type: "married"}, {type: "friend"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_path.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_path.md index a7d4d3b0bf..b68383a274 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_path.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_path.md @@ -1,34 +1,33 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_path -/// @brief The result of the query is the path to all elements. -/// -/// `graph_query.path()` -/// -/// By defaut the result of the generated AQL query is the set of elements passing the last matches. -/// So having a `vertices()` query as the last step the result will be set of vertices. -/// Using `path()` as the last action before requesting the result -/// will modify the result such that the path required to find the set vertices is returned. -/// -/// @EXAMPLES -/// -/// Request the iteratively explored path using vertices and edges: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLPathSimple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices({name: "Alice"}); -/// query.outEdges().toVertices().path().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// When requesting neighbors the path to these neighbors is expanded: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLPathNeighbors} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices({name: "Alice"}); -/// query.neighbors().path().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief The result of the query is the path to all elements. + +`graph_query.path()` + +By defaut the result of the generated AQL query is the set of elements passing the last matches. +So having a `vertices()` query as the last step the result will be set of vertices. +Using `path()` as the last action before requesting the result +will modify the result such that the path required to find the set vertices is returned. + +@EXAMPLES + +Request the iteratively explored path using vertices and edges: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLPathSimple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices({name: "Alice"}); + query.outEdges().toVertices().path().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +When requesting neighbors the path to these neighbors is expanded: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLPathNeighbors} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices({name: "Alice"}); + query.neighbors().path().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_restrict.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_restrict.md index 6b9c60fc26..1d734e161e 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_restrict.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_restrict.md @@ -1,53 +1,52 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_restrict -/// @brief Restricts the last statement in the chain to return -/// only elements of a specified set of collections -/// -/// `graph_query.restrict(restrictions)` -/// -/// By default all collections in the graph are searched for matching elements -/// whenever vertices and edges are requested. -/// Using *restrict* after such a statement allows to restrict the search -/// to a specific set of collections within the graph. -/// Restriction is only applied to this one part of the query. -/// It does not effect earlier or later statements. -/// -/// @PARAMS -/// -/// @PARAM{restrictions, array, optional} -/// Define either one or a list of collections in the graph. -/// Only elements from these collections are taken into account for the result. -/// -/// @EXAMPLES -/// -/// Request all directly connected vertices unrestricted: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLUnrestricted} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices({name: "Alice"}); -/// query.edges().vertices().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Apply a restriction to the directly connected vertices: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLRestricted} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices({name: "Alice"}); -/// query.edges().vertices().restrict("female").toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Restriction of a query is only valid for collections known to the graph: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLRestrictedUnknown} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices({name: "Alice"}); -/// query.edges().vertices().restrict(["female", "male", "products"]).toArray(); // xpError(ERROR_BAD_PARAMETER); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Restricts the last statement in the chain to return +only elements of a specified set of collections + +`graph_query.restrict(restrictions)` + +By default all collections in the graph are searched for matching elements +whenever vertices and edges are requested. +Using *restrict* after such a statement allows to restrict the search +to a specific set of collections within the graph. +Restriction is only applied to this one part of the query. +It does not effect earlier or later statements. + +@PARAMS + +@PARAM{restrictions, array, optional} +Define either one or a list of collections in the graph. +Only elements from these collections are taken into account for the result. + +@EXAMPLES + +Request all directly connected vertices unrestricted: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLUnrestricted} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices({name: "Alice"}); + query.edges().vertices().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Apply a restriction to the directly connected vertices: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLRestricted} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices({name: "Alice"}); + query.edges().vertices().restrict("female").toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Restriction of a query is only valid for collections known to the graph: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLRestrictedUnknown} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices({name: "Alice"}); + query.edges().vertices().restrict(["female", "male", "products"]).toArray(); // xpError(ERROR_BAD_PARAMETER); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toArray.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toArray.md index 6592c89855..cccb4570ad 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toArray.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toArray.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_toArray -/// @brief Returns an array containing the complete result. -/// -/// `graph_query.toArray()` -/// -/// This function executes the generated query and returns the -/// entire result as one array. -/// ToArray does not return the generated query anymore and -/// hence can only be the endpoint of a query. -/// However keeping a reference to the query before -/// executing allows to chain further statements to it. -/// -/// @EXAMPLES -/// -/// To collect the entire result of a query toArray can be used: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToArray} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._vertices(); -/// query.toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Returns an array containing the complete result. + +`graph_query.toArray()` + +This function executes the generated query and returns the +entire result as one array. +ToArray does not return the generated query anymore and +hence can only be the endpoint of a query. +However keeping a reference to the query before +executing allows to chain further statements to it. + +@EXAMPLES + +To collect the entire result of a query toArray can be used: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToArray} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._vertices(); + query.toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toVertices.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toVertices.md index b3c61686ab..6c9cb9681f 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toVertices.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_toVertices.md @@ -1,49 +1,48 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_toVertices -/// @brief Select all vertices targeted by the edges selected before. -/// -/// `graph_query.toVertices(examples)` -/// -/// Creates an AQL statement to select the set of vertices where the edges selected -/// in the step before end in. -/// This includes all vertices contained in *_to* attribute of the edges. -/// The resulting set of vertices can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// To request unfiltered target vertices: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToVerticesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.toVertices().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered target vertices by a single example: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToVerticesFilteredSingle} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.toVertices({name: "Bob"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered target vertices by multiple examples: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToVerticesFilteredMultiple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.toVertices([{name: "Bob"}, {name: "Diana"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select all vertices targeted by the edges selected before. + +`graph_query.toVertices(examples)` + +Creates an AQL statement to select the set of vertices where the edges selected +in the step before end in. +This includes all vertices contained in *_to* attribute of the edges. +The resulting set of vertices can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +To request unfiltered target vertices: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToVerticesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.toVertices().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered target vertices by a single example: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToVerticesFilteredSingle} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.toVertices({name: "Bob"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered target vertices by multiple examples: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLToVerticesFilteredMultiple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.toVertices([{name: "Bob"}, {name: "Diana"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_vertices.md b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_vertices.md index 3d9ff8fc89..184f10bd30 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_vertices.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fluent_aql_vertices.md @@ -1,49 +1,48 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fluent_aql_vertices -/// @brief Select all vertices connected to the edges selected before. -/// -/// `graph_query.vertices(examples)` -/// -/// Creates an AQL statement to select all vertices for each of the edges selected -/// in the step before. -/// This includes all vertices contained in *_from* as well as *_to* attribute of the edges. -/// The resulting set of vertices can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// To request unfiltered vertices: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLVerticesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.vertices().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered vertices by a single example: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLVerticesFilteredSingle} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.vertices({name: "Alice"}).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered vertices by multiple examples: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLVerticesFilteredMultiple} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// var query = graph._edges({type: "married"}); -/// query.vertices([{name: "Alice"}, {name: "Charly"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select all vertices connected to the edges selected before. + +`graph_query.vertices(examples)` + +Creates an AQL statement to select all vertices for each of the edges selected +in the step before. +This includes all vertices contained in *_from* as well as *_to* attribute of the edges. +The resulting set of vertices can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +To request unfiltered vertices: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLVerticesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.vertices().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered vertices by a single example: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLVerticesFilteredSingle} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.vertices({name: "Alice"}).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered vertices by multiple examples: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphFluentAQLVerticesFilteredMultiple} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + var query = graph._edges({type: "married"}); + query.vertices([{name: "Alice"}, {name: "Charly"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_fromVertex.md b/Documentation/DocuBlocks/JSF_general_graph_fromVertex.md index 8ff864f266..24ced69211 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_fromVertex.md +++ b/Documentation/DocuBlocks/JSF_general_graph_fromVertex.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_fromVertex -/// @brief Get the source vertex of an edge -/// -/// `graph._fromVertex(edgeId)` -/// -/// Returns the vertex defined with the attribute *_from* of the edge with *edgeId* as its *_id*. -/// -/// @PARAMS -/// -/// @PARAM{edgeId, string, required} -/// *_id* attribute of the edge -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphGetFromVertex} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph._fromVertex("relation/aliceAndBob") -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the source vertex of an edge + +`graph._fromVertex(edgeId)` + +Returns the vertex defined with the attribute *_from* of the edge with *edgeId* as its *_id*. + +@PARAMS + +@PARAM{edgeId, string, required} +*_id* attribute of the edge + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphGetFromVertex} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph._fromVertex("relation/aliceAndBob") +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_graph.md b/Documentation/DocuBlocks/JSF_general_graph_graph.md index b01de24b20..080fba631e 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_graph.md +++ b/Documentation/DocuBlocks/JSF_general_graph_graph.md @@ -1,27 +1,26 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_graph -/// @brief Get a graph -/// -/// `graph_module._graph(graphName)` -/// -/// A graph can be retrieved by its name. -/// -/// @PARAMS -/// -/// @PARAM{graphName, string, required} -/// Unique identifier of the graph -/// -/// @EXAMPLES -/// -/// Get a graph: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphLoadGraph} -/// ~ var examples = require("@arangodb/graph-examples/example-graph.js"); -/// ~ var g1 = examples.loadGraph("social"); -/// var graph_module = require("@arangodb/general-graph"); -/// graph = graph_module._graph("social"); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get a graph + +`graph_module._graph(graphName)` + +A graph can be retrieved by its name. + +@PARAMS + +@PARAM{graphName, string, required} +Unique identifier of the graph + +@EXAMPLES + +Get a graph: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphLoadGraph} +~ var examples = require("@arangodb/graph-examples/example-graph.js"); +~ var g1 = examples.loadGraph("social"); + var graph_module = require("@arangodb/general-graph"); + graph = graph_module._graph("social"); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_how_to_create.md b/Documentation/DocuBlocks/JSF_general_graph_how_to_create.md index 061267529e..4b95b9ea23 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_how_to_create.md +++ b/Documentation/DocuBlocks/JSF_general_graph_how_to_create.md @@ -1,37 +1,36 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_how_to_create -/// -/// * Create a graph -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphHowTo1} -/// var graph_module = require("@arangodb/general-graph"); -/// var graph = graph_module._create("myGraph"); -/// graph; -/// ~ graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// * Add some vertex collections -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphHowTo2} -/// ~ var graph_module = require("@arangodb/general-graph"); -/// ~ var graph = graph_module._create("myGraph"); -/// graph._addVertexCollection("shop"); -/// graph._addVertexCollection("customer"); -/// graph._addVertexCollection("pet"); -/// graph; -/// ~ graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// * Define relations on the -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphHowTo3} -/// ~ var graph_module = require("@arangodb/general-graph"); -/// ~ var graph = graph_module._create("myGraph"); -/// var rel = graph_module._relation("isCustomer", ["shop"], ["customer"]); -/// graph._extendEdgeDefinitions(rel); -/// graph; -/// ~ graph_module._drop("myGraph", true); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +* Create a graph + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphHowTo1} + var graph_module = require("@arangodb/general-graph"); + var graph = graph_module._create("myGraph"); + graph; +~ graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + +* Add some vertex collections + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphHowTo2} +~ var graph_module = require("@arangodb/general-graph"); +~ var graph = graph_module._create("myGraph"); + graph._addVertexCollection("shop"); + graph._addVertexCollection("customer"); + graph._addVertexCollection("pet"); + graph; +~ graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + +* Define relations on the + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphCreateGraphHowTo3} +~ var graph_module = require("@arangodb/general-graph"); +~ var graph = graph_module._create("myGraph"); + var rel = graph_module._relation("isCustomer", ["shop"], ["customer"]); + graph._extendEdgeDefinitions(rel); + graph; +~ graph_module._drop("myGraph", true); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_list.md b/Documentation/DocuBlocks/JSF_general_graph_list.md index c32d8c0f48..0988882a9a 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_list.md +++ b/Documentation/DocuBlocks/JSF_general_graph_list.md @@ -1,16 +1,15 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_list -/// @brief List all graphs. -/// -/// `graph_module._list()` -/// -/// Lists all graph names stored in this database. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphList} -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._list(); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief List all graphs. + +`graph_module._list()` + +Lists all graph names stored in this database. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphList} + var graph_module = require("@arangodb/general-graph"); + graph_module._list(); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_neighbors.md b/Documentation/DocuBlocks/JSF_general_graph_neighbors.md index 37ecf66c3e..041ee5dc5b 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_neighbors.md +++ b/Documentation/DocuBlocks/JSF_general_graph_neighbors.md @@ -1,50 +1,49 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_neighbors -/// @brief Get all neighbors of the vertices defined by the example -/// -/// `graph._neighbors(vertexExample, options)` -/// -/// The function accepts an id, an example, a list of examples or even an empty -/// example as parameter for vertexExample. -/// The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the -/// parameter vertexExamplex, *m* the average amount of neighbors and *x* the maximal depths. -/// Hence the default call would have a complexity of **O(n\*m)**; -/// -/// @PARAMS -/// -/// @PARAM{vertexExample, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeExamples*: Filter the edges, see [Definition of examples](#definition-of-examples) -/// * *neighborExamples*: Filter the neighbor vertices, see [Definition of examples](#definition-of-examples) -/// * *edgeCollectionRestriction* : One or a list of edge-collection names that should be -/// considered to be on the path. -/// * *vertexCollectionRestriction* : One or a list of vertex-collection names that should be -/// considered on the intermediate vertex steps. -/// * *minDepth*: Defines the minimal number of intermediate steps to neighbors (default is 1). -/// * *maxDepth*: Defines the maximal number of intermediate steps to neighbors (default is 1). -/// -/// @EXAMPLES -/// -/// A route planner example, all neighbors of capitals. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleNeighbors1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._neighbors({isCapital : true}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, all outbound neighbors of Hamburg. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleNeighbors2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._neighbors('germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get all neighbors of the vertices defined by the example + +`graph._neighbors(vertexExample, options)` + +The function accepts an id, an example, a list of examples or even an empty +example as parameter for vertexExample. +The complexity of this method is **O(n\*m^x)** with *n* being the vertices defined by the +parameter vertexExamplex, *m* the average amount of neighbors and *x* the maximal depths. +Hence the default call would have a complexity of **O(n\*m)**; + +@PARAMS + +@PARAM{vertexExample, object, optional} +See [Definition of examples](#definition-of-examples) +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *edgeExamples*: Filter the edges, see [Definition of examples](#definition-of-examples) + * *neighborExamples*: Filter the neighbor vertices, see [Definition of examples](#definition-of-examples) + * *edgeCollectionRestriction* : One or a list of edge-collection names that should be + considered to be on the path. + * *vertexCollectionRestriction* : One or a list of vertex-collection names that should be + considered on the intermediate vertex steps. + * *minDepth*: Defines the minimal number of intermediate steps to neighbors (default is 1). + * *maxDepth*: Defines the maximal number of intermediate steps to neighbors (default is 1). + +@EXAMPLES + +A route planner example, all neighbors of capitals. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleNeighbors1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._neighbors({isCapital : true}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, all outbound neighbors of Hamburg. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleNeighbors2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._neighbors('germanCity/Hamburg', {direction : 'outbound', maxDepth : 2}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_paths.md b/Documentation/DocuBlocks/JSF_general_graph_paths.md index 067b1edf61..f3bcf1e60b 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_paths.md +++ b/Documentation/DocuBlocks/JSF_general_graph_paths.md @@ -1,46 +1,45 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_paths -/// @brief The _paths function returns all paths of a graph. -/// -/// `graph._paths(options)` -/// -/// This function determines all available paths in a graph. -/// -/// The complexity of this method is **O(n\*n\*m)** with *n* being the amount of vertices in -/// the graph and *m* the average amount of connected edges; -/// -/// @PARAMS -/// -/// @PARAM{options, object, optional} -/// An object containing options, see below: -/// * *direction* : The direction of the edges. Possible values are *any*, -/// *inbound* and *outbound* (default). -/// * *followCycles* (optional) : If set to *true* the query follows cycles in the graph, -/// default is false. -/// * *minLength* (optional) : Defines the minimal length a path must -/// have to be returned (default is 0). -/// * *maxLength* (optional) : Defines the maximal length a path must -/// have to be returned (default is 10). -/// -/// @EXAMPLES -/// -/// Return all paths of the graph "social": -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModulePaths} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("social"); -/// g._paths(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Return all inbound paths of the graph "social" with a maximal -/// length of 1 and a minimal length of 2: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModulePaths2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("social"); -/// g._paths({direction : 'inbound', minLength : 1, maxLength : 2}); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief The _paths function returns all paths of a graph. + +`graph._paths(options)` + +This function determines all available paths in a graph. + +The complexity of this method is **O(n\*n\*m)** with *n* being the amount of vertices in +the graph and *m* the average amount of connected edges; + +@PARAMS + +@PARAM{options, object, optional} +An object containing options, see below: + * *direction* : The direction of the edges. Possible values are *any*, + *inbound* and *outbound* (default). + * *followCycles* (optional) : If set to *true* the query follows cycles in the graph, + default is false. + * *minLength* (optional) : Defines the minimal length a path must + have to be returned (default is 0). + * *maxLength* (optional) : Defines the maximal length a path must + have to be returned (default is 10). + +@EXAMPLES + +Return all paths of the graph "social": + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModulePaths} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("social"); + g._paths(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Return all inbound paths of the graph "social" with a maximal +length of 1 and a minimal length of 2: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModulePaths2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("social"); + g._paths({direction : 'inbound', minLength : 1, maxLength : 2}); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_radius.md b/Documentation/DocuBlocks/JSF_general_graph_radius.md index 0b02c641b3..e881dc401f 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_radius.md +++ b/Documentation/DocuBlocks/JSF_general_graph_radius.md @@ -1,59 +1,58 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_radius -/// @brief Get the -/// [radius](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) -/// of a graph. -/// -/// `graph._radius(options)` -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @PARAMS -/// -/// @PARAM{options, object, optional} -/// An object defining further options. Can have the following values: -/// * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). -/// * *algorithm*: The algorithm to calculate the shortest paths, possible values are -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and -/// [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). -/// * *weight*: The name of the attribute of the edges containing the weight. -/// * *defaultWeight*: Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as weight. -/// If no default is supplied the default would be positive infinity so the path and -/// hence the radius can not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, the radius of the graph. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleRadius1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._radius(); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the radius of the graph. -/// This considers the actual distances. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleRadius2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._radius({weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, the radius of the graph regarding only -/// outbound paths. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleRadius3} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("routeplanner"); -/// graph._radius({direction : 'outbound', weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the +[radius](http://en.wikipedia.org/wiki/Eccentricity_%28graph_theory%29) +of a graph. + +`graph._radius(options)` + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@PARAMS + +@PARAM{options, object, optional} +An object defining further options. Can have the following values: + * *direction*: The direction of the edges. Possible values are *outbound*, *inbound* and *any* (default). + * *algorithm*: The algorithm to calculate the shortest paths, possible values are + [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) and + [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm). + * *weight*: The name of the attribute of the edges containing the weight. + * *defaultWeight*: Only used with the option *weight*. + If an edge does not have the attribute named as defined in option *weight* this default + is used as weight. + If no default is supplied the default would be positive infinity so the path and + hence the radius can not be calculated. + +@EXAMPLES + +A route planner example, the radius of the graph. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleRadius1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._radius(); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the radius of the graph. +This considers the actual distances. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleRadius2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._radius({weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, the radius of the graph regarding only +outbound paths. + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleRadius3} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("routeplanner"); + graph._radius({direction : 'outbound', weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_relation.md b/Documentation/DocuBlocks/JSF_general_graph_relation.md index bd57c63a4d..056fbe7e3c 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_relation.md +++ b/Documentation/DocuBlocks/JSF_general_graph_relation.md @@ -1,40 +1,39 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_relation -/// @brief Define a directed relation. -/// -/// `graph_module._relation(relationName, fromVertexCollections, toVertexCollections)` -/// -/// 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*. -/// -/// @PARAMS -/// -/// @PARAM{relationName, string, required} -/// The name of the edge collection where the edges should be stored. -/// Will be created if it does not yet exist. -/// -/// @PARAM{fromVertexCollections, array, required} -/// One or a list of collection names. Source vertices for the edges -/// have to be stored in these collections. Collections will be created if they do not exist. -/// -/// @PARAM{toVertexCollections, array, required} -/// One or a list of collection names. Target vertices for the edges -/// have to be stored in these collections. Collections will be created if they do not exist. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRelationDefinition} -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._relation("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphRelationDefinitionSingle} -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._relation("has_bought", "Customer", "Product"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Define a directed relation. + +`graph_module._relation(relationName, fromVertexCollections, toVertexCollections)` + +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*. + +@PARAMS + +@PARAM{relationName, string, required} + The name of the edge collection where the edges should be stored. + Will be created if it does not yet exist. + +@PARAM{fromVertexCollections, array, required} + One or a list of collection names. Source vertices for the edges + have to be stored in these collections. Collections will be created if they do not exist. + +@PARAM{toVertexCollections, array, required} + One or a list of collection names. Target vertices for the edges + have to be stored in these collections. Collections will be created if they do not exist. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRelationDefinition} + var graph_module = require("@arangodb/general-graph"); + graph_module._relation("has_bought", ["Customer", "Company"], ["Groceries", "Electronics"]); +@END_EXAMPLE_ARANGOSH_OUTPUT + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphRelationDefinitionSingle} + var graph_module = require("@arangodb/general-graph"); + graph_module._relation("has_bought", "Customer", "Product"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_shortest_path.md b/Documentation/DocuBlocks/JSF_general_graph_shortest_path.md index d94c1c1dfc..7751935197 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_shortest_path.md +++ b/Documentation/DocuBlocks/JSF_general_graph_shortest_path.md @@ -1,84 +1,83 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_shortest_path -/// @brief The _shortestPath function returns all shortest paths of a graph. -/// -/// `graph._shortestPath(startVertexExample, endVertexExample, options)` -/// -/// This function determines all shortest paths in a graph. -/// The function accepts an id, an example, a list of examples -/// or even an empty example as parameter for -/// start and end vertex. If one wants to call this function to receive nearly all -/// shortest paths for a graph the option *algorithm* should be set to -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) -/// to increase performance. -/// If no algorithm is provided in the options the function chooses the appropriate -/// one (either [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) -/// or [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)) according to its parameters. -/// The length of a path is by default the amount of edges from one start vertex to -/// an end vertex. The option weight allows the user to define an edge attribute -/// representing the length. -/// -/// The complexity of the function is described -/// [here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). -/// -/// @PARAMS -/// -/// @PARAM{startVertexExample, object, optional} -/// An example for the desired start Vertices -/// (see [Definition of examples](#definition-of-examples)). -/// -/// @PARAM{endVertexExample, object, optional} -/// An example for the desired -/// end Vertices (see [Definition of examples](#definition-of-examples)). -/// -/// @PARAM{options, object, optional} -/// An object containing options, see below: -/// * *direction* : The direction of the edges as a string. -/// Possible values are *outbound*, *inbound* and *any* (default). -/// * *edgeCollectionRestriction* : One or multiple edge -/// collection names. Only edges from these collections will be considered for the path. -/// * *startVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// start vertex of a path. -/// * *endVertexCollectionRestriction* : One or multiple vertex -/// collection names. Only vertices from these collections will be considered as -/// end vertex of a path. -/// * *edgeExamples* : A filter example for the -/// edges in the shortest paths -/// (see [example](#definition-of-examples)). -/// * *algorithm* : The algorithm to calculate -/// the shortest paths. If both start and end vertex examples are empty -/// [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is -/// used, otherwise the default is [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm) -/// * *weight* : The name of the attribute of -/// the edges containing the length as a string. -/// * *defaultWeight* : Only used with the option *weight*. -/// If an edge does not have the attribute named as defined in option *weight* this default -/// is used as length. -/// If no default is supplied the default would be positive Infinity so the path could -/// not be calculated. -/// -/// @EXAMPLES -/// -/// A route planner example, shortest path from all german to all french cities: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleShortestPaths1} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | g._shortestPath({}, {}, {weight : 'distance', endVertexCollectionRestriction : 'frenchCity', -/// startVertexCollectionRestriction : 'germanCity'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// A route planner example, shortest path from Hamburg and Cologne to Lyon: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleShortestPaths2} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var g = examples.loadGraph("routeplanner"); -/// | g._shortestPath([{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], 'frenchCity/Lyon', -/// {weight : 'distance'}); -/// ~ examples.dropGraph("routeplanner"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief The _shortestPath function returns all shortest paths of a graph. + +`graph._shortestPath(startVertexExample, endVertexExample, options)` + +This function determines all shortest paths in a graph. +The function accepts an id, an example, a list of examples +or even an empty example as parameter for +start and end vertex. If one wants to call this function to receive nearly all +shortest paths for a graph the option *algorithm* should be set to +[Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) +to increase performance. +If no algorithm is provided in the options the function chooses the appropriate +one (either [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) +or [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm)) according to its parameters. +The length of a path is by default the amount of edges from one start vertex to +an end vertex. The option weight allows the user to define an edge attribute +representing the length. + +The complexity of the function is described +[here](../Aql/GraphOperations.md#the-complexity-of-the-shortest-path-algorithms). + +@PARAMS + +@PARAM{startVertexExample, object, optional} +An example for the desired start Vertices +(see [Definition of examples](#definition-of-examples)). + +@PARAM{endVertexExample, object, optional} +An example for the desired +end Vertices (see [Definition of examples](#definition-of-examples)). + +@PARAM{options, object, optional} +An object containing options, see below: + * *direction* : The direction of the edges as a string. + Possible values are *outbound*, *inbound* and *any* (default). + * *edgeCollectionRestriction* : One or multiple edge + collection names. Only edges from these collections will be considered for the path. + * *startVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + start vertex of a path. + * *endVertexCollectionRestriction* : One or multiple vertex + collection names. Only vertices from these collections will be considered as + end vertex of a path. + * *edgeExamples* : A filter example for the + edges in the shortest paths + (see [example](#definition-of-examples)). + * *algorithm* : The algorithm to calculate + the shortest paths. If both start and end vertex examples are empty + [Floyd-Warshall](http://en.wikipedia.org/wiki/Floyd%E2%80%93Warshall_algorithm) is + used, otherwise the default is [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm) + * *weight* : The name of the attribute of + the edges containing the length as a string. + * *defaultWeight* : Only used with the option *weight*. + If an edge does not have the attribute named as defined in option *weight* this default + is used as length. + If no default is supplied the default would be positive Infinity so the path could + not be calculated. + +@EXAMPLES + +A route planner example, shortest path from all german to all french cities: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleShortestPaths1} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| g._shortestPath({}, {}, {weight : 'distance', endVertexCollectionRestriction : 'frenchCity', + startVertexCollectionRestriction : 'germanCity'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +A route planner example, shortest path from Hamburg and Cologne to Lyon: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphModuleShortestPaths2} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var g = examples.loadGraph("routeplanner"); +| g._shortestPath([{_id: 'germanCity/Cologne'},{_id: 'germanCity/Munich'}], 'frenchCity/Lyon', + {weight : 'distance'}); +~ examples.dropGraph("routeplanner"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_toVertex.md b/Documentation/DocuBlocks/JSF_general_graph_toVertex.md index 442837f4c3..6d14739bbf 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_toVertex.md +++ b/Documentation/DocuBlocks/JSF_general_graph_toVertex.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_toVertex -/// @brief Get the target vertex of an edge -/// -/// `graph._toVertex(edgeId)` -/// -/// Returns the vertex defined with the attribute *_to* of the edge with *edgeId* as its *_id*. -/// -/// @PARAMS -/// -/// @PARAM{edgeId, string, required} -/// *_id* attribute of the edge -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphGetToVertex} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph._toVertex("relation/aliceAndBob") -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Get the target vertex of an edge + +`graph._toVertex(edgeId)` + +Returns the vertex defined with the attribute *_to* of the edge with *edgeId* as its *_id*. + +@PARAMS + +@PARAM{edgeId, string, required} +*_id* attribute of the edge + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphGetToVertex} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph._toVertex("relation/aliceAndBob") +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_undirectedRelation.md b/Documentation/DocuBlocks/JSF_general_graph_undirectedRelation.md index 1f0fdc3c7a..4e65544fee 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_undirectedRelation.md +++ b/Documentation/DocuBlocks/JSF_general_graph_undirectedRelation.md @@ -1,38 +1,37 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_undirectedRelation -/// @brief Define an undirected relation. -/// -/// `graph_module._undirectedRelation(relationName, vertexCollections)` -/// -/// 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*. -/// -/// @PARAMS -/// -/// @PARAM{relationName, string, required} -/// The name of the edge collection where the edges should be stored. -/// Will be created if it does not yet exist. -/// -/// @PARAM{vertexCollections, array, required} -/// One or a list of collection names for which connections are allowed. -/// Will be created if they do not exist. -/// -/// @EXAMPLES -/// -/// To define simple relation with only one vertex collection: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphUndirectedRelationDefinition1} -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._undirectedRelation("friend", "user"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To define a relation between several vertex collections: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphUndirectedRelationDefinition2} -/// var graph_module = require("@arangodb/general-graph"); -/// graph_module._undirectedRelation("marriage", ["female", "male"]); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Define an undirected relation. + +`graph_module._undirectedRelation(relationName, vertexCollections)` + +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*. + +@PARAMS + +@PARAM{relationName, string, required} + The name of the edge collection where the edges should be stored. + Will be created if it does not yet exist. + +@PARAM{vertexCollections, array, required} + One or a list of collection names for which connections are allowed. + Will be created if they do not exist. + +@EXAMPLES + +To define simple relation with only one vertex collection: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphUndirectedRelationDefinition1} + var graph_module = require("@arangodb/general-graph"); + graph_module._undirectedRelation("friend", "user"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To define a relation between several vertex collections: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphUndirectedRelationDefinition2} + var graph_module = require("@arangodb/general-graph"); + graph_module._undirectedRelation("marriage", ["female", "male"]); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_remove.md b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_remove.md index 89934e1ca2..8d3416a97e 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_remove.md +++ b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_remove.md @@ -1,31 +1,30 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_vertex_collection_remove -/// @brief Removes a vertex in collection *vertexCollectionName* -/// -/// `graph.vertexCollectionName.remove(vertexId, options)` -/// -/// Additionally removes all ingoing and outgoing edges of the vertex recursively -/// (see [edge remove](#remove-an-edge)). -/// -/// @PARAMS -/// -/// @PARAM{vertexId, string, required} -/// *_id* attribute of the vertex -/// -/// @PARAM{options, object, optional} -/// See [collection documentation](../Documents/DocumentMethods.md) -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionRemove} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.male.save({name: "Kermit", _key: "kermit"}); -/// db._exists("male/kermit") -/// graph.male.remove("male/kermit") -/// db._exists("male/kermit") -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Removes a vertex in collection *vertexCollectionName* + +`graph.vertexCollectionName.remove(vertexId, options)` + +Additionally removes all ingoing and outgoing edges of the vertex recursively +(see [edge remove](#remove-an-edge)). + +@PARAMS + +@PARAM{vertexId, string, required} +*_id* attribute of the vertex + +@PARAM{options, object, optional} +See [collection documentation](../Documents/DocumentMethods.md) + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionRemove} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.male.save({name: "Kermit", _key: "kermit"}); + db._exists("male/kermit") + graph.male.remove("male/kermit") + db._exists("male/kermit") +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_replace.md b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_replace.md index beaaf56c1c..ac3a8ecef6 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_replace.md +++ b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_replace.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_vertex_collection_replace -/// @brief Replaces the data of a vertex in collection vertexCollectionName -/// -/// `graph.vertexCollectionName.replace(vertexId, data, options)` -/// -/// @PARAMS -/// -/// @PARAM{vertexId, string, required} -/// *_id* attribute of the vertex -/// -/// @PARAM{data, object, required} -/// JSON data of vertex. -/// -/// @PARAM{options, object, optional} -/// See [collection documentation](../Documents/DocumentMethods.md) -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionReplace} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.male.save({neym: "Jon", _key: "john"}); -/// graph.male.replace("male/john", {name: "John"}); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Replaces the data of a vertex in collection vertexCollectionName + +`graph.vertexCollectionName.replace(vertexId, data, options)` + +@PARAMS + +@PARAM{vertexId, string, required} +*_id* attribute of the vertex + +@PARAM{data, object, required} +JSON data of vertex. + +@PARAM{options, object, optional} +See [collection documentation](../Documents/DocumentMethods.md) + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionReplace} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.male.save({neym: "Jon", _key: "john"}); + graph.male.replace("male/john", {name: "John"}); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_save.md b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_save.md index 33f4e2f58f..032330e9c3 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_save.md +++ b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_save.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_vertex_collection_save -/// @brief Create a new vertex in vertexCollectionName -/// -/// `graph.vertexCollectionName.save(data)` -/// -/// @PARAMS -/// -/// @PARAM{data, object, required} -/// JSON data of vertex. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionSave} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.male.save({name: "Floyd", _key: "floyd"}); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Create a new vertex in vertexCollectionName + +`graph.vertexCollectionName.save(data)` + +@PARAMS + +@PARAM{data, object, required} +JSON data of vertex. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionSave} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.male.save({name: "Floyd", _key: "floyd"}); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_update.md b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_update.md index bd7e18bf30..42fc4afe08 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_update.md +++ b/Documentation/DocuBlocks/JSF_general_graph_vertex_collection_update.md @@ -1,29 +1,28 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_vertex_collection_update -/// @brief Updates the data of a vertex in collection vertexCollectionName -/// -/// `graph.vertexCollectionName.update(vertexId, data, options)` -/// -/// @PARAMS -/// -/// @PARAM{vertexId, string, required} -/// *_id* attribute of the vertex -/// -/// @PARAM{data, object, required} -/// JSON data of vertex. -/// -/// @PARAM{options, object, optional} -/// See [collection documentation](../Documents/DocumentMethods.md) -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionUpdate} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph.female.save({name: "Lynda", _key: "linda"}); -/// graph.female.update("female/linda", {name: "Linda", _key: "linda"}); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Updates the data of a vertex in collection vertexCollectionName + +`graph.vertexCollectionName.update(vertexId, data, options)` + +@PARAMS + +@PARAM{vertexId, string, required} +*_id* attribute of the vertex + +@PARAM{data, object, required} +JSON data of vertex. + +@PARAM{options, object, optional} +See [collection documentation](../Documents/DocumentMethods.md) + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVertexCollectionUpdate} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph.female.save({name: "Lynda", _key: "linda"}); + graph.female.update("female/linda", {name: "Linda", _key: "linda"}); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/JSF_general_graph_vertices.md b/Documentation/DocuBlocks/JSF_general_graph_vertices.md index ef398d0143..62a9b753ee 100644 --- a/Documentation/DocuBlocks/JSF_general_graph_vertices.md +++ b/Documentation/DocuBlocks/JSF_general_graph_vertices.md @@ -1,41 +1,40 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JSF_general_graph_vertices -/// @brief Select some vertices from the graph. -/// -/// `graph._vertices(examples)` -/// -/// Creates an AQL statement to select a subset of the vertices stored in the graph. -/// This is one of the entry points for the fluent AQL interface. -/// It will return a mutable AQL statement which can be further refined, using the -/// functions described below. -/// The resulting set of edges can be filtered by defining one or more *examples*. -/// -/// @PARAMS -/// -/// @PARAM{examples, object, optional} -/// See [Definition of examples](#definition-of-examples) -/// -/// @EXAMPLES -/// -/// In the examples the *toArray* function is used to print the result. -/// The description of this function can be found below. -/// -/// To request unfiltered vertices: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVerticesUnfiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph._vertices().toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// To request filtered vertices: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{generalGraphVerticesFiltered} -/// var examples = require("@arangodb/graph-examples/example-graph.js"); -/// var graph = examples.loadGraph("social"); -/// graph._vertices([{name: "Alice"}, {name: "Bob"}]).toArray(); -/// ~ examples.dropGraph("social"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief Select some vertices from the graph. + +`graph._vertices(examples)` + +Creates an AQL statement to select a subset of the vertices stored in the graph. +This is one of the entry points for the fluent AQL interface. +It will return a mutable AQL statement which can be further refined, using the +functions described below. +The resulting set of edges can be filtered by defining one or more *examples*. + +@PARAMS + +@PARAM{examples, object, optional} +See [Definition of examples](#definition-of-examples) + +@EXAMPLES + +In the examples the *toArray* function is used to print the result. +The description of this function can be found below. + +To request unfiltered vertices: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVerticesUnfiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph._vertices().toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +To request filtered vertices: + +@EXAMPLE_ARANGOSH_OUTPUT{generalGraphVerticesFiltered} + var examples = require("@arangodb/graph-examples/example-graph.js"); + var graph = examples.loadGraph("social"); + graph._vertices([{name: "Alice"}, {name: "Bob"}]).toArray(); +~ examples.dropGraph("social"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/JS_Chmod.md b/Documentation/DocuBlocks/JS_Chmod.md index c38b87cbe2..2e48909be7 100644 --- a/Documentation/DocuBlocks/JS_Chmod.md +++ b/Documentation/DocuBlocks/JS_Chmod.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Chmod -/// @brief sets file permissions of specified files (non windows only) -/// `fs.exists(path)` -/// -/// Returns true on success. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief sets file permissions of specified files (non windows only) +`fs.exists(path)` + +Returns true on success. + diff --git a/Documentation/DocuBlocks/JS_CopyDirectoryRecursive.md b/Documentation/DocuBlocks/JS_CopyDirectoryRecursive.md index a7c16463b7..0c2cbfc7b2 100644 --- a/Documentation/DocuBlocks/JS_CopyDirectoryRecursive.md +++ b/Documentation/DocuBlocks/JS_CopyDirectoryRecursive.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_CopyDirectoryRecursive -/// @brief copies a directory structure -/// `fs.copyRecursive(source, destination)` -/// -/// Copies *source* to *destination*. -/// Exceptions will be thrown on: -/// - Failure to copy the file -/// - specifying a directory for destination when source is a file -/// - specifying a directory as source and destination -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief copies a directory structure +`fs.copyRecursive(source, destination)` + +Copies *source* to *destination*. +Exceptions will be thrown on: + - Failure to copy the file + - specifying a directory for destination when source is a file + - specifying a directory as source and destination + diff --git a/Documentation/DocuBlocks/JS_CopyFile.md b/Documentation/DocuBlocks/JS_CopyFile.md index 6e2a2e2610..25f940749a 100644 --- a/Documentation/DocuBlocks/JS_CopyFile.md +++ b/Documentation/DocuBlocks/JS_CopyFile.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_CopyFile -/// @brief copies a file into a target file -/// `fs.copyFile(source, destination)` -/// -/// Copies *source* to destination. If Destination is a directory, a file -/// of the same name will be created in that directory, else the copy will get -/// the -/// specified filename. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief copies a file into a target file +`fs.copyFile(source, destination)` + +Copies *source* to destination. If Destination is a directory, a file +of the same name will be created in that directory, else the copy will get +the +specified filename. + diff --git a/Documentation/DocuBlocks/JS_Exists.md b/Documentation/DocuBlocks/JS_Exists.md index 816b6061ac..c9920a7088 100644 --- a/Documentation/DocuBlocks/JS_Exists.md +++ b/Documentation/DocuBlocks/JS_Exists.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Exists -/// @brief checks if a file of any type or directory exists -/// `fs.exists(path)` -/// -/// Returns true if a file (of any type) or a directory exists at a given -/// path. If the file is a broken symbolic link, returns false. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief checks if a file of any type or directory exists +`fs.exists(path)` + +Returns true if a file (of any type) or a directory exists at a given +path. If the file is a broken symbolic link, returns false. + diff --git a/Documentation/DocuBlocks/JS_GetTempFile.md b/Documentation/DocuBlocks/JS_GetTempFile.md index 6099f0b89c..9d522657ba 100644 --- a/Documentation/DocuBlocks/JS_GetTempFile.md +++ b/Documentation/DocuBlocks/JS_GetTempFile.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_GetTempFile -/// @brief returns the name for a (new) temporary file -/// `fs.getTempFile(directory, createFile)` -/// -/// Returns the name for a new temporary file in directory *directory*. -/// If *createFile* is *true*, an empty file will be created so no other -/// process can create a file of the same name. -/// -/// **Note**: The directory *directory* must exist. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the name for a (new) temporary file +`fs.getTempFile(directory, createFile)` + +Returns the name for a new temporary file in directory *directory*. +If *createFile* is *true*, an empty file will be created so no other +process can create a file of the same name. + +**Note**: The directory *directory* must exist. + diff --git a/Documentation/DocuBlocks/JS_GetTempPath.md b/Documentation/DocuBlocks/JS_GetTempPath.md index e112c1ff6b..1c565074be 100644 --- a/Documentation/DocuBlocks/JS_GetTempPath.md +++ b/Documentation/DocuBlocks/JS_GetTempPath.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_GetTempPath -/// @brief returns the temporary directory -/// `fs.getTempPath()` -/// -/// Returns the absolute path of the temporary directory -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the temporary directory +`fs.getTempPath()` + +Returns the absolute path of the temporary directory + + diff --git a/Documentation/DocuBlocks/JS_IsDirectory.md b/Documentation/DocuBlocks/JS_IsDirectory.md index 5b4c484e81..32179476ec 100644 --- a/Documentation/DocuBlocks/JS_IsDirectory.md +++ b/Documentation/DocuBlocks/JS_IsDirectory.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_IsDirectory -/// @brief tests if path is a directory -/// `fs.isDirectory(path)` -/// -/// Returns true if the *path* points to a directory. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief tests if path is a directory +`fs.isDirectory(path)` + +Returns true if the *path* points to a directory. + diff --git a/Documentation/DocuBlocks/JS_IsFile.md b/Documentation/DocuBlocks/JS_IsFile.md index 9d77b8d9aa..72421e2b1f 100644 --- a/Documentation/DocuBlocks/JS_IsFile.md +++ b/Documentation/DocuBlocks/JS_IsFile.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_IsFile -/// @brief tests if path is a file -/// `fs.isFile(path)` -/// -/// Returns true if the *path* points to a file. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief tests if path is a file +`fs.isFile(path)` + +Returns true if the *path* points to a file. + diff --git a/Documentation/DocuBlocks/JS_List.md b/Documentation/DocuBlocks/JS_List.md index a457f28e5b..03acf6ecd4 100644 --- a/Documentation/DocuBlocks/JS_List.md +++ b/Documentation/DocuBlocks/JS_List.md @@ -1,13 +1,12 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_List -/// @brief returns the directory listing -/// `fs.list(path)` -/// -/// The functions returns the names of all the files in a directory, in -/// lexically sorted order. Throws an exception if the directory cannot be -/// traversed (or path is not a directory). -/// -/// **Note**: this means that list("x") of a directory containing "a" and "b" would -/// return ["a", "b"], not ["x/a", "x/b"]. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the directory listing +`fs.list(path)` + +The functions returns the names of all the files in a directory, in +lexically sorted order. Throws an exception if the directory cannot be +traversed (or path is not a directory). + +**Note**: this means that list("x") of a directory containing "a" and "b" would +return ["a", "b"], not ["x/a", "x/b"]. + diff --git a/Documentation/DocuBlocks/JS_ListTree.md b/Documentation/DocuBlocks/JS_ListTree.md index 187771dde2..4ebca52fee 100644 --- a/Documentation/DocuBlocks/JS_ListTree.md +++ b/Documentation/DocuBlocks/JS_ListTree.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_ListTree -/// @brief returns the directory tree -/// `fs.listTree(path)` -/// -/// The function returns an array that starts with the given path, and all of -/// the paths relative to the given path, discovered by a depth first traversal -/// of every directory in any visited directory, reporting but not traversing -/// symbolic links to directories. The first path is always *""*, the path -/// relative to itself. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the directory tree +`fs.listTree(path)` + +The function returns an array that starts with the given path, and all of +the paths relative to the given path, discovered by a depth first traversal +of every directory in any visited directory, reporting but not traversing +symbolic links to directories. The first path is always *""*, the path +relative to itself. + diff --git a/Documentation/DocuBlocks/JS_MTime.md b/Documentation/DocuBlocks/JS_MTime.md index 885bd94547..976e48497d 100644 --- a/Documentation/DocuBlocks/JS_MTime.md +++ b/Documentation/DocuBlocks/JS_MTime.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_MTime -/// @brief gets the last modification time of a file -/// `fs.mtime(filename)` -/// -/// Returns the last modification date of the specified file. The date is -/// returned as a Unix timestamp (number of seconds elapsed since January 1 1970). -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief gets the last modification time of a file +`fs.mtime(filename)` + +Returns the last modification date of the specified file. The date is +returned as a Unix timestamp (number of seconds elapsed since January 1 1970). + diff --git a/Documentation/DocuBlocks/JS_MakeAbsolute.md b/Documentation/DocuBlocks/JS_MakeAbsolute.md index 4f83bbe2b9..032f801e60 100644 --- a/Documentation/DocuBlocks/JS_MakeAbsolute.md +++ b/Documentation/DocuBlocks/JS_MakeAbsolute.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_MakeAbsolute -/// @brief makes a given path absolute -/// `fs.makeAbsolute(path)` -/// -/// Returns the given string if it is an absolute path, otherwise an -/// absolute path to the same location is returned. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief makes a given path absolute +`fs.makeAbsolute(path)` + +Returns the given string if it is an absolute path, otherwise an +absolute path to the same location is returned. + diff --git a/Documentation/DocuBlocks/JS_MakeDirectory.md b/Documentation/DocuBlocks/JS_MakeDirectory.md index c10dda6c33..1bd1ff1db6 100644 --- a/Documentation/DocuBlocks/JS_MakeDirectory.md +++ b/Documentation/DocuBlocks/JS_MakeDirectory.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_MakeDirectory -/// @brief creates a directory -/// `fs.makeDirectory(path)` -/// -/// Creates the directory specified by *path*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief creates a directory +`fs.makeDirectory(path)` + +Creates the directory specified by *path*. + diff --git a/Documentation/DocuBlocks/JS_MakeDirectoryRecursive.md b/Documentation/DocuBlocks/JS_MakeDirectoryRecursive.md index c3deb37c87..ad14727a65 100644 --- a/Documentation/DocuBlocks/JS_MakeDirectoryRecursive.md +++ b/Documentation/DocuBlocks/JS_MakeDirectoryRecursive.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_MakeDirectoryRecursive -/// @brief creates a directory -/// `fs.makeDirectoryRecursive(path)` -/// -/// Creates the directory hierarchy specified by *path*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief creates a directory +`fs.makeDirectoryRecursive(path)` + +Creates the directory hierarchy specified by *path*. + diff --git a/Documentation/DocuBlocks/JS_MoveFile.md b/Documentation/DocuBlocks/JS_MoveFile.md index ad9bc75137..eb15049e0f 100644 --- a/Documentation/DocuBlocks/JS_MoveFile.md +++ b/Documentation/DocuBlocks/JS_MoveFile.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_MoveFile -/// @brief renames a file -/// `fs.move(source, destination)` -/// -/// Moves *source* to destination. Failure to move the file, or -/// specifying a directory for destination when source is a file will throw an -/// exception. Likewise, specifying a directory as source and destination will -/// fail. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief renames a file +`fs.move(source, destination)` + +Moves *source* to destination. Failure to move the file, or +specifying a directory for destination when source is a file will throw an +exception. Likewise, specifying a directory as source and destination will +fail. + diff --git a/Documentation/DocuBlocks/JS_Read.md b/Documentation/DocuBlocks/JS_Read.md index 84b4fa4289..98933c5e76 100644 --- a/Documentation/DocuBlocks/JS_Read.md +++ b/Documentation/DocuBlocks/JS_Read.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Read -/// @brief reads in a file -/// `fs.read(filename)` -/// -/// Reads in a file and returns the content as string. Please note that the -/// file content must be encoded in UTF-8. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief reads in a file +`fs.read(filename)` + +Reads in a file and returns the content as string. Please note that the +file content must be encoded in UTF-8. + diff --git a/Documentation/DocuBlocks/JS_Read64.md b/Documentation/DocuBlocks/JS_Read64.md index 66926032c8..d9d3f68401 100644 --- a/Documentation/DocuBlocks/JS_Read64.md +++ b/Documentation/DocuBlocks/JS_Read64.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Read64 -/// @brief reads in a file as base64 -/// `fs.read64(filename)` -/// -/// Reads in a file and returns the content as string. The file content is -/// Base64 encoded. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief reads in a file as base64 +`fs.read64(filename)` + +Reads in a file and returns the content as string. The file content is +Base64 encoded. + diff --git a/Documentation/DocuBlocks/JS_ReadBuffer.md b/Documentation/DocuBlocks/JS_ReadBuffer.md index 0a5bd8545f..b0b74087df 100644 --- a/Documentation/DocuBlocks/JS_ReadBuffer.md +++ b/Documentation/DocuBlocks/JS_ReadBuffer.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_ReadBuffer -/// @brief reads in a file -/// `fs.readBuffer(filename)` -/// -/// Reads in a file and returns its content in a Buffer object. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief reads in a file +`fs.readBuffer(filename)` + +Reads in a file and returns its content in a Buffer object. + diff --git a/Documentation/DocuBlocks/JS_Remove.md b/Documentation/DocuBlocks/JS_Remove.md index fcc5d7fe5d..ddc99b43df 100644 --- a/Documentation/DocuBlocks/JS_Remove.md +++ b/Documentation/DocuBlocks/JS_Remove.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Remove -/// @brief removes a file -/// `fs.remove(filename)` -/// -/// Removes the file *filename* at the given path. Throws an exception if the -/// path corresponds to anything that is not a file or a symbolic link. If -/// "path" refers to a symbolic link, removes the symbolic link. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief removes a file +`fs.remove(filename)` + +Removes the file *filename* at the given path. Throws an exception if the +path corresponds to anything that is not a file or a symbolic link. If +"path" refers to a symbolic link, removes the symbolic link. + diff --git a/Documentation/DocuBlocks/JS_RemoveDirectory.md b/Documentation/DocuBlocks/JS_RemoveDirectory.md index 0a54e5ea08..3df01bd716 100644 --- a/Documentation/DocuBlocks/JS_RemoveDirectory.md +++ b/Documentation/DocuBlocks/JS_RemoveDirectory.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_RemoveDirectory -/// @brief removes an empty directory -/// `fs.removeDirectory(path)` -/// -/// Removes a directory if it is empty. Throws an exception if the path is not -/// an empty directory. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief removes an empty directory +`fs.removeDirectory(path)` + +Removes a directory if it is empty. Throws an exception if the path is not +an empty directory. + + diff --git a/Documentation/DocuBlocks/JS_RemoveDirectoryRecursive.md b/Documentation/DocuBlocks/JS_RemoveDirectoryRecursive.md index a256c961c0..ffc5b8f45e 100644 --- a/Documentation/DocuBlocks/JS_RemoveDirectoryRecursive.md +++ b/Documentation/DocuBlocks/JS_RemoveDirectoryRecursive.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_RemoveDirectoryRecursive -/// @brief removes a directory -/// `fs.removeDirectoryRecursive(path)` -/// -/// Removes a directory with all subelements. Throws an exception if the path -/// is not a directory. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief removes a directory +`fs.removeDirectoryRecursive(path)` + +Removes a directory with all subelements. Throws an exception if the path +is not a directory. + diff --git a/Documentation/DocuBlocks/JS_Save.md b/Documentation/DocuBlocks/JS_Save.md index f602510318..182863b1f8 100644 --- a/Documentation/DocuBlocks/JS_Save.md +++ b/Documentation/DocuBlocks/JS_Save.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Save -/// @brief writes to a file -/// `fs.write(filename, content)` -/// -/// Writes the content into a file. Content can be a string or a Buffer object. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief writes to a file +`fs.write(filename, content)` + +Writes the content into a file. Content can be a string or a Buffer object. + diff --git a/Documentation/DocuBlocks/JS_Size.md b/Documentation/DocuBlocks/JS_Size.md index d327ea9e72..4f4f5618cc 100644 --- a/Documentation/DocuBlocks/JS_Size.md +++ b/Documentation/DocuBlocks/JS_Size.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Size -/// @brief gets the size of a file -/// `fs.size(path)` -/// -/// Returns the size of the file specified by *path*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief gets the size of a file +`fs.size(path)` + +Returns the size of the file specified by *path*. + diff --git a/Documentation/DocuBlocks/JS_Unzip.md b/Documentation/DocuBlocks/JS_Unzip.md index 92f1877e32..fff297bdd1 100644 --- a/Documentation/DocuBlocks/JS_Unzip.md +++ b/Documentation/DocuBlocks/JS_Unzip.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Unzip -/// @brief unzips a file -/// `fs.unzipFile(filename, outpath, skipPaths, overwrite, password)` -/// -/// Unzips the zip file specified by *filename* into the path specified by -/// *outpath*. Overwrites any existing target files if *overwrite* is set -/// to *true*. -/// -/// Returns *true* if the file was unzipped successfully. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief unzips a file +`fs.unzipFile(filename, outpath, skipPaths, overwrite, password)` + +Unzips the zip file specified by *filename* into the path specified by +*outpath*. Overwrites any existing target files if *overwrite* is set +to *true*. + +Returns *true* if the file was unzipped successfully. + diff --git a/Documentation/DocuBlocks/JS_Zip.md b/Documentation/DocuBlocks/JS_Zip.md index 174b732559..9c31983776 100644 --- a/Documentation/DocuBlocks/JS_Zip.md +++ b/Documentation/DocuBlocks/JS_Zip.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock JS_Zip -/// @brief zips a file -/// `fs.zipFile(filename, chdir, files, password)` -/// -/// Stores the files specified by *files* in the zip file *filename*. If -/// the file *filename* already exists, an error is thrown. The list of input -/// files *files* must be given as a list of absolute filenames. If *chdir* is -/// not empty, the *chdir* prefix will be stripped from the filename in the -/// zip file, so when it is unzipped filenames will be relative. -/// Specifying a password is optional. -/// -/// Returns *true* if the file was zipped successfully. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief zips a file +`fs.zipFile(filename, chdir, files, password)` + +Stores the files specified by *files* in the zip file *filename*. If +the file *filename* already exists, an error is thrown. The list of input +files *files* must be given as a list of absolute filenames. If *chdir* is +not empty, the *chdir* prefix will be stripped from the filename in the +zip file, so when it is unzipped filenames will be relative. +Specifying a password is optional. + +Returns *true* if the file was zipped successfully. + diff --git a/Documentation/DocuBlocks/SessionTimeout.md b/Documentation/DocuBlocks/SessionTimeout.md index d671543b57..be83fe2c61 100644 --- a/Documentation/DocuBlocks/SessionTimeout.md +++ b/Documentation/DocuBlocks/SessionTimeout.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock SessionTimeout -/// @brief time to live for server sessions -/// `--server.session-timeout value` -/// -/// The timeout for web interface sessions, using for authenticating requests -/// to the web interface (/_admin/aardvark) and related areas. -/// -/// Sessions are only used when authentication is turned on. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief time to live for server sessions +`--server.session-timeout value` + +The timeout for web interface sessions, using for authenticating requests +to the web interface (/_admin/aardvark) and related areas. + +Sessions are only used when authentication is turned on. + diff --git a/Documentation/DocuBlocks/WalLogfileDirectory.md b/Documentation/DocuBlocks/WalLogfileDirectory.md index b4d4915f15..41d0989396 100644 --- a/Documentation/DocuBlocks/WalLogfileDirectory.md +++ b/Documentation/DocuBlocks/WalLogfileDirectory.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock WalLogfileDirectory -/// @brief the WAL logfiles directory -/// `--wal.directory` -/// -/// Specifies the directory in which the write-ahead logfiles should be -/// stored. If this option is not specified, it defaults to the subdirectory -/// *journals* in the server's global database directory. If the directory is -/// not present, it will be created. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief the WAL logfiles directory +`--wal.directory` + +Specifies the directory in which the write-ahead logfiles should be +stored. If this option is not specified, it defaults to the subdirectory +*journals* in the server's global database directory. If the directory is +not present, it will be created. + diff --git a/Documentation/DocuBlocks/WalLogfileIgnoreLogfileErrors.md b/Documentation/DocuBlocks/WalLogfileIgnoreLogfileErrors.md index ef45a834ef..41e5a46c5e 100644 --- a/Documentation/DocuBlocks/WalLogfileIgnoreLogfileErrors.md +++ b/Documentation/DocuBlocks/WalLogfileIgnoreLogfileErrors.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock WalLogfileIgnoreLogfileErrors -/// @brief ignore logfile errors when opening logfiles -/// `--wal.ignore-logfile-errors` -/// -/// Ignores any recovery errors caused by corrupted logfiles on startup. When -/// set to *false*, the recovery procedure on startup will fail with an error -/// whenever it encounters a corrupted (that includes only half-written) -/// logfile. This is a security precaution to prevent data loss in case of -/// disk -/// errors etc. When the recovery procedure aborts because of corruption, any -/// corrupted files can be inspected and fixed (or removed) manually and the -/// server can be restarted afterwards. -/// -/// Setting the option to *true* will make the server continue with the -/// recovery -/// procedure even in case it detects corrupt logfile entries. In this case it -/// will stop at the first corrupted logfile entry and ignore all others, -/// which -/// might cause data loss. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ignore logfile errors when opening logfiles +`--wal.ignore-logfile-errors` + +Ignores any recovery errors caused by corrupted logfiles on startup. When +set to *false*, the recovery procedure on startup will fail with an error +whenever it encounters a corrupted (that includes only half-written) +logfile. This is a security precaution to prevent data loss in case of +disk +errors etc. When the recovery procedure aborts because of corruption, any +corrupted files can be inspected and fixed (or removed) manually and the +server can be restarted afterwards. + +Setting the option to *true* will make the server continue with the +recovery +procedure even in case it detects corrupt logfile entries. In this case it +will stop at the first corrupted logfile entry and ignore all others, +which +might cause data loss. + diff --git a/Documentation/DocuBlocks/WalLogfileIgnoreRecoveryErrors.md b/Documentation/DocuBlocks/WalLogfileIgnoreRecoveryErrors.md index 5b58256f16..6b2e48ec44 100644 --- a/Documentation/DocuBlocks/WalLogfileIgnoreRecoveryErrors.md +++ b/Documentation/DocuBlocks/WalLogfileIgnoreRecoveryErrors.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock WalLogfileIgnoreRecoveryErrors -/// @brief ignore recovery errors -/// `--wal.ignore-recovery-errors` -/// -/// Ignores any recovery errors not caused by corrupted logfiles but by -/// logical -/// errors. Logical errors can occur if logfiles or any other server datafiles -/// have been manually edited or the server is somehow misconfigured. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ignore recovery errors +`--wal.ignore-recovery-errors` + +Ignores any recovery errors not caused by corrupted logfiles but by +logical +errors. Logical errors can occur if logfiles or any other server datafiles +have been manually edited or the server is somehow misconfigured. + diff --git a/Documentation/DocuBlocks/WalLogfileSlots.md b/Documentation/DocuBlocks/WalLogfileSlots.md index 8d1c313c08..2f42999d85 100644 --- a/Documentation/DocuBlocks/WalLogfileSlots.md +++ b/Documentation/DocuBlocks/WalLogfileSlots.md @@ -1,17 +1,16 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock WalLogfileSlots -/// @brief maximum number of slots to be used in parallel -/// `--wal.slots` -/// -/// Configures the amount of write slots the write-ahead log can give to write -/// operations in parallel. Any write operation will lease a slot and return -/// it -/// to the write-ahead log when it is finished writing the data. A slot will -/// remain blocked until the data in it was synchronized to disk. After that, -/// a slot becomes reusable by following operations. The required number of -/// slots is thus determined by the parallelity of write operations and the -/// disk synchronization speed. Slow disks probably need higher values, and -/// fast -/// disks may only require a value lower than the default. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief maximum number of slots to be used in parallel +`--wal.slots` + +Configures the amount of write slots the write-ahead log can give to write +operations in parallel. Any write operation will lease a slot and return +it +to the write-ahead log when it is finished writing the data. A slot will +remain blocked until the data in it was synchronized to disk. After that, +a slot becomes reusable by following operations. The required number of +slots is thus determined by the parallelity of write operations and the +disk synchronization speed. Slow disks probably need higher values, and +fast +disks may only require a value lower than the default. + diff --git a/Documentation/DocuBlocks/WalLogfileThrottling.md b/Documentation/DocuBlocks/WalLogfileThrottling.md index 7dd6cbd733..883b9ffbaa 100644 --- a/Documentation/DocuBlocks/WalLogfileThrottling.md +++ b/Documentation/DocuBlocks/WalLogfileThrottling.md @@ -1,36 +1,35 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock WalLogfileThrottling -/// @brief throttle writes to WAL when at least such many operations are -/// waiting for garbage collection -/// `--wal.throttle-when-pending` -/// -/// The maximum value for the number of write-ahead log garbage-collection -/// queue -/// elements. If set to *0*, the queue size is unbounded, and no -/// writtle-throttling will occur. If set to a non-zero value, -/// writte-throttling -/// will automatically kick in when the garbage-collection queue contains at -/// least as many elements as specified by this option. -/// While write-throttling is active, data-modification operations will -/// intentionally be delayed by a configurable amount of time. This is to -/// ensure the write-ahead log garbage collector can catch up with the -/// operations executed. -/// Write-throttling will stay active until the garbage-collection queue size -/// goes down below the specified value. -/// Write-throttling is turned off by default. -/// -/// `--wal.throttle-wait` -/// -/// This option determines the maximum wait time (in milliseconds) for -/// operations that are write-throttled. If write-throttling is active and a -/// new write operation is to be executed, it will wait for at most the -/// specified amount of time for the write-ahead log garbage-collection queue -/// size to fall below the throttling threshold. If the queue size decreases -/// before the maximum wait time is over, the operation will be executed -/// normally. If the queue size does not decrease before the wait time is -/// over, -/// the operation will be aborted with an error. -/// This option only has an effect if `--wal.throttle-when-pending` has a -/// non-zero value, which is not the default. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief throttle writes to WAL when at least such many operations are +waiting for garbage collection +`--wal.throttle-when-pending` + +The maximum value for the number of write-ahead log garbage-collection +queue +elements. If set to *0*, the queue size is unbounded, and no +writtle-throttling will occur. If set to a non-zero value, +writte-throttling +will automatically kick in when the garbage-collection queue contains at +least as many elements as specified by this option. +While write-throttling is active, data-modification operations will +intentionally be delayed by a configurable amount of time. This is to +ensure the write-ahead log garbage collector can catch up with the +operations executed. +Write-throttling will stay active until the garbage-collection queue size +goes down below the specified value. +Write-throttling is turned off by default. + +`--wal.throttle-wait` + +This option determines the maximum wait time (in milliseconds) for +operations that are write-throttled. If write-throttling is active and a +new write operation is to be executed, it will wait for at most the +specified amount of time for the write-ahead log garbage-collection queue +size to fall below the throttling threshold. If the queue size decreases +before the maximum wait time is over, the operation will be executed +normally. If the queue size does not decrease before the wait time is +over, +the operation will be aborted with an error. +This option only has an effect if `--wal.throttle-when-pending` has a +non-zero value, which is not the default. + diff --git a/Documentation/DocuBlocks/actionsCollectionNotFound.md b/Documentation/DocuBlocks/actionsCollectionNotFound.md index 67f6ad4f87..f88000431d 100644 --- a/Documentation/DocuBlocks/actionsCollectionNotFound.md +++ b/Documentation/DocuBlocks/actionsCollectionNotFound.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsCollectionNotFound -/// -/// `actions.collectionNotFound(req, res, collection, headers)` -/// -/// The function generates an error response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.collectionNotFound(req, res, collection, headers)` + +The function generates an error response. + diff --git a/Documentation/DocuBlocks/actionsDefineHttp.md b/Documentation/DocuBlocks/actionsDefineHttp.md index ae0493654c..911d1c75c9 100644 --- a/Documentation/DocuBlocks/actionsDefineHttp.md +++ b/Documentation/DocuBlocks/actionsDefineHttp.md @@ -1,38 +1,37 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsDefineHttp -/// -/// `actions.defineHttp(options)` -/// -/// Defines a new action. The *options* are as follows: -/// -/// `options.url` -/// -/// The URL, which can be used to access the action. This path might contain -/// slashes. Note that this action will also be called, if a url is given such that -/// *options.url* is a prefix of the given url and no longer definition -/// matches. -/// -/// `options.prefix` -/// -/// If *false*, then only use the action for exact matches. The default is -/// *true*. -/// -/// `options.callback(request, response)` -/// -/// The request argument contains a description of the request. A request -/// parameter *foo* is accessible as *request.parametrs.foo*. A request -/// header *bar* is accessible as *request.headers.bar*. Assume that -/// the action is defined for the url */foo/bar* and the request url is -/// */foo/bar/hugo/egon*. Then the suffix parts *[ "hugo", "egon" ]* -/// are availible in *request.suffix*. -/// -/// The callback must define fill the *response*. -/// -/// * *response.responseCode*: the response code -/// * *response.contentType*: the content type of the response -/// * *response.body*: the body of the response -/// -/// You can use the functions *ResultOk* and *ResultError* to easily -/// generate a response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.defineHttp(options)` + +Defines a new action. The *options* are as follows: + +`options.url` + +The URL, which can be used to access the action. This path might contain +slashes. Note that this action will also be called, if a url is given such that +*options.url* is a prefix of the given url and no longer definition +matches. + +`options.prefix` + +If *false*, then only use the action for exact matches. The default is +*true*. + +`options.callback(request, response)` + +The request argument contains a description of the request. A request +parameter *foo* is accessible as *request.parametrs.foo*. A request +header *bar* is accessible as *request.headers.bar*. Assume that +the action is defined for the url */foo/bar* and the request url is +*/foo/bar/hugo/egon*. Then the suffix parts *[ "hugo", "egon" ]* +are availible in *request.suffix*. + +The callback must define fill the *response*. + +* *response.responseCode*: the response code +* *response.contentType*: the content type of the response +* *response.body*: the body of the response + +You can use the functions *ResultOk* and *ResultError* to easily +generate a response. + diff --git a/Documentation/DocuBlocks/actionsGetErrorMessage.md b/Documentation/DocuBlocks/actionsGetErrorMessage.md index 234f46a0d8..90b227c17a 100644 --- a/Documentation/DocuBlocks/actionsGetErrorMessage.md +++ b/Documentation/DocuBlocks/actionsGetErrorMessage.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsGetErrorMessage -/// -/// `actions.getErrorMessage(code)` -/// -/// Returns the error message for an error code. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.getErrorMessage(code)` + +Returns the error message for an error code. + diff --git a/Documentation/DocuBlocks/actionsIndexNotFound.md b/Documentation/DocuBlocks/actionsIndexNotFound.md index f8676b67c9..b3c13c37d7 100644 --- a/Documentation/DocuBlocks/actionsIndexNotFound.md +++ b/Documentation/DocuBlocks/actionsIndexNotFound.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsIndexNotFound -/// -/// `actions.indexNotFound(req, res, collection, index, headers)` -/// -/// The function generates an error response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.indexNotFound(req, res, collection, index, headers)` + +The function generates an error response. + diff --git a/Documentation/DocuBlocks/actionsResultBad.md b/Documentation/DocuBlocks/actionsResultBad.md index 6c2e293df0..bfba6bacf5 100644 --- a/Documentation/DocuBlocks/actionsResultBad.md +++ b/Documentation/DocuBlocks/actionsResultBad.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultBad -/// -/// `actions.resultBad(req, res, error-code, msg, headers)` -/// -/// The function generates an error response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultBad(req, res, error-code, msg, headers)` + +The function generates an error response. + diff --git a/Documentation/DocuBlocks/actionsResultError.md b/Documentation/DocuBlocks/actionsResultError.md index dd12cfe50d..6dbc7f47c2 100644 --- a/Documentation/DocuBlocks/actionsResultError.md +++ b/Documentation/DocuBlocks/actionsResultError.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultError -/// -/// *actions.resultError(*req*, *res*, *code*, *errorNum*, -/// *errorMessage*, *headers*, *keyvals)* -/// -/// The function generates an error response. The response body is an array -/// with an attribute *errorMessage* containing the error message -/// *errorMessage*, *error* containing *true*, *code* containing -/// *code*, *errorNum* containing *errorNum*, and *errorMessage* -/// containing the error message *errorMessage*. *keyvals* are mixed -/// into the result. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +*actions.resultError(*req*, *res*, *code*, *errorNum*, + *errorMessage*, *headers*, *keyvals)* + +The function generates an error response. The response body is an array +with an attribute *errorMessage* containing the error message +*errorMessage*, *error* containing *true*, *code* containing +*code*, *errorNum* containing *errorNum*, and *errorMessage* +containing the error message *errorMessage*. *keyvals* are mixed +into the result. + diff --git a/Documentation/DocuBlocks/actionsResultException.md b/Documentation/DocuBlocks/actionsResultException.md index af76d6b969..ca1820cf23 100644 --- a/Documentation/DocuBlocks/actionsResultException.md +++ b/Documentation/DocuBlocks/actionsResultException.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultException -/// -/// `actions.resultException(req, res, err, headers, verbose)` -/// -/// The function generates an error response. If @FA{verbose} is set to -/// *true* or not specified (the default), then the error stack trace will -/// be included in the error message if available. If @FA{verbose} is a string -/// it will be prepended before the error message and the stacktrace will also -/// be included. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultException(req, res, err, headers, verbose)` + +The function generates an error response. If @FA{verbose} is set to +*true* or not specified (the default), then the error stack trace will +be included in the error message if available. If @FA{verbose} is a string +it will be prepended before the error message and the stacktrace will also +be included. + diff --git a/Documentation/DocuBlocks/actionsResultNotFound.md b/Documentation/DocuBlocks/actionsResultNotFound.md index 8256a69ffe..ea6b83dc12 100644 --- a/Documentation/DocuBlocks/actionsResultNotFound.md +++ b/Documentation/DocuBlocks/actionsResultNotFound.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultNotFound -/// -/// `actions.resultNotFound(req, res, code, msg, headers)` -/// -/// The function generates an error response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultNotFound(req, res, code, msg, headers)` + +The function generates an error response. + diff --git a/Documentation/DocuBlocks/actionsResultNotImplemented.md b/Documentation/DocuBlocks/actionsResultNotImplemented.md index 00cf0b3b41..4b0819701b 100644 --- a/Documentation/DocuBlocks/actionsResultNotImplemented.md +++ b/Documentation/DocuBlocks/actionsResultNotImplemented.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultNotImplemented -/// -/// `actions.resultNotImplemented(req, res, msg, headers)` -/// -/// The function generates an error response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultNotImplemented(req, res, msg, headers)` + +The function generates an error response. + diff --git a/Documentation/DocuBlocks/actionsResultOk.md b/Documentation/DocuBlocks/actionsResultOk.md index 49a05fbfc3..3aa2fc4c51 100644 --- a/Documentation/DocuBlocks/actionsResultOk.md +++ b/Documentation/DocuBlocks/actionsResultOk.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultOk -/// -/// `actions.resultOk(req, res, code, result, headers)` -/// -/// The function defines a response. *code* is the status code to -/// return. *result* is the result object, which will be returned as JSON -/// object in the body. *headers* is an array of headers to returned. -/// The function adds the attribute *error* with value *false* -/// and *code* with value *code* to the *result*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultOk(req, res, code, result, headers)` + +The function defines a response. *code* is the status code to +return. *result* is the result object, which will be returned as JSON +object in the body. *headers* is an array of headers to returned. +The function adds the attribute *error* with value *false* +and *code* with value *code* to the *result*. + diff --git a/Documentation/DocuBlocks/actionsResultPermanentRedirect.md b/Documentation/DocuBlocks/actionsResultPermanentRedirect.md index 43c2641e37..78800d47f4 100644 --- a/Documentation/DocuBlocks/actionsResultPermanentRedirect.md +++ b/Documentation/DocuBlocks/actionsResultPermanentRedirect.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultPermanentRedirect -/// -/// `actions.resultPermanentRedirect(req, res, options, headers)` -/// -/// The function generates a redirect response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultPermanentRedirect(req, res, options, headers)` + +The function generates a redirect response. + diff --git a/Documentation/DocuBlocks/actionsResultTemporaryRedirect.md b/Documentation/DocuBlocks/actionsResultTemporaryRedirect.md index c241959eea..290556040b 100644 --- a/Documentation/DocuBlocks/actionsResultTemporaryRedirect.md +++ b/Documentation/DocuBlocks/actionsResultTemporaryRedirect.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultTemporaryRedirect -/// -/// `actions.resultTemporaryRedirect(req, res, options, headers)` -/// -/// The function generates a redirect response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultTemporaryRedirect(req, res, options, headers)` + +The function generates a redirect response. + diff --git a/Documentation/DocuBlocks/actionsResultUnsupported.md b/Documentation/DocuBlocks/actionsResultUnsupported.md index 4187e7608d..6ae826faba 100644 --- a/Documentation/DocuBlocks/actionsResultUnsupported.md +++ b/Documentation/DocuBlocks/actionsResultUnsupported.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock actionsResultUnsupported -/// -/// `actions.resultUnsupported(req, res, headers)` -/// -/// The function generates an error response. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`actions.resultUnsupported(req, res, headers)` + +The function generates an error response. + diff --git a/Documentation/DocuBlocks/aqlFunctionsRegister.md b/Documentation/DocuBlocks/aqlFunctionsRegister.md index 3fa0d6a25d..57e027ed46 100644 --- a/Documentation/DocuBlocks/aqlFunctionsRegister.md +++ b/Documentation/DocuBlocks/aqlFunctionsRegister.md @@ -1,38 +1,37 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock aqlFunctionsRegister -/// @brief register an AQL user function -/// `aqlfunctions.register(name, code, isDeterministic)` -/// -/// Registers an AQL user function, identified by a fully qualified function -/// name. The function code in *code* must be specified as a JavaScript -/// function or a string representation of a JavaScript function. -/// If the function code in *code* is passed as a string, it is required that -/// the string evaluates to a JavaScript function definition. -/// -/// If a function identified by *name* already exists, the previous function -/// definition will be updated. Please also make sure that the function code -/// does not violate the [Conventions](../AqlExtending/Conventions.md) for AQL -/// functions. -/// -/// The *isDeterministic* attribute can be used to specify whether the -/// function results are fully deterministic (i.e. depend solely on the input -/// and are the same for repeated calls with the same input values). It is not -/// used at the moment but may be used for optimizations later. -/// -/// The registered function is stored in the selected database's system -/// collection *_aqlfunctions*. -/// -/// The function returns *true* when it updates/replaces an existing AQL -/// function of the same name, and *false* otherwise. It will throw an exception -/// when it detects syntactially invalid function code. -/// -/// @EXAMPLES -/// -/// ```js -/// require("@arangodb/aql/functions").register("myfunctions::temperature::celsiustofahrenheit", -/// function (celsius) { -/// return celsius * 1.8 + 32; -/// }); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief register an AQL user function +`aqlfunctions.register(name, code, isDeterministic)` + +Registers an AQL user function, identified by a fully qualified function +name. The function code in *code* must be specified as a JavaScript +function or a string representation of a JavaScript function. +If the function code in *code* is passed as a string, it is required that +the string evaluates to a JavaScript function definition. + +If a function identified by *name* already exists, the previous function +definition will be updated. Please also make sure that the function code +does not violate the [Conventions](../AqlExtending/Conventions.md) for AQL +functions. + +The *isDeterministic* attribute can be used to specify whether the +function results are fully deterministic (i.e. depend solely on the input +and are the same for repeated calls with the same input values). It is not +used at the moment but may be used for optimizations later. + +The registered function is stored in the selected database's system +collection *_aqlfunctions*. + +The function returns *true* when it updates/replaces an existing AQL +function of the same name, and *false* otherwise. It will throw an exception +when it detects syntactially invalid function code. + +@EXAMPLES + +```js + require("@arangodb/aql/functions").register("myfunctions::temperature::celsiustofahrenheit", + function (celsius) { + return celsius * 1.8 + 32; + }); +``` + diff --git a/Documentation/DocuBlocks/aqlFunctionsToArray.md b/Documentation/DocuBlocks/aqlFunctionsToArray.md index e8b9a21990..50c63226e1 100644 --- a/Documentation/DocuBlocks/aqlFunctionsToArray.md +++ b/Documentation/DocuBlocks/aqlFunctionsToArray.md @@ -1,34 +1,33 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock aqlFunctionsToArray -/// @brief list all AQL user functions -/// `aqlfunctions.toArray()` -/// -/// Returns all previously registered AQL user functions, with their fully -/// qualified names and function code. -/// -/// The result may optionally be restricted to a specified group of functions -/// by specifying a group prefix: -/// -/// `aqlfunctions.toArray(prefix)` -/// -/// @EXAMPLES -/// -/// To list all available user functions: -/// -/// ```js -/// require("@arangodb/aql/functions").toArray(); -/// ``` -/// -/// To list all available user functions in the *myfunctions* namespace: -/// -/// ```js -/// require("@arangodb/aql/functions").toArray("myfunctions"); -/// ``` -/// -/// To list all available user functions in the *myfunctions::temperature* namespace: -/// -/// ```js -/// require("@arangodb/aql/functions").toArray("myfunctions::temperature"); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief list all AQL user functions +`aqlfunctions.toArray()` + +Returns all previously registered AQL user functions, with their fully +qualified names and function code. + +The result may optionally be restricted to a specified group of functions +by specifying a group prefix: + +`aqlfunctions.toArray(prefix)` + +@EXAMPLES + +To list all available user functions: + +```js + require("@arangodb/aql/functions").toArray(); +``` + +To list all available user functions in the *myfunctions* namespace: + +```js + require("@arangodb/aql/functions").toArray("myfunctions"); +``` + +To list all available user functions in the *myfunctions::temperature* namespace: + +```js + require("@arangodb/aql/functions").toArray("myfunctions::temperature"); +``` + diff --git a/Documentation/DocuBlocks/aqlFunctionsUnregister.md b/Documentation/DocuBlocks/aqlFunctionsUnregister.md index 39b67967aa..9b9c20a21d 100644 --- a/Documentation/DocuBlocks/aqlFunctionsUnregister.md +++ b/Documentation/DocuBlocks/aqlFunctionsUnregister.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock aqlFunctionsUnregister -/// @brief delete an existing AQL user function -/// `aqlfunctions.unregister(name)` -/// -/// Unregisters an existing AQL user function, identified by the fully qualified -/// function name. -/// -/// Trying to unregister a function that does not exist will result in an -/// exception. -/// -/// @EXAMPLES -/// -/// ```js -/// require("@arangodb/aql/functions").unregister("myfunctions::temperature::celsiustofahrenheit"); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief delete an existing AQL user function +`aqlfunctions.unregister(name)` + +Unregisters an existing AQL user function, identified by the fully qualified +function name. + +Trying to unregister a function that does not exist will result in an +exception. + +@EXAMPLES + +```js + require("@arangodb/aql/functions").unregister("myfunctions::temperature::celsiustofahrenheit"); +``` + diff --git a/Documentation/DocuBlocks/aqlFunctionsUnregisterGroup.md b/Documentation/DocuBlocks/aqlFunctionsUnregisterGroup.md index 01e6d28c7d..f962a6e7c7 100644 --- a/Documentation/DocuBlocks/aqlFunctionsUnregisterGroup.md +++ b/Documentation/DocuBlocks/aqlFunctionsUnregisterGroup.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock aqlFunctionsUnregisterGroup -/// @brief delete a group of AQL user functions -/// `aqlfunctions.unregisterGroup(prefix)` -/// -/// Unregisters a group of AQL user function, identified by a common function -/// group prefix. -/// -/// This will return the number of functions unregistered. -/// -/// @EXAMPLES -/// -/// ```js -/// require("@arangodb/aql/functions").unregisterGroup("myfunctions::temperature"); -/// -/// require("@arangodb/aql/functions").unregisterGroup("myfunctions"); -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief delete a group of AQL user functions +`aqlfunctions.unregisterGroup(prefix)` + +Unregisters a group of AQL user function, identified by a common function +group prefix. + +This will return the number of functions unregistered. + +@EXAMPLES + +```js + require("@arangodb/aql/functions").unregisterGroup("myfunctions::temperature"); + + require("@arangodb/aql/functions").unregisterGroup("myfunctions"); +``` + diff --git a/Documentation/DocuBlocks/clusterAgencyEndpoint.md b/Documentation/DocuBlocks/clusterAgencyEndpoint.md index fa79d29c5c..7d7bc88210 100644 --- a/Documentation/DocuBlocks/clusterAgencyEndpoint.md +++ b/Documentation/DocuBlocks/clusterAgencyEndpoint.md @@ -1,27 +1,26 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock clusterAgencyEndpoint -/// @brief list of agency endpoints -/// `--cluster.agency-endpoint endpoint` -/// -/// An agency endpoint the server can connect to. The option can be specified -/// multiple times so the server can use a cluster of agency servers. -/// Endpoints -/// have the following pattern: -/// -/// - tcp://ipv4-address:port - TCP/IP endpoint, using IPv4 -/// - tcp://[ipv6-address]:port - TCP/IP endpoint, using IPv6 -/// - ssl://ipv4-address:port - TCP/IP endpoint, using IPv4, SSL encryption -/// - ssl://[ipv6-address]:port - TCP/IP endpoint, using IPv6, SSL encryption -/// -/// At least one endpoint must be specified or ArangoDB will refuse to start. -/// It is recommended to specify at least two endpoints so ArangoDB has an -/// alternative endpoint if one of them becomes unavailable. -/// -/// @EXAMPLES -/// -/// ``` -/// --cluster.agency-endpoint tcp://192.168.1.1:4001 --cluster.agency-endpoint -/// tcp://192.168.1.2:4002 -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief list of agency endpoints +`--cluster.agency-endpoint endpoint` + +An agency endpoint the server can connect to. The option can be specified +multiple times so the server can use a cluster of agency servers. +Endpoints +have the following pattern: + +- tcp://ipv4-address:port - TCP/IP endpoint, using IPv4 +- tcp://[ipv6-address]:port - TCP/IP endpoint, using IPv6 +- ssl://ipv4-address:port - TCP/IP endpoint, using IPv4, SSL encryption +- ssl://[ipv6-address]:port - TCP/IP endpoint, using IPv6, SSL encryption + +At least one endpoint must be specified or ArangoDB will refuse to start. +It is recommended to specify at least two endpoints so ArangoDB has an +alternative endpoint if one of them becomes unavailable. + +@EXAMPLES + +``` +--cluster.agency-endpoint tcp://192.168.1.1:4001 --cluster.agency-endpoint +tcp://192.168.1.2:4002 +``` + diff --git a/Documentation/DocuBlocks/clusterAgencyPrefix.md b/Documentation/DocuBlocks/clusterAgencyPrefix.md index a0cf2573ac..a5a43d99bc 100644 --- a/Documentation/DocuBlocks/clusterAgencyPrefix.md +++ b/Documentation/DocuBlocks/clusterAgencyPrefix.md @@ -1,20 +1,19 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock clusterAgencyPrefix -/// @brief global agency prefix -/// `--cluster.agency-prefix prefix` -/// -/// The global key prefix used in all requests to the agency. The specified -/// prefix will become part of each agency key. Specifying the key prefix -/// allows managing multiple ArangoDB clusters with the same agency -/// server(s). -/// -/// *prefix* must consist of the letters *a-z*, *A-Z* and the digits *0-9* -/// only. Specifying a prefix is mandatory. -/// -/// @EXAMPLES -/// -/// ``` -/// --cluster.prefix mycluster -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief global agency prefix +`--cluster.agency-prefix prefix` + +The global key prefix used in all requests to the agency. The specified +prefix will become part of each agency key. Specifying the key prefix +allows managing multiple ArangoDB clusters with the same agency +server(s). + +*prefix* must consist of the letters *a-z*, *A-Z* and the digits *0-9* +only. Specifying a prefix is mandatory. + +@EXAMPLES + +``` +--cluster.prefix mycluster +``` + diff --git a/Documentation/DocuBlocks/clusterMyAddress.md b/Documentation/DocuBlocks/clusterMyAddress.md index 7329f94398..60fe134398 100644 --- a/Documentation/DocuBlocks/clusterMyAddress.md +++ b/Documentation/DocuBlocks/clusterMyAddress.md @@ -1,23 +1,22 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock clusterMyAddress -/// @brief this server's address / endpoint -/// `--cluster.my-address endpoint` -/// -/// The server's endpoint for cluster-internal communication. If specified, it -/// must have the following pattern: -/// - tcp://ipv4-address:port - TCP/IP endpoint, using IPv4 -/// - tcp://[ipv6-address]:port - TCP/IP endpoint, using IPv6 -/// - ssl://ipv4-address:port - TCP/IP endpoint, using IPv4, SSL encryption -/// - ssl://[ipv6-address]:port - TCP/IP endpoint, using IPv6, SSL encryption -/// -/// If no *endpoint* is specified, the server will look up its internal -/// endpoint address in the agency. If no endpoint can be found in the agency -/// for the server's id, ArangoDB will refuse to start. -/// -/// @EXAMPLES -/// -/// ``` -/// --cluster.my-address tcp://192.168.1.1:8530 -/// ``` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief this server's address / endpoint +`--cluster.my-address endpoint` + +The server's endpoint for cluster-internal communication. If specified, it +must have the following pattern: +- tcp://ipv4-address:port - TCP/IP endpoint, using IPv4 +- tcp://[ipv6-address]:port - TCP/IP endpoint, using IPv6 +- ssl://ipv4-address:port - TCP/IP endpoint, using IPv4, SSL encryption +- ssl://[ipv6-address]:port - TCP/IP endpoint, using IPv6, SSL encryption + +If no *endpoint* is specified, the server will look up its internal +endpoint address in the agency. If no endpoint can be found in the agency +for the server's id, ArangoDB will refuse to start. + +@EXAMPLES + +``` +--cluster.my-address tcp://192.168.1.1:8530 +``` + diff --git a/Documentation/DocuBlocks/clusterMyId.md b/Documentation/DocuBlocks/clusterMyId.md index 3f3252ea76..01f7ab37fc 100644 --- a/Documentation/DocuBlocks/clusterMyId.md +++ b/Documentation/DocuBlocks/clusterMyId.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock clusterMyId -/// @brief this server's id -/// `--cluster.my-id id` -/// -/// The local server's id in the cluster. Specifying *id* is mandatory on -/// startup. Each server of the cluster must have a unique id. -/// -/// Specifying the id is very important because the server id is used for -/// determining the server's role and tasks in the cluster. -/// -/// *id* must be a string consisting of the letters *a-z*, *A-Z* or the -/// digits *0-9* only. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief this server's id +`--cluster.my-id id` + +The local server's id in the cluster. Specifying *id* is mandatory on +startup. Each server of the cluster must have a unique id. + +Specifying the id is very important because the server id is used for +determining the server's role and tasks in the cluster. + +*id* must be a string consisting of the letters *a-z*, *A-Z* or the +digits *0-9* only. + diff --git a/Documentation/DocuBlocks/clusterMyLocalInfo.md b/Documentation/DocuBlocks/clusterMyLocalInfo.md index 6ac0f6a45f..de25cda2be 100644 --- a/Documentation/DocuBlocks/clusterMyLocalInfo.md +++ b/Documentation/DocuBlocks/clusterMyLocalInfo.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock clusterMyLocalInfo -/// @brief this server's id -/// `--cluster.my-local-info info` -/// -/// Some local information about the server in the cluster, this can for -/// example be an IP address with a process ID or any string unique to -/// the server. Specifying *info* is mandatory on startup if the server -/// id (see below) is not specified. Each server of the cluster must -/// have a unique local info. This is ignored if my-id below is specified. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief this server's id +`--cluster.my-local-info info` + +Some local information about the server in the cluster, this can for +example be an IP address with a process ID or any string unique to +the server. Specifying *info* is mandatory on startup if the server +id (see below) is not specified. Each server of the cluster must +have a unique local info. This is ignored if my-id below is specified. + diff --git a/Documentation/DocuBlocks/clusterPassword.md b/Documentation/DocuBlocks/clusterPassword.md index 4691261e31..0efe881a12 100644 --- a/Documentation/DocuBlocks/clusterPassword.md +++ b/Documentation/DocuBlocks/clusterPassword.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock clusterPassword -/// @brief password used for cluster-internal communication -/// `--cluster.password password` -/// -/// The password used for authorization of cluster-internal requests. -/// This password will be used to authenticate all requests and responses in -/// cluster-internal communication, i.e. requests exchanged between -/// coordinators -/// and individual database servers. -/// -/// This option is used for cluster-internal requests only. Regular requests -/// to -/// coordinators are authenticated normally using the data in the `_users` -/// collection. -/// -/// If coordinators and database servers are run with authentication turned -/// off, -/// (e.g. by setting the *--server.disable-authentication* option to *true*), -/// the cluster-internal communication will also be unauthenticated. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief password used for cluster-internal communication +`--cluster.password password` + +The password used for authorization of cluster-internal requests. +This password will be used to authenticate all requests and responses in +cluster-internal communication, i.e. requests exchanged between +coordinators +and individual database servers. + +This option is used for cluster-internal requests only. Regular requests +to +coordinators are authenticated normally using the data in the `_users` +collection. + +If coordinators and database servers are run with authentication turned +off, +(e.g. by setting the *--server.disable-authentication* option to *true*), +the cluster-internal communication will also be unauthenticated. + diff --git a/Documentation/DocuBlocks/clusterUsername.md b/Documentation/DocuBlocks/clusterUsername.md index 0a52561d0f..396bbbfb2a 100644 --- a/Documentation/DocuBlocks/clusterUsername.md +++ b/Documentation/DocuBlocks/clusterUsername.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock clusterUsername -/// @brief username used for cluster-internal communication -/// `--cluster.username username` -/// -/// The username used for authorization of cluster-internal requests. -/// This username will be used to authenticate all requests and responses in -/// cluster-internal communication, i.e. requests exchanged between -/// coordinators -/// and individual database servers. -/// -/// This option is used for cluster-internal requests only. Regular requests -/// to -/// coordinators are authenticated normally using the data in the *_users* -/// collection. -/// -/// If coordinators and database servers are run with authentication turned -/// off, -/// (e.g. by setting the *--server.disable-authentication* option to *true*), -/// the cluster-internal communication will also be unauthenticated. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief username used for cluster-internal communication +`--cluster.username username` + +The username used for authorization of cluster-internal requests. +This username will be used to authenticate all requests and responses in +cluster-internal communication, i.e. requests exchanged between +coordinators +and individual database servers. + +This option is used for cluster-internal requests only. Regular requests +to +coordinators are authenticated normally using the data in the *_users* +collection. + +If coordinators and database servers are run with authentication turned +off, +(e.g. by setting the *--server.disable-authentication* option to *true*), +the cluster-internal communication will also be unauthenticated. + diff --git a/Documentation/DocuBlocks/col_dropIndex.md b/Documentation/DocuBlocks/col_dropIndex.md index 925a92a92f..dc8404c3d7 100644 --- a/Documentation/DocuBlocks/col_dropIndex.md +++ b/Documentation/DocuBlocks/col_dropIndex.md @@ -1,27 +1,26 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock col_dropIndex -/// @brief drops an index -/// `collection.dropIndex(index)` -/// -/// Drops the index. If the index does not exist, then *false* is -/// returned. If the index existed and was dropped, then *true* is -/// returned. Note that you cannot drop some special indexes (e.g. the primary -/// index of a collection or the edge index of an edge collection). -/// -/// `collection.dropIndex(index-handle)` -/// -/// Same as above. Instead of an index an index handle can be given. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{col_dropIndex} -/// ~db._create("example"); -/// db.example.ensureSkiplist("a", "b"); -/// var indexInfo = db.example.getIndexes(); -/// indexInfo; -/// db.example.dropIndex(indexInfo[0]) -/// db.example.dropIndex(indexInfo[1].id) -/// indexInfo = db.example.getIndexes(); -/// ~db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief drops an index +`collection.dropIndex(index)` + +Drops the index. If the index does not exist, then *false* is +returned. If the index existed and was dropped, then *true* is +returned. Note that you cannot drop some special indexes (e.g. the primary +index of a collection or the edge index of an edge collection). + +`collection.dropIndex(index-handle)` + +Same as above. Instead of an index an index handle can be given. + +@EXAMPLE_ARANGOSH_OUTPUT{col_dropIndex} +~db._create("example"); +db.example.ensureSkiplist("a", "b"); +var indexInfo = db.example.getIndexes(); +indexInfo; +db.example.dropIndex(indexInfo[0]) +db.example.dropIndex(indexInfo[1].id) +indexInfo = db.example.getIndexes(); +~db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionAll.md b/Documentation/DocuBlocks/collectionAll.md index b22c437e63..66d231c4cb 100644 --- a/Documentation/DocuBlocks/collectionAll.md +++ b/Documentation/DocuBlocks/collectionAll.md @@ -1,39 +1,38 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionAll -/// @brief constructs an all query for a collection -/// `collection.all()` -/// -/// Fetches all documents from a collection and returns a cursor. You can use -/// *toArray*, *next*, or *hasNext* to access the result. The result -/// can be limited using the *skip* and *limit* operator. -/// -/// @EXAMPLES -/// -/// Use *toArray* to get all documents at once: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{001_collectionAll} -/// ~ db._create("five"); -/// db.five.save({ name : "one" }); -/// db.five.save({ name : "two" }); -/// db.five.save({ name : "three" }); -/// db.five.save({ name : "four" }); -/// db.five.save({ name : "five" }); -/// db.five.all().toArray(); -/// ~ db._drop("five"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Use *limit* to restrict the documents: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{002_collectionAllNext} -/// ~ db._create("five"); -/// db.five.save({ name : "one" }); -/// db.five.save({ name : "two" }); -/// db.five.save({ name : "three" }); -/// db.five.save({ name : "four" }); -/// db.five.save({ name : "five" }); -/// db.five.all().limit(2).toArray(); -/// ~ db._drop("five"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief constructs an all query for a collection +`collection.all()` + +Fetches all documents from a collection and returns a cursor. You can use +*toArray*, *next*, or *hasNext* to access the result. The result +can be limited using the *skip* and *limit* operator. + +@EXAMPLES + +Use *toArray* to get all documents at once: + +@EXAMPLE_ARANGOSH_OUTPUT{001_collectionAll} +~ db._create("five"); + db.five.save({ name : "one" }); + db.five.save({ name : "two" }); + db.five.save({ name : "three" }); + db.five.save({ name : "four" }); + db.five.save({ name : "five" }); + db.five.all().toArray(); +~ db._drop("five"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Use *limit* to restrict the documents: + +@EXAMPLE_ARANGOSH_OUTPUT{002_collectionAllNext} +~ db._create("five"); + db.five.save({ name : "one" }); + db.five.save({ name : "two" }); + db.five.save({ name : "three" }); + db.five.save({ name : "four" }); + db.five.save({ name : "five" }); + db.five.all().limit(2).toArray(); +~ db._drop("five"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionByExample.md b/Documentation/DocuBlocks/collectionByExample.md index 6b4912a70d..ea98d73964 100644 --- a/Documentation/DocuBlocks/collectionByExample.md +++ b/Documentation/DocuBlocks/collectionByExample.md @@ -1,75 +1,74 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionByExample -/// @brief constructs a query-by-example for a collection -/// `collection.byExample(example)` -/// -/// Fetches all documents from a collection that match the specified -/// example and returns a cursor. -/// -/// You can use *toArray*, *next*, or *hasNext* to access the -/// result. The result can be limited using the *skip* and *limit* -/// operator. -/// -/// An attribute name of the form *a.b* is interpreted as attribute path, -/// not as attribute. If you use -/// -/// *{ a : { c : 1 } }* -/// -/// as example, then you will find all documents, such that the attribute -/// *a* contains a document of the form *{c : 1 }*. For example the document -/// -/// *{ a : { c : 1 }, b : 1 }* -/// -/// will match, but the document -/// -/// *{ a : { c : 1, b : 1 } }* -/// -/// will not. -/// -/// However, if you use -/// -/// *{ a.c : 1 }*, -/// -/// then you will find all documents, which contain a sub-document in *a* -/// that has an attribute *c* of value *1*. Both the following documents -/// -/// *{ a : { c : 1 }, b : 1 }* and -/// -/// *{ a : { c : 1, b : 1 } }* -/// -/// will match. -/// -/// `collection.byExample(path1, value1, ...)` -/// -/// As alternative you can supply an array of paths and values. -/// -/// @EXAMPLES -/// -/// Use *toArray* to get all documents at once: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{003_collectionByExample} -/// ~ db._create("users"); -/// db.users.save({ name: "Gerhard" }); -/// db.users.save({ name: "Helmut" }); -/// db.users.save({ name: "Angela" }); -/// db.users.all().toArray(); -/// db.users.byExample({ "_id" : "users/20" }).toArray(); -/// db.users.byExample({ "name" : "Gerhard" }).toArray(); -/// db.users.byExample({ "name" : "Helmut", "_id" : "users/15" }).toArray(); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Use *next* to loop over all documents: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{004_collectionByExampleNext} -/// ~ db._create("users"); -/// db.users.save({ name: "Gerhard" }); -/// db.users.save({ name: "Helmut" }); -/// db.users.save({ name: "Angela" }); -/// var a = db.users.byExample( {"name" : "Angela" } ); -/// while (a.hasNext()) print(a.next()); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief constructs a query-by-example for a collection +`collection.byExample(example)` + +Fetches all documents from a collection that match the specified +example and returns a cursor. + +You can use *toArray*, *next*, or *hasNext* to access the +result. The result can be limited using the *skip* and *limit* +operator. + +An attribute name of the form *a.b* is interpreted as attribute path, +not as attribute. If you use + +*{ a : { c : 1 } }* + +as example, then you will find all documents, such that the attribute +*a* contains a document of the form *{c : 1 }*. For example the document + +*{ a : { c : 1 }, b : 1 }* + +will match, but the document + +*{ a : { c : 1, b : 1 } }* + +will not. + +However, if you use + +*{ a.c : 1 }*, + +then you will find all documents, which contain a sub-document in *a* +that has an attribute *c* of value *1*. Both the following documents + +*{ a : { c : 1 }, b : 1 }* and + +*{ a : { c : 1, b : 1 } }* + +will match. + +`collection.byExample(path1, value1, ...)` + +As alternative you can supply an array of paths and values. + +@EXAMPLES + +Use *toArray* to get all documents at once: + +@EXAMPLE_ARANGOSH_OUTPUT{003_collectionByExample} +~ db._create("users"); + db.users.save({ name: "Gerhard" }); + db.users.save({ name: "Helmut" }); + db.users.save({ name: "Angela" }); + db.users.all().toArray(); + db.users.byExample({ "_id" : "users/20" }).toArray(); + db.users.byExample({ "name" : "Gerhard" }).toArray(); + db.users.byExample({ "name" : "Helmut", "_id" : "users/15" }).toArray(); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Use *next* to loop over all documents: + +@EXAMPLE_ARANGOSH_OUTPUT{004_collectionByExampleNext} +~ db._create("users"); + db.users.save({ name: "Gerhard" }); + db.users.save({ name: "Helmut" }); + db.users.save({ name: "Angela" }); + var a = db.users.byExample( {"name" : "Angela" } ); + while (a.hasNext()) print(a.next()); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionByExampleSkiplist.md b/Documentation/DocuBlocks/collectionByExampleSkiplist.md index f1f3a09117..fb5023482d 100644 --- a/Documentation/DocuBlocks/collectionByExampleSkiplist.md +++ b/Documentation/DocuBlocks/collectionByExampleSkiplist.md @@ -1,44 +1,43 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionByExampleSkiplist -/// @brief constructs a query-by-example using a skiplist index -/// `collection.byExampleSkiplist(index, example)` -/// -/// Selects all documents from the specified skiplist index that match the -/// specified example and returns a cursor. -/// -/// You can use *toArray*, *next*, or *hasNext* to access the -/// result. The result can be limited using the *skip* and *limit* -/// operator. -/// -/// An attribute name of the form *a.b* is interpreted as attribute path, -/// not as attribute. If you use -/// -/// *{ a : { c : 1 } }* -/// -/// as example, then you will find all documents, such that the attribute -/// *a* contains a document of the form *{c : 1 }*. For example the document -/// -/// *{ a : { c : 1 }, b : 1 }* -/// -/// will match, but the document -/// -/// *{ a : { c : 1, b : 1 } }* -/// -/// will not. -/// -/// However, if you use -/// -/// *{ a.c : 1 }*, -/// -/// then you will find all documents, which contain a sub-document in *a* -/// that has an attribute @LIT{c} of value *1*. Both the following documents -/// -/// *{ a : { c : 1 }, b : 1 }*and -/// -/// *{ a : { c : 1, b : 1 } }* -/// -/// will match. -/// -/// `collection.byExampleSkiplist(index, path1, value1, ...)` -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief constructs a query-by-example using a skiplist index +`collection.byExampleSkiplist(index, example)` + +Selects all documents from the specified skiplist index that match the +specified example and returns a cursor. + +You can use *toArray*, *next*, or *hasNext* to access the +result. The result can be limited using the *skip* and *limit* +operator. + +An attribute name of the form *a.b* is interpreted as attribute path, +not as attribute. If you use + +*{ a : { c : 1 } }* + +as example, then you will find all documents, such that the attribute +*a* contains a document of the form *{c : 1 }*. For example the document + +*{ a : { c : 1 }, b : 1 }* + +will match, but the document + +*{ a : { c : 1, b : 1 } }* + +will not. + +However, if you use + +*{ a.c : 1 }*, + +then you will find all documents, which contain a sub-document in *a* +that has an attribute @LIT{c} of value *1*. Both the following documents + +*{ a : { c : 1 }, b : 1 }*and + +*{ a : { c : 1, b : 1 } }* + +will match. + +`collection.byExampleSkiplist(index, path1, value1, ...)` + diff --git a/Documentation/DocuBlocks/collectionChecksum.md b/Documentation/DocuBlocks/collectionChecksum.md index dff77af7e1..27ab1c5fa3 100644 --- a/Documentation/DocuBlocks/collectionChecksum.md +++ b/Documentation/DocuBlocks/collectionChecksum.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionChecksum -/// @brief calculates a checksum for the data in a collection -/// `collection.checksum(withRevisions, withData)` -/// -/// The *checksum* operation calculates a CRC32 checksum of the keys -/// contained in collection *collection*. -/// -/// If the optional argument *withRevisions* is set to *true*, then the -/// revision ids of the documents are also included in the checksumming. -/// -/// If the optional argument *withData* is set to *true*, then the -/// actual document data is also checksummed. Including the document data in -/// checksumming will make the calculation slower, but is more accurate. -/// -/// **Note**: this method is not available in a cluster. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief calculates a checksum for the data in a collection +`collection.checksum(withRevisions, withData)` + +The *checksum* operation calculates a CRC32 checksum of the keys +contained in collection *collection*. + +If the optional argument *withRevisions* is set to *true*, then the +revision ids of the documents are also included in the checksumming. + +If the optional argument *withData* is set to *true*, then the +actual document data is also checksummed. Including the document data in +checksumming will make the calculation slower, but is more accurate. + +**Note**: this method is not available in a cluster. + + diff --git a/Documentation/DocuBlocks/collectionClosedRange.md b/Documentation/DocuBlocks/collectionClosedRange.md index 50b3920101..6493489b23 100644 --- a/Documentation/DocuBlocks/collectionClosedRange.md +++ b/Documentation/DocuBlocks/collectionClosedRange.md @@ -1,40 +1,39 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionClosedRange -/// @brief constructs a closed range query for a collection -/// `collection.closedRange(attribute, left, right)` -/// -/// Returns all documents of a collection such that the *attribute* is -/// greater or equal than *left* and less or equal than *right*. -/// -/// You can use *toArray*, *next*, or *hasNext* to access the -/// result. The result can be limited using the *skip* and *limit* -/// operator. -/// -/// An attribute name of the form *a.b* is interpreted as attribute path, -/// not as attribute. -/// -/// Note: the *closedRange* simple query function is **deprecated** as of ArangoDB 2.6. -/// The function may be removed in future versions of ArangoDB. The preferred -/// way for retrieving documents from a collection within a specific range -/// is to use an AQL query as follows: -/// -/// FOR doc IN @@collection -/// FILTER doc.value >= @left && doc.value <= @right -/// LIMIT @skip, @limit -/// RETURN doc -/// -/// @EXAMPLES -/// -/// Use *toArray* to get all documents at once: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{006_collectionClosedRange} -/// ~ db._create("old"); -/// db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] }); -/// db.old.save({ age: 15 }); -/// db.old.save({ age: 25 }); -/// db.old.save({ age: 30 }); -/// db.old.closedRange("age", 10, 30).toArray(); -/// ~ db._drop("old") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief constructs a closed range query for a collection +`collection.closedRange(attribute, left, right)` + +Returns all documents of a collection such that the *attribute* is +greater or equal than *left* and less or equal than *right*. + +You can use *toArray*, *next*, or *hasNext* to access the +result. The result can be limited using the *skip* and *limit* +operator. + +An attribute name of the form *a.b* is interpreted as attribute path, +not as attribute. + +Note: the *closedRange* simple query function is **deprecated** as of ArangoDB 2.6. +The function may be removed in future versions of ArangoDB. The preferred +way for retrieving documents from a collection within a specific range +is to use an AQL query as follows: + + FOR doc IN @@collection + FILTER doc.value >= @left && doc.value <= @right + LIMIT @skip, @limit + RETURN doc + +@EXAMPLES + +Use *toArray* to get all documents at once: + +@EXAMPLE_ARANGOSH_OUTPUT{006_collectionClosedRange} +~ db._create("old"); + db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] }); + db.old.save({ age: 15 }); + db.old.save({ age: 25 }); + db.old.save({ age: 30 }); + db.old.closedRange("age", 10, 30).toArray(); +~ db._drop("old") +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionCount.md b/Documentation/DocuBlocks/collectionCount.md index 4ac9feb138..23b1d7dbc6 100644 --- a/Documentation/DocuBlocks/collectionCount.md +++ b/Documentation/DocuBlocks/collectionCount.md @@ -1,17 +1,16 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionCount -/// @brief counts the number of documents in a result set -/// `collection.count()` -/// -/// Returns the number of living documents in the collection. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionCount} -/// ~ db._create("users"); -/// db.users.count(); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief counts the number of documents in a result set +`collection.count()` + +Returns the number of living documents in the collection. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionCount} +~ db._create("users"); + db.users.count(); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionCreateDocumentCollection.md b/Documentation/DocuBlocks/collectionCreateDocumentCollection.md index 3536dbbe08..1e564e91e2 100644 --- a/Documentation/DocuBlocks/collectionCreateDocumentCollection.md +++ b/Documentation/DocuBlocks/collectionCreateDocumentCollection.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionCreateDocumentCollection -/// @brief creates a new document collection -/// `db._createDocumentCollection(collection-name)` -/// -/// Creates a new document collection named *collection-name*. If the -/// document name already exists and error is thrown. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief creates a new document collection +`db._createDocumentCollection(collection-name)` + +Creates a new document collection named *collection-name*. If the +document name already exists and error is thrown. + diff --git a/Documentation/DocuBlocks/collectionCreateEdgeCollection.md b/Documentation/DocuBlocks/collectionCreateEdgeCollection.md index a7ad909558..29bff7c9e4 100644 --- a/Documentation/DocuBlocks/collectionCreateEdgeCollection.md +++ b/Documentation/DocuBlocks/collectionCreateEdgeCollection.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionCreateEdgeCollection -/// @brief creates a new edge collection -/// `db._createEdgeCollection(collection-name)` -/// -/// Creates a new edge collection named *collection-name*. If the -/// collection name already exists an error is thrown. The default value -/// for *waitForSync* is *false*. -/// -/// `db._createEdgeCollection(collection-name, properties)` -/// -/// *properties* must be an object with the following attributes: -/// -/// * *waitForSync* (optional, default *false*): If *true* creating -/// a document will only return after the data was synced to disk. -/// * *journalSize* (optional, default is -/// "configuration parameter"): The maximal size of -/// a journal or datafile. Note that this also limits the maximal -/// size of a single object and must be at least 1MB. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief creates a new edge collection +`db._createEdgeCollection(collection-name)` + +Creates a new edge collection named *collection-name*. If the +collection name already exists an error is thrown. The default value +for *waitForSync* is *false*. + +`db._createEdgeCollection(collection-name, properties)` + +*properties* must be an object with the following attributes: + +* *waitForSync* (optional, default *false*): If *true* creating + a document will only return after the data was synced to disk. +* *journalSize* (optional, default is + "configuration parameter"): The maximal size of + a journal or datafile. Note that this also limits the maximal + size of a single object and must be at least 1MB. + + diff --git a/Documentation/DocuBlocks/collectionDatabaseCollectionName.md b/Documentation/DocuBlocks/collectionDatabaseCollectionName.md index 458eb8e815..d90eedc4da 100644 --- a/Documentation/DocuBlocks/collectionDatabaseCollectionName.md +++ b/Documentation/DocuBlocks/collectionDatabaseCollectionName.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionDatabaseCollectionName -/// @brief selects a collection from the vocbase -/// `db.collection-name` -/// -/// Returns the collection with the given *collection-name*. If no such -/// collection exists, create a collection named *collection-name* with the -/// default properties. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCollectionName} -/// ~ db._create("example"); -/// db.example; -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief selects a collection from the vocbase +`db.collection-name` + +Returns the collection with the given *collection-name*. If no such +collection exists, create a collection named *collection-name* with the +default properties. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCollectionName} +~ db._create("example"); + db.example; +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionDatabaseCreate.md b/Documentation/DocuBlocks/collectionDatabaseCreate.md index f5693f2edd..1673602023 100644 --- a/Documentation/DocuBlocks/collectionDatabaseCreate.md +++ b/Documentation/DocuBlocks/collectionDatabaseCreate.md @@ -1,127 +1,126 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionDatabaseCreate -/// @brief creates a new document or edge collection -/// `db._create(collection-name)` -/// -/// Creates a new document collection named *collection-name*. -/// If the collection name already exists or if the name format is invalid, an -/// error is thrown. For more information on valid collection names please refer -/// to the [naming conventions](../NamingConventions/README.md). -/// -/// `db._create(collection-name, properties)` -/// -/// *properties* must be an object with the following attributes: -/// -/// * *waitForSync* (optional, default *false*): If *true* creating -/// a document will only return after the data was synced to disk. -/// -/// * *journalSize* (optional, default is a -/// configuration parameter: The maximal -/// size of a journal or datafile. Note that this also limits the maximal -/// size of a single object. Must be at least 1MB. -/// -/// * *isSystem* (optional, default is *false*): If *true*, create a -/// system collection. In this case *collection-name* should start with -/// an underscore. End users should normally create non-system collections -/// only. API implementors may be required to create system collections in -/// very special occasions, but normally a regular collection will do. -/// -/// * *isVolatile* (optional, default is *false*): If *true then the -/// collection data is kept in-memory only and not made persistent. Unloading -/// the collection will cause the collection data to be discarded. Stopping -/// or re-starting the server will also cause full loss of data in the -/// collection. Setting this option will make the resulting collection be -/// slightly faster than regular collections because ArangoDB does not -/// enforce any synchronization to disk and does not calculate any CRC -/// checksums for datafiles (as there are no datafiles). -/// -/// * *keyOptions* (optional): additional options for key generation. If -/// specified, then *keyOptions* should be a JSON array containing the -/// following attributes (**note**: some of them are optional): -/// * *type*: specifies the type of the key generator. The currently -/// available generators are *traditional* and *autoincrement*. -/// * *allowUserKeys*: if set to *true*, then it is allowed to supply -/// own key values in the *_key* attribute of a document. If set to -/// *false*, then the key generator will solely be responsible for -/// generating keys and supplying own key values in the *_key* attribute -/// of documents is considered an error. -/// * *increment*: increment value for *autoincrement* key generator. -/// Not used for other key generator types. -/// * *offset*: initial offset value for *autoincrement* key generator. -/// Not used for other key generator types. -/// -/// * *numberOfShards* (optional, default is *1*): in a cluster, this value -/// determines the number of shards to create for the collection. In a single -/// server setup, this option is meaningless. -/// -/// * *shardKeys* (optional, default is *[ "_key" ]*): in a cluster, this -/// attribute determines which document attributes are used to determine the -/// target shard for documents. Documents are sent to shards based on the -/// values they have in their shard key attributes. The values of all shard -/// key attributes in a document are hashed, and the hash value is used to -/// determine the target shard. Note that values of shard key attributes cannot -/// be changed once set. -/// This option is meaningless in a single server setup. -/// -/// When choosing the shard keys, one must be aware of the following -/// rules and limitations: In a sharded collection with more than -/// one shard it is not possible to set up a unique constraint on -/// an attribute that is not the one and only shard key given in -/// *shardKeys*. This is because enforcing a unique constraint -/// would otherwise make a global index necessary or need extensive -/// communication for every single write operation. Furthermore, if -/// *_key* is not the one and only shard key, then it is not possible -/// to set the *_key* attribute when inserting a document, provided -/// the collection has more than one shard. Again, this is because -/// the database has to enforce the unique constraint on the *_key* -/// attribute and this can only be done efficiently if this is the -/// only shard key by delegating to the individual shards. -/// -/// `db._create(collection-name, properties, type)` -/// -/// Specifies the optional *type* of the collection, it can either be *document* -/// or *edge*. On default it is document. Instead of giving a type you can also use -/// *db._createEdgeCollection* or *db._createDocumentCollection*. -/// -/// @EXAMPLES -/// -/// With defaults: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreate} -/// c = db._create("users"); -/// c.properties(); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// With properties: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreateProperties} -/// |c = db._create("users", { waitForSync : true, -/// journalSize : 1024 * 1204}); -/// c.properties(); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// With a key generator: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreateKey} -/// | db._create("users", -/// { keyOptions: { type: "autoincrement", offset: 10, increment: 5 } }); -/// db.users.save({ name: "user 1" }); -/// db.users.save({ name: "user 2" }); -/// db.users.save({ name: "user 3" }); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// With a special key option: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreateSpecialKey} -/// db._create("users", { keyOptions: { allowUserKeys: false } }); -/// db.users.save({ name: "user 1" }); -/// | db.users.save({ name: "user 2", _key: "myuser" }); -/// ~ // xpError(ERROR_ARANGO_DOCUMENT_KEY_UNEXPECTED) -/// db.users.save({ name: "user 3" }); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief creates a new document or edge collection +`db._create(collection-name)` + +Creates a new document collection named *collection-name*. +If the collection name already exists or if the name format is invalid, an +error is thrown. For more information on valid collection names please refer +to the [naming conventions](../NamingConventions/README.md). + +`db._create(collection-name, properties)` + +*properties* must be an object with the following attributes: + +* *waitForSync* (optional, default *false*): If *true* creating + a document will only return after the data was synced to disk. + +* *journalSize* (optional, default is a + configuration parameter: The maximal + size of a journal or datafile. Note that this also limits the maximal + size of a single object. Must be at least 1MB. + +* *isSystem* (optional, default is *false*): If *true*, create a + system collection. In this case *collection-name* should start with + an underscore. End users should normally create non-system collections + only. API implementors may be required to create system collections in + very special occasions, but normally a regular collection will do. + +* *isVolatile* (optional, default is *false*): If *true then the + collection data is kept in-memory only and not made persistent. Unloading + the collection will cause the collection data to be discarded. Stopping + or re-starting the server will also cause full loss of data in the + collection. Setting this option will make the resulting collection be + slightly faster than regular collections because ArangoDB does not + enforce any synchronization to disk and does not calculate any CRC + checksums for datafiles (as there are no datafiles). + +* *keyOptions* (optional): additional options for key generation. If + specified, then *keyOptions* should be a JSON array containing the + following attributes (**note**: some of them are optional): + * *type*: specifies the type of the key generator. The currently + available generators are *traditional* and *autoincrement*. + * *allowUserKeys*: if set to *true*, then it is allowed to supply + own key values in the *_key* attribute of a document. If set to + *false*, then the key generator will solely be responsible for + generating keys and supplying own key values in the *_key* attribute + of documents is considered an error. + * *increment*: increment value for *autoincrement* key generator. + Not used for other key generator types. + * *offset*: initial offset value for *autoincrement* key generator. + Not used for other key generator types. + +* *numberOfShards* (optional, default is *1*): in a cluster, this value + determines the number of shards to create for the collection. In a single + server setup, this option is meaningless. + +* *shardKeys* (optional, default is *[ "_key" ]*): in a cluster, this + attribute determines which document attributes are used to determine the + target shard for documents. Documents are sent to shards based on the + values they have in their shard key attributes. The values of all shard + key attributes in a document are hashed, and the hash value is used to + determine the target shard. Note that values of shard key attributes cannot + be changed once set. + This option is meaningless in a single server setup. + + When choosing the shard keys, one must be aware of the following + rules and limitations: In a sharded collection with more than + one shard it is not possible to set up a unique constraint on + an attribute that is not the one and only shard key given in + *shardKeys*. This is because enforcing a unique constraint + would otherwise make a global index necessary or need extensive + communication for every single write operation. Furthermore, if + *_key* is not the one and only shard key, then it is not possible + to set the *_key* attribute when inserting a document, provided + the collection has more than one shard. Again, this is because + the database has to enforce the unique constraint on the *_key* + attribute and this can only be done efficiently if this is the + only shard key by delegating to the individual shards. + +`db._create(collection-name, properties, type)` + +Specifies the optional *type* of the collection, it can either be *document* +or *edge*. On default it is document. Instead of giving a type you can also use +*db._createEdgeCollection* or *db._createDocumentCollection*. + +@EXAMPLES + +With defaults: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreate} + c = db._create("users"); + c.properties(); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +With properties: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreateProperties} + |c = db._create("users", { waitForSync : true, + journalSize : 1024 * 1204}); + c.properties(); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +With a key generator: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreateKey} +| db._create("users", + { keyOptions: { type: "autoincrement", offset: 10, increment: 5 } }); + db.users.save({ name: "user 1" }); + db.users.save({ name: "user 2" }); + db.users.save({ name: "user 3" }); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +With a special key option: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseCreateSpecialKey} + db._create("users", { keyOptions: { allowUserKeys: false } }); + db.users.save({ name: "user 1" }); +| db.users.save({ name: "user 2", _key: "myuser" }); +~ // xpError(ERROR_ARANGO_DOCUMENT_KEY_UNEXPECTED) + db.users.save({ name: "user 3" }); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionDatabaseDrop.md b/Documentation/DocuBlocks/collectionDatabaseDrop.md index 72b69becc2..0a359f4ed6 100644 --- a/Documentation/DocuBlocks/collectionDatabaseDrop.md +++ b/Documentation/DocuBlocks/collectionDatabaseDrop.md @@ -1,40 +1,39 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionDatabaseDrop -/// @brief drops a collection -/// `db._drop(collection)` -/// -/// Drops a *collection* and all its indexes. -/// -/// `db._drop(collection-identifier)` -/// -/// Drops a collection identified by *collection-identifier* and all its -/// indexes. No error is thrown if there is no such collection. -/// -/// `db._drop(collection-name)` -/// -/// Drops a collection named *collection-name* and all its indexes. No error -/// is thrown if there is no such collection. -/// -/// *Examples* -/// -/// Drops a collection: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseDrop} -/// ~ db._create("example"); -/// col = db.example; -/// db._drop(col); -/// col; -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Drops a collection identified by name: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseDropName} -/// ~ db._create("example"); -/// col = db.example; -/// db._drop("example"); -/// col; -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief drops a collection +`db._drop(collection)` + +Drops a *collection* and all its indexes. + +`db._drop(collection-identifier)` + +Drops a collection identified by *collection-identifier* and all its +indexes. No error is thrown if there is no such collection. + +`db._drop(collection-name)` + +Drops a collection named *collection-name* and all its indexes. No error +is thrown if there is no such collection. + +*Examples* + +Drops a collection: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseDrop} +~ db._create("example"); + col = db.example; + db._drop(col); + col; +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Drops a collection identified by name: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseDropName} +~ db._create("example"); + col = db.example; + db._drop("example"); + col; +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionDatabaseName.md b/Documentation/DocuBlocks/collectionDatabaseName.md index caa3276cb3..1a62488e7e 100644 --- a/Documentation/DocuBlocks/collectionDatabaseName.md +++ b/Documentation/DocuBlocks/collectionDatabaseName.md @@ -1,36 +1,35 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionDatabaseName -/// @brief returns a single collection or null -/// `db._collection(collection-name)` -/// -/// Returns the collection with the given name or null if no such collection -/// exists. -/// -/// `db._collection(collection-identifier)` -/// -/// Returns the collection with the given identifier or null if no such -/// collection exists. Accessing collections by identifier is discouraged for -/// end users. End users should access collections using the collection name. -/// -/// @EXAMPLES -/// -/// Get a collection by name: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseName} -/// db._collection("demo"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Get a collection by id: -/// -/// ``` -/// arangosh> db._collection(123456); -/// [ArangoCollection 123456, "demo" (type document, status loaded)] -/// ``` -/// -/// Unknown collection: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseNameUnknown} -/// db._collection("unknown"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns a single collection or null +`db._collection(collection-name)` + +Returns the collection with the given name or null if no such collection +exists. + +`db._collection(collection-identifier)` + +Returns the collection with the given identifier or null if no such +collection exists. Accessing collections by identifier is discouraged for +end users. End users should access collections using the collection name. + +@EXAMPLES + +Get a collection by name: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseName} + db._collection("demo"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Get a collection by id: + +``` +arangosh> db._collection(123456); +[ArangoCollection 123456, "demo" (type document, status loaded)] +``` + +Unknown collection: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseNameUnknown} + db._collection("unknown"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionDatabaseNameAll.md b/Documentation/DocuBlocks/collectionDatabaseNameAll.md index a1081b6464..5bc8865b39 100644 --- a/Documentation/DocuBlocks/collectionDatabaseNameAll.md +++ b/Documentation/DocuBlocks/collectionDatabaseNameAll.md @@ -1,17 +1,16 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionDatabaseNameAll -/// @brief returns all collections -/// `db._collections()` -/// -/// Returns all collections of the given database. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionsDatabaseName} -/// ~ db._create("example"); -/// db._collections(); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns all collections +`db._collections()` + +Returns all collections of the given database. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionsDatabaseName} +~ db._create("example"); + db._collections(); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionDatabaseTruncate.md b/Documentation/DocuBlocks/collectionDatabaseTruncate.md index e392a31cf9..ff7841e48b 100644 --- a/Documentation/DocuBlocks/collectionDatabaseTruncate.md +++ b/Documentation/DocuBlocks/collectionDatabaseTruncate.md @@ -1,46 +1,45 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionDatabaseTruncate -/// @brief truncates a collection -/// `db._truncate(collection)` -/// -/// Truncates a *collection*, removing all documents but keeping all its -/// indexes. -/// -/// `db._truncate(collection-identifier)` -/// -/// Truncates a collection identified by *collection-identified*. No error is -/// thrown if there is no such collection. -/// -/// `db._truncate(collection-name)` -/// -/// Truncates a collection named *collection-name*. No error is thrown if -/// there is no such collection. -/// -/// @EXAMPLES -/// -/// Truncates a collection: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseTruncate} -/// ~ db._create("example"); -/// col = db.example; -/// col.save({ "Hello" : "World" }); -/// col.count(); -/// db._truncate(col); -/// col.count(); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Truncates a collection identified by name: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseTruncateName} -/// ~ db._create("example"); -/// col = db.example; -/// col.save({ "Hello" : "World" }); -/// col.count(); -/// db._truncate("example"); -/// col.count(); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief truncates a collection +`db._truncate(collection)` + +Truncates a *collection*, removing all documents but keeping all its +indexes. + +`db._truncate(collection-identifier)` + +Truncates a collection identified by *collection-identified*. No error is +thrown if there is no such collection. + +`db._truncate(collection-name)` + +Truncates a collection named *collection-name*. No error is thrown if +there is no such collection. + +@EXAMPLES + +Truncates a collection: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseTruncate} +~ db._create("example"); + col = db.example; + col.save({ "Hello" : "World" }); + col.count(); + db._truncate(col); + col.count(); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Truncates a collection identified by name: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDatabaseTruncateName} +~ db._create("example"); + col = db.example; + col.save({ "Hello" : "World" }); + col.count(); + db._truncate("example"); + col.count(); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionDrop.md b/Documentation/DocuBlocks/collectionDrop.md index 702d23c916..222bdb4831 100644 --- a/Documentation/DocuBlocks/collectionDrop.md +++ b/Documentation/DocuBlocks/collectionDrop.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionDrop -/// @brief drops a collection -/// `collection.drop()` -/// -/// Drops a *collection* and all its indexes. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionDrop} -/// ~ db._create("example"); -/// col = db.example; -/// col.drop(); -/// col; -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief drops a collection +`collection.drop()` + +Drops a *collection* and all its indexes. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionDrop} +~ db._create("example"); + col = db.example; + col.drop(); + col; +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionEdgesAll.md b/Documentation/DocuBlocks/collectionEdgesAll.md index 8f7e40e171..f7b8e4adda 100644 --- a/Documentation/DocuBlocks/collectionEdgesAll.md +++ b/Documentation/DocuBlocks/collectionEdgesAll.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionEdgesAll -/// @brief returns all edges connected to a vertex -/// `collection.edges(vertex-id)` -/// -/// Returns all edges connected to the vertex specified by *vertex-id*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns all edges connected to a vertex +`collection.edges(vertex-id)` + +Returns all edges connected to the vertex specified by *vertex-id*. + diff --git a/Documentation/DocuBlocks/collectionEdgesInbound.md b/Documentation/DocuBlocks/collectionEdgesInbound.md index 57e6b39380..0c03c8b986 100644 --- a/Documentation/DocuBlocks/collectionEdgesInbound.md +++ b/Documentation/DocuBlocks/collectionEdgesInbound.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionEdgesInbound -/// @brief returns inbound edges connected to a vertex -/// `collection.inEdges(vertex-id)` -/// -/// Returns inbound edges connected to the vertex specified by *vertex-id*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns inbound edges connected to a vertex +`collection.inEdges(vertex-id)` + +Returns inbound edges connected to the vertex specified by *vertex-id*. + diff --git a/Documentation/DocuBlocks/collectionEdgesOutbound.md b/Documentation/DocuBlocks/collectionEdgesOutbound.md index 9aa9c3b203..d2f0077942 100644 --- a/Documentation/DocuBlocks/collectionEdgesOutbound.md +++ b/Documentation/DocuBlocks/collectionEdgesOutbound.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionEdgesOutbound -/// @brief returns outbound edges connected to a vertex -/// `collection.outEdges(vertex-id)` -/// -/// Returns outbound edges connected to the vertex specified by *vertex-id*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns outbound edges connected to a vertex +`collection.outEdges(vertex-id)` + +Returns outbound edges connected to the vertex specified by *vertex-id*. + diff --git a/Documentation/DocuBlocks/collectionEnsureCapConstraint.md b/Documentation/DocuBlocks/collectionEnsureCapConstraint.md index 6b08a53ca2..042bfc6405 100644 --- a/Documentation/DocuBlocks/collectionEnsureCapConstraint.md +++ b/Documentation/DocuBlocks/collectionEnsureCapConstraint.md @@ -1,38 +1,37 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionEnsureCapConstraint -/// @brief ensures that a cap constraint exists -/// `collection.ensureIndex({ type: "cap", size: size, byteSize: byteSize })` -/// -/// Creates a size restriction aka cap for the collection of `size` -/// documents and/or `byteSize` data size. If the restriction is in place -/// and the (`size` plus one) document is added to the collection, or the -/// total active data size in the collection exceeds `byteSize`, then the -/// least recently created or updated documents are removed until all -/// constraints are satisfied. -/// -/// It is allowed to specify either `size` or `byteSize`, or both at -/// the same time. If both are specified, then the automatic document removal -/// will be triggered by the first non-met constraint. -/// -/// Note that at most one cap constraint is allowed per collection. Trying -/// to create additional cap constraints will result in an error. Creating -/// cap constraints is also not supported in sharded collections with more -/// than one shard. -/// -/// Note that this does not imply any restriction of the number of revisions -/// of documents. -/// -/// @EXAMPLES -/// -/// Restrict the number of document to at most 10 documents: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionEnsureCapConstraint} -/// ~db._create('examples'); -/// db.examples.ensureIndex({ type: "cap", size: 10 }); -/// for (var i = 0; i < 20; ++i) { var d = db.examples.save( { n : i } ); } -/// db.examples.count(); -/// ~db._drop('examples'); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a cap constraint exists +`collection.ensureIndex({ type: "cap", size: size, byteSize: byteSize })` + +Creates a size restriction aka cap for the collection of `size` +documents and/or `byteSize` data size. If the restriction is in place +and the (`size` plus one) document is added to the collection, or the +total active data size in the collection exceeds `byteSize`, then the +least recently created or updated documents are removed until all +constraints are satisfied. + +It is allowed to specify either `size` or `byteSize`, or both at +the same time. If both are specified, then the automatic document removal +will be triggered by the first non-met constraint. + +Note that at most one cap constraint is allowed per collection. Trying +to create additional cap constraints will result in an error. Creating +cap constraints is also not supported in sharded collections with more +than one shard. + +Note that this does not imply any restriction of the number of revisions +of documents. + +@EXAMPLES + +Restrict the number of document to at most 10 documents: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionEnsureCapConstraint} +~db._create('examples'); + db.examples.ensureIndex({ type: "cap", size: 10 }); + for (var i = 0; i < 20; ++i) { var d = db.examples.save( { n : i } ); } + db.examples.count(); +~db._drop('examples'); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionEnsureGeoConstraint.md b/Documentation/DocuBlocks/collectionEnsureGeoConstraint.md index 08f66e64c3..4678c4c4ec 100644 --- a/Documentation/DocuBlocks/collectionEnsureGeoConstraint.md +++ b/Documentation/DocuBlocks/collectionEnsureGeoConstraint.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionEnsureGeoConstraint -/// @brief ensures that a geo constraint exists -/// `collection.ensureIndex({ type: "geo", fields: [ "location" ] })` -/// -/// Since ArangoDB 2.5, this method is an alias for *ensureGeoIndex* since -/// geo indexes are always sparse, meaning that documents that do not contain -/// the index attributes or have non-numeric values in the index attributes -/// will not be indexed. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a geo constraint exists +`collection.ensureIndex({ type: "geo", fields: [ "location" ] })` + +Since ArangoDB 2.5, this method is an alias for *ensureGeoIndex* since +geo indexes are always sparse, meaning that documents that do not contain +the index attributes or have non-numeric values in the index attributes +will not be indexed. + diff --git a/Documentation/DocuBlocks/collectionEnsureGeoIndex.md b/Documentation/DocuBlocks/collectionEnsureGeoIndex.md index 1c8d0edc0c..890d7906b1 100644 --- a/Documentation/DocuBlocks/collectionEnsureGeoIndex.md +++ b/Documentation/DocuBlocks/collectionEnsureGeoIndex.md @@ -1,66 +1,65 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionEnsureGeoIndex -/// @brief ensures that a geo index exists -/// `collection.ensureIndex({ type: "geo", fields: [ "location" ] })` -/// -/// Creates a geo-spatial index on all documents using *location* as path to -/// the coordinates. The value of the attribute has to be an array with at least two -/// numeric values. The array must contain the latitude (first value) and the -/// longitude (second value). -/// -/// All documents, which do not have the attribute path or have a non-conforming -/// value in it are excluded from the index. -/// -/// A geo index is implicitly sparse, and there is no way to control its sparsity. -/// -/// In case that the index was successfully created, an object with the index -/// details, including the index-identifier, is returned. -/// -/// To create a geo on an array attribute that contains longitude first, set the -/// *geoJson* attribute to `true`. This corresponds to the format described in -/// [positions](http://geojson.org/geojson-spec.html) -/// -/// `collection.ensureIndex({ type: "geo", fields: [ "location" ], geoJson: true })` -/// -/// To create a geo-spatial index on all documents using *latitude* and -/// *longitude* as separate attribute paths, two paths need to be specified -/// in the *fields* array: -/// -/// `collection.ensureIndex({ type: "geo", fields: [ "latitude", "longitude" ] })` -/// -/// In case that the index was successfully created, an object with the index -/// details, including the index-identifier, is returned. -/// -/// @EXAMPLES -/// -/// Create a geo index for an array attribute: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{geoIndexCreateForArrayAttribute} -/// ~db._create("geo") -/// db.geo.ensureIndex({ type: "geo", fields: [ "loc" ] }); -/// | for (i = -90; i <= 90; i += 10) { -/// | for (j = -180; j <= 180; j += 10) { -/// | db.geo.save({ name : "Name/" + i + "/" + j, loc: [ i, j ] }); -/// | } -/// } -/// db.geo.count(); -/// db.geo.near(0, 0).limit(3).toArray(); -/// db.geo.near(0, 0).count(); -/// ~db._drop("geo") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Create a geo index for a hash array attribute: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{geoIndexCreateForArrayAttribute2} -/// ~db._create("geo2") -/// db.geo2.ensureIndex({ type: "geo", fields: [ "location.latitude", "location.longitude" ] }); -/// | for (i = -90; i <= 90; i += 10) { -/// | for (j = -180; j <= 180; j += 10) { -/// | db.geo2.save({ name : "Name/" + i + "/" + j, location: { latitude : i, longitude : j } }); -/// | } -/// } -/// db.geo2.near(0, 0).limit(3).toArray(); -/// ~db._drop("geo2") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a geo index exists +`collection.ensureIndex({ type: "geo", fields: [ "location" ] })` + +Creates a geo-spatial index on all documents using *location* as path to +the coordinates. The value of the attribute has to be an array with at least two +numeric values. The array must contain the latitude (first value) and the +longitude (second value). + +All documents, which do not have the attribute path or have a non-conforming +value in it are excluded from the index. + +A geo index is implicitly sparse, and there is no way to control its sparsity. + +In case that the index was successfully created, an object with the index +details, including the index-identifier, is returned. + +To create a geo on an array attribute that contains longitude first, set the +*geoJson* attribute to `true`. This corresponds to the format described in +[positions](http://geojson.org/geojson-spec.html) + +`collection.ensureIndex({ type: "geo", fields: [ "location" ], geoJson: true })` + +To create a geo-spatial index on all documents using *latitude* and +*longitude* as separate attribute paths, two paths need to be specified +in the *fields* array: + +`collection.ensureIndex({ type: "geo", fields: [ "latitude", "longitude" ] })` + +In case that the index was successfully created, an object with the index +details, including the index-identifier, is returned. + +@EXAMPLES + +Create a geo index for an array attribute: + +@EXAMPLE_ARANGOSH_OUTPUT{geoIndexCreateForArrayAttribute} +~db._create("geo") + db.geo.ensureIndex({ type: "geo", fields: [ "loc" ] }); +| for (i = -90; i <= 90; i += 10) { +| for (j = -180; j <= 180; j += 10) { +| db.geo.save({ name : "Name/" + i + "/" + j, loc: [ i, j ] }); +| } + } +db.geo.count(); +db.geo.near(0, 0).limit(3).toArray(); +db.geo.near(0, 0).count(); +~db._drop("geo") +@END_EXAMPLE_ARANGOSH_OUTPUT + +Create a geo index for a hash array attribute: + +@EXAMPLE_ARANGOSH_OUTPUT{geoIndexCreateForArrayAttribute2} +~db._create("geo2") +db.geo2.ensureIndex({ type: "geo", fields: [ "location.latitude", "location.longitude" ] }); +| for (i = -90; i <= 90; i += 10) { +| for (j = -180; j <= 180; j += 10) { +| db.geo2.save({ name : "Name/" + i + "/" + j, location: { latitude : i, longitude : j } }); +| } + } +db.geo2.near(0, 0).limit(3).toArray(); +~db._drop("geo2") +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionEnsureIndex.md b/Documentation/DocuBlocks/collectionEnsureIndex.md index 2bbe45c0bf..4351e3b061 100644 --- a/Documentation/DocuBlocks/collectionEnsureIndex.md +++ b/Documentation/DocuBlocks/collectionEnsureIndex.md @@ -1,41 +1,40 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionEnsureIndex -/// @brief ensures that an index exists -/// `collection.ensureIndex(index-description)` -/// -/// Ensures that an index according to the *index-description* exists. A -/// new index will be created if none exists with the given description. -/// -/// The *index-description* must contain at least a *type* attribute. -/// Other attributes may be necessary, depending on the index type. -/// -/// **type** can be one of the following values: -/// - *hash*: hash index -/// - *skiplist*: skiplist index -/// - *fulltext*: fulltext index -/// - *geo1*: geo index, with one attribute -/// - *geo2*: geo index, with two attributes -/// - *cap*: cap constraint -/// -/// **sparse** can be *true* or *false*. -/// -/// For *hash*, and *skiplist* the sparsity can be controlled, *fulltext* and *geo* -/// are [sparse](WhichIndex.md) by definition. -/// -/// **unique** can be *true* or *false* and is supported by *hash* or *skiplist* -/// -/// Calling this method returns an index object. Whether or not the index -/// object existed before the call is indicated in the return attribute -/// *isNewlyCreated*. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionEnsureIndex} -/// ~db._create("test"); -/// db.test.ensureIndex({ type: "hash", fields: [ "a" ], sparse: true }); -/// db.test.ensureIndex({ type: "hash", fields: [ "a", "b" ], unique: true }); -/// ~db._drop("test"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that an index exists +`collection.ensureIndex(index-description)` + +Ensures that an index according to the *index-description* exists. A +new index will be created if none exists with the given description. + +The *index-description* must contain at least a *type* attribute. +Other attributes may be necessary, depending on the index type. + +**type** can be one of the following values: +- *hash*: hash index +- *skiplist*: skiplist index +- *fulltext*: fulltext index +- *geo1*: geo index, with one attribute +- *geo2*: geo index, with two attributes +- *cap*: cap constraint + +**sparse** can be *true* or *false*. + +For *hash*, and *skiplist* the sparsity can be controlled, *fulltext* and *geo* +are [sparse](WhichIndex.md) by definition. + +**unique** can be *true* or *false* and is supported by *hash* or *skiplist* + +Calling this method returns an index object. Whether or not the index +object existed before the call is indicated in the return attribute +*isNewlyCreated*. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionEnsureIndex} +~db._create("test"); +db.test.ensureIndex({ type: "hash", fields: [ "a" ], sparse: true }); +db.test.ensureIndex({ type: "hash", fields: [ "a", "b" ], unique: true }); +~db._drop("test"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionFigures.md b/Documentation/DocuBlocks/collectionFigures.md index f41cb558ff..77b54aacb4 100644 --- a/Documentation/DocuBlocks/collectionFigures.md +++ b/Documentation/DocuBlocks/collectionFigures.md @@ -1,101 +1,100 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionFigures -/// @brief returns the figures of a collection -/// `collection.figures()` -/// -/// Returns an object containing statistics about the collection. -/// **Note** : Retrieving the figures will always load the collection into -/// memory. -/// -/// * *alive.count*: The number of currently active documents in all datafiles and -/// journals of the collection. Documents that are contained in the -/// write-ahead log only are not reported in this figure. -/// * *alive.size*: The total size in bytes used by all active documents of the -/// collection. Documents that are contained in the write-ahead log only are -/// not reported in this figure. -/// - *dead.count*: The number of dead documents. This includes document -/// versions that have been deleted or replaced by a newer version. Documents -/// deleted or replaced that are contained in the write-ahead log only are not -/// reported in this figure. -/// * *dead.size*: The total size in bytes used by all dead documents. -/// * *dead.deletion*: The total number of deletion markers. Deletion markers -/// only contained in the write-ahead log are not reporting in this figure. -/// * *datafiles.count*: The number of datafiles. -/// * *datafiles.fileSize*: The total filesize of datafiles (in bytes). -/// * *journals.count*: The number of journal files. -/// * *journals.fileSize*: The total filesize of the journal files -/// (in bytes). -/// * *compactors.count*: The number of compactor files. -/// * *compactors.fileSize*: The total filesize of the compactor files -/// (in bytes). -/// * *shapefiles.count*: The number of shape files. This value is -/// deprecated and kept for compatibility reasons only. The value will always -/// be 0 since ArangoDB 2.0 and higher. -/// * *shapefiles.fileSize*: The total filesize of the shape files. This -/// value is deprecated and kept for compatibility reasons only. The value will -/// always be 0 in ArangoDB 2.0 and higher. -/// * *shapes.count*: The total number of shapes used in the collection. -/// This includes shapes that are not in use anymore. Shapes that are contained -/// in the write-ahead log only are not reported in this figure. -/// * *shapes.size*: The total size of all shapes (in bytes). This includes -/// shapes that are not in use anymore. Shapes that are contained in the -/// write-ahead log only are not reported in this figure. -/// * *attributes.count*: The total number of attributes used in the -/// collection. Note: the value includes data of attributes that are not in use -/// anymore. Attributes that are contained in the write-ahead log only are -/// not reported in this figure. -/// * *attributes.size*: The total size of the attribute data (in bytes). -/// Note: the value includes data of attributes that are not in use anymore. -/// Attributes that are contained in the write-ahead log only are not -/// reported in this figure. -/// * *indexes.count*: The total number of indexes defined for the -/// collection, including the pre-defined indexes (e.g. primary index). -/// * *indexes.size*: The total memory allocated for indexes in bytes. -/// * *maxTick*: The tick of the last marker that was stored in a journal -/// of the collection. This might be 0 if the collection does not yet have -/// a journal. -/// * *uncollectedLogfileEntries*: The number of markers in the write-ahead -/// log for this collection that have not been transferred to journals or -/// datafiles. -/// * *documentReferences*: The number of references to documents in datafiles -/// that JavaScript code currently holds. This information can be used for -/// debugging compaction and unload issues. -/// * *waitingFor*: An optional string value that contains information about -/// which object type is at the head of the collection's cleanup queue. This -/// information can be used for debugging compaction and unload issues. -/// * *compactionStatus.time*: The point in time the compaction for the collection -/// was last executed. This information can be used for debugging compaction -/// issues. -/// * *compactionStatus.message*: The action that was performed when the compaction -/// was last run for the collection. This information can be used for debugging -/// compaction issues. -/// -/// **Note**: collection data that are stored in the write-ahead log only are -/// not reported in the results. When the write-ahead log is collected, documents -/// might be added to journals and datafiles of the collection, which may modify -/// the figures of the collection. Also note that `waitingFor` and `compactionStatus` -/// may be empty when called on a coordinator in a cluster. -/// -/// Additionally, the filesizes of collection and index parameter JSON files are -/// not reported. These files should normally have a size of a few bytes -/// each. Please also note that the *fileSize* values are reported in bytes -/// and reflect the logical file sizes. Some filesystems may use optimisations -/// (e.g. sparse files) so that the actual physical file size is somewhat -/// different. Directories and sub-directories may also require space in the -/// file system, but this space is not reported in the *fileSize* results. -/// -/// That means that the figures reported do not reflect the actual disk -/// usage of the collection with 100% accuracy. The actual disk usage of -/// a collection is normally slightly higher than the sum of the reported -/// *fileSize* values. Still the sum of the *fileSize* values can still be -/// used as a lower bound approximation of the disk usage. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionFigures} -/// ~ require("internal").wal.flush(true, true); -/// db.demo.figures() -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the figures of a collection +`collection.figures()` + +Returns an object containing statistics about the collection. +**Note** : Retrieving the figures will always load the collection into +memory. + +* *alive.count*: The number of currently active documents in all datafiles and + journals of the collection. Documents that are contained in the + write-ahead log only are not reported in this figure. +* *alive.size*: The total size in bytes used by all active documents of the + collection. Documents that are contained in the write-ahead log only are + not reported in this figure. +- *dead.count*: The number of dead documents. This includes document + versions that have been deleted or replaced by a newer version. Documents + deleted or replaced that are contained in the write-ahead log only are not + reported in this figure. +* *dead.size*: The total size in bytes used by all dead documents. +* *dead.deletion*: The total number of deletion markers. Deletion markers + only contained in the write-ahead log are not reporting in this figure. +* *datafiles.count*: The number of datafiles. +* *datafiles.fileSize*: The total filesize of datafiles (in bytes). +* *journals.count*: The number of journal files. +* *journals.fileSize*: The total filesize of the journal files + (in bytes). +* *compactors.count*: The number of compactor files. +* *compactors.fileSize*: The total filesize of the compactor files + (in bytes). +* *shapefiles.count*: The number of shape files. This value is + deprecated and kept for compatibility reasons only. The value will always + be 0 since ArangoDB 2.0 and higher. +* *shapefiles.fileSize*: The total filesize of the shape files. This + value is deprecated and kept for compatibility reasons only. The value will + always be 0 in ArangoDB 2.0 and higher. +* *shapes.count*: The total number of shapes used in the collection. + This includes shapes that are not in use anymore. Shapes that are contained + in the write-ahead log only are not reported in this figure. +* *shapes.size*: The total size of all shapes (in bytes). This includes + shapes that are not in use anymore. Shapes that are contained in the + write-ahead log only are not reported in this figure. +* *attributes.count*: The total number of attributes used in the + collection. Note: the value includes data of attributes that are not in use + anymore. Attributes that are contained in the write-ahead log only are + not reported in this figure. +* *attributes.size*: The total size of the attribute data (in bytes). + Note: the value includes data of attributes that are not in use anymore. + Attributes that are contained in the write-ahead log only are not + reported in this figure. +* *indexes.count*: The total number of indexes defined for the + collection, including the pre-defined indexes (e.g. primary index). +* *indexes.size*: The total memory allocated for indexes in bytes. +* *maxTick*: The tick of the last marker that was stored in a journal + of the collection. This might be 0 if the collection does not yet have + a journal. +* *uncollectedLogfileEntries*: The number of markers in the write-ahead + log for this collection that have not been transferred to journals or + datafiles. +* *documentReferences*: The number of references to documents in datafiles + that JavaScript code currently holds. This information can be used for + debugging compaction and unload issues. +* *waitingFor*: An optional string value that contains information about + which object type is at the head of the collection's cleanup queue. This + information can be used for debugging compaction and unload issues. +* *compactionStatus.time*: The point in time the compaction for the collection + was last executed. This information can be used for debugging compaction + issues. +* *compactionStatus.message*: The action that was performed when the compaction + was last run for the collection. This information can be used for debugging + compaction issues. + +**Note**: collection data that are stored in the write-ahead log only are +not reported in the results. When the write-ahead log is collected, documents +might be added to journals and datafiles of the collection, which may modify +the figures of the collection. Also note that `waitingFor` and `compactionStatus` +may be empty when called on a coordinator in a cluster. + +Additionally, the filesizes of collection and index parameter JSON files are +not reported. These files should normally have a size of a few bytes +each. Please also note that the *fileSize* values are reported in bytes +and reflect the logical file sizes. Some filesystems may use optimisations +(e.g. sparse files) so that the actual physical file size is somewhat +different. Directories and sub-directories may also require space in the +file system, but this space is not reported in the *fileSize* results. + +That means that the figures reported do not reflect the actual disk +usage of the collection with 100% accuracy. The actual disk usage of +a collection is normally slightly higher than the sum of the reported +*fileSize* values. Still the sum of the *fileSize* values can still be +used as a lower bound approximation of the disk usage. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionFigures} +~ require("internal").wal.flush(true, true); + db.demo.figures() +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionFirstExample.md b/Documentation/DocuBlocks/collectionFirstExample.md index 7ea9151ec6..60b97b346c 100644 --- a/Documentation/DocuBlocks/collectionFirstExample.md +++ b/Documentation/DocuBlocks/collectionFirstExample.md @@ -1,27 +1,26 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionFirstExample -/// @brief constructs a query-by-example for a collection -/// `collection.firstExample(example)` -/// -/// Returns the first document of a collection that matches the specified -/// example. If no such document exists, *null* will be returned. -/// The example has to be specified as paths and values. -/// See *byExample* for details. -/// -/// `collection.firstExample(path1, value1, ...)` -/// -/// As alternative you can supply an array of paths and values. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionFirstExample} -/// ~ db._create("users"); -/// ~ db.users.save({ name: "Gerhard" }); -/// ~ db.users.save({ name: "Helmut" }); -/// ~ db.users.save({ name: "Angela" }); -/// db.users.firstExample("name", "Angela"); -/// ~ db._drop("users"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief constructs a query-by-example for a collection +`collection.firstExample(example)` + +Returns the first document of a collection that matches the specified +example. If no such document exists, *null* will be returned. +The example has to be specified as paths and values. +See *byExample* for details. + +`collection.firstExample(path1, value1, ...)` + +As alternative you can supply an array of paths and values. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionFirstExample} +~ db._create("users"); +~ db.users.save({ name: "Gerhard" }); +~ db.users.save({ name: "Helmut" }); +~ db.users.save({ name: "Angela" }); + db.users.firstExample("name", "Angela"); +~ db._drop("users"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionFulltext.md b/Documentation/DocuBlocks/collectionFulltext.md index 6b194b1a4d..d2a801050c 100644 --- a/Documentation/DocuBlocks/collectionFulltext.md +++ b/Documentation/DocuBlocks/collectionFulltext.md @@ -1,34 +1,33 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionFulltext -/// @brief queries the fulltext index -/// `collection.fulltext(attribute, query)` -/// -/// The *fulltext* simple query functions performs a fulltext search on the specified -/// *attribute* and the specified *query*. -/// -/// Details about the fulltext query syntax can be found below. -/// -/// Note: the *fulltext* simple query function is **deprecated** as of ArangoDB 2.6. -/// The function may be removed in future versions of ArangoDB. The preferred -/// way for executing fulltext queries is to use an AQL query using the *FULLTEXT* -/// [AQL function](../Aql/FulltextFunctions.md) as follows: -/// -/// FOR doc IN FULLTEXT(@@collection, @attributeName, @queryString, @limit) -/// RETURN doc -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionFulltext} -/// ~ db._drop("emails"); -/// ~ db._create("emails"); -/// db.emails.ensureFulltextIndex("content"); -/// | db.emails.save({ content: -/// "Hello Alice, how are you doing? Regards, Bob"}); -/// | db.emails.save({ content: -/// "Hello Charlie, do Alice and Bob know about it?"}); -/// db.emails.save({ content: "I think they don't know. Regards, Eve" }); -/// db.emails.fulltext("content", "charlie,|eve").toArray(); -/// ~ db._drop("emails"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief queries the fulltext index +`collection.fulltext(attribute, query)` + +The *fulltext* simple query functions performs a fulltext search on the specified +*attribute* and the specified *query*. + +Details about the fulltext query syntax can be found below. + +Note: the *fulltext* simple query function is **deprecated** as of ArangoDB 2.6. +The function may be removed in future versions of ArangoDB. The preferred +way for executing fulltext queries is to use an AQL query using the *FULLTEXT* +[AQL function](../Aql/FulltextFunctions.md) as follows: + + FOR doc IN FULLTEXT(@@collection, @attributeName, @queryString, @limit) + RETURN doc + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionFulltext} +~ db._drop("emails"); +~ db._create("emails"); + db.emails.ensureFulltextIndex("content"); +| db.emails.save({ content: + "Hello Alice, how are you doing? Regards, Bob"}); +| db.emails.save({ content: + "Hello Charlie, do Alice and Bob know about it?"}); + db.emails.save({ content: "I think they don't know. Regards, Eve" }); + db.emails.fulltext("content", "charlie,|eve").toArray(); +~ db._drop("emails"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionGetIndexes.md b/Documentation/DocuBlocks/collectionGetIndexes.md index 555a14466b..1aa4b2aea7 100644 --- a/Documentation/DocuBlocks/collectionGetIndexes.md +++ b/Documentation/DocuBlocks/collectionGetIndexes.md @@ -1,20 +1,19 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionGetIndexes -/// @brief returns information about the indexes -/// `getIndexes()` -/// -/// Returns an array of all indexes defined for the collection. -/// -/// Note that `_key` implicitly has an index assigned to it. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionGetIndexes} -/// ~db._create("test"); -/// ~db.test.ensureUniqueSkiplist("skiplistAttribute"); -/// ~db.test.ensureUniqueSkiplist("skiplistUniqueAttribute"); -/// |~db.test.ensureHashIndex("hashListAttribute", -/// "hashListSecondAttribute.subAttribute"); -/// db.test.getIndexes(); -/// ~db._drop("test"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns information about the indexes +`getIndexes()` + +Returns an array of all indexes defined for the collection. + +Note that `_key` implicitly has an index assigned to it. + +@EXAMPLE_ARANGOSH_OUTPUT{collectionGetIndexes} +~db._create("test"); +~db.test.ensureUniqueSkiplist("skiplistAttribute"); +~db.test.ensureUniqueSkiplist("skiplistUniqueAttribute"); +|~db.test.ensureHashIndex("hashListAttribute", + "hashListSecondAttribute.subAttribute"); +db.test.getIndexes(); +~db._drop("test"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionIterate.md b/Documentation/DocuBlocks/collectionIterate.md index da39d3810f..835b7d31cb 100644 --- a/Documentation/DocuBlocks/collectionIterate.md +++ b/Documentation/DocuBlocks/collectionIterate.md @@ -1,37 +1,36 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionIterate -/// @brief iterates over some elements of a collection -/// `collection.iterate(iterator, options)` -/// -/// Iterates over some elements of the collection and apply the function -/// *iterator* to the elements. The function will be called with the -/// document as first argument and the current number (starting with 0) -/// as second argument. -/// -/// *options* must be an object with the following attributes: -/// -/// - *limit* (optional, default none): use at most *limit* documents. -/// -/// - *probability* (optional, default all): a number between *0* and -/// *1*. Documents are chosen with this probability. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{accessViaGeoIndex} -/// ~db._create("example") -/// |for (i = -90; i <= 90; i += 10) { -/// | for (j = -180; j <= 180; j += 10) { -/// | db.example.save({ name : "Name/" + i + "/" + j, -/// | home : [ i, j ], -/// | work : [ -i, -j ] }); -/// | } -/// |} -/// -/// db.example.ensureIndex({ type: "geo", fields: [ "home" ] }); -/// |items = db.example.getIndexes().map(function(x) { return x.id; }); -/// db.example.index(items[1]); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief iterates over some elements of a collection +`collection.iterate(iterator, options)` + +Iterates over some elements of the collection and apply the function +*iterator* to the elements. The function will be called with the +document as first argument and the current number (starting with 0) +as second argument. + +*options* must be an object with the following attributes: + +- *limit* (optional, default none): use at most *limit* documents. + +- *probability* (optional, default all): a number between *0* and + *1*. Documents are chosen with this probability. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{accessViaGeoIndex} +~db._create("example") +|for (i = -90; i <= 90; i += 10) { +| for (j = -180; j <= 180; j += 10) { +| db.example.save({ name : "Name/" + i + "/" + j, +| home : [ i, j ], +| work : [ -i, -j ] }); +| } +|} + + db.example.ensureIndex({ type: "geo", fields: [ "home" ] }); + |items = db.example.getIndexes().map(function(x) { return x.id; }); + db.example.index(items[1]); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionLoad.md b/Documentation/DocuBlocks/collectionLoad.md index ef2a553188..e8d0ab69f9 100644 --- a/Documentation/DocuBlocks/collectionLoad.md +++ b/Documentation/DocuBlocks/collectionLoad.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionLoad -/// @brief loads a collection -/// `collection.load()` -/// -/// Loads a collection into memory. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionLoad} -/// ~ db._create("example"); -/// col = db.example; -/// col.load(); -/// col; -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief loads a collection +`collection.load()` + +Loads a collection into memory. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionLoad} +~ db._create("example"); + col = db.example; + col.load(); + col; +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionLookupByKeys.md b/Documentation/DocuBlocks/collectionLookupByKeys.md index dc1df82b26..144146c646 100644 --- a/Documentation/DocuBlocks/collectionLookupByKeys.md +++ b/Documentation/DocuBlocks/collectionLookupByKeys.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionLookupByKeys -/// @brief fetches multiple documents by their keys -/// `collection.documents(keys)` -/// -/// Looks up the documents in the specified collection using the array of keys -/// provided. All documents for which a matching key was specified in the *keys* -/// array and that exist in the collection will be returned. -/// Keys for which no document can be found in the underlying collection are ignored, -/// and no exception will be thrown for them. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionLookupByKeys} -/// ~ db._drop("example"); -/// ~ db._create("example"); -/// keys = [ ]; -/// | for (var i = 0; i < 10; ++i) { -/// | db.example.insert({ _key: "test" + i, value: i }); -/// | keys.push("test" + i); -/// } -/// db.example.documents(keys); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief fetches multiple documents by their keys +`collection.documents(keys)` + +Looks up the documents in the specified collection using the array of keys +provided. All documents for which a matching key was specified in the *keys* +array and that exist in the collection will be returned. +Keys for which no document can be found in the underlying collection are ignored, +and no exception will be thrown for them. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionLookupByKeys} +~ db._drop("example"); +~ db._create("example"); + keys = [ ]; +| for (var i = 0; i < 10; ++i) { +| db.example.insert({ _key: "test" + i, value: i }); +| keys.push("test" + i); + } + db.example.documents(keys); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionRange.md b/Documentation/DocuBlocks/collectionRange.md index 80f7344a35..1699e858ac 100644 --- a/Documentation/DocuBlocks/collectionRange.md +++ b/Documentation/DocuBlocks/collectionRange.md @@ -1,45 +1,44 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionRange -/// @brief constructs a range query for a collection -/// `collection.range(attribute, left, right)` -/// -/// Returns all documents from a collection such that the *attribute* is -/// greater or equal than *left* and strictly less than *right*. -/// -/// You can use *toArray*, *next*, or *hasNext* to access the -/// result. The result can be limited using the *skip* and *limit* -/// operator. -/// -/// An attribute name of the form *a.b* is interpreted as attribute path, -/// not as attribute. -/// -/// For range queries it is required that a skiplist index is present for the -/// queried attribute. If no skiplist index is present on the attribute, an -/// error will be thrown. -/// -/// Note: the *range* simple query function is **deprecated** as of ArangoDB 2.6. -/// The function may be removed in future versions of ArangoDB. The preferred -/// way for retrieving documents from a collection within a specific range -/// is to use an AQL query as follows: -/// -/// FOR doc IN @@collection -/// FILTER doc.value >= @left && doc.value < @right -/// LIMIT @skip, @limit -/// RETURN doc -/// -/// @EXAMPLES -/// -/// Use *toArray* to get all documents at once: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{005_collectionRange} -/// ~ db._create("old"); -/// db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] }); -/// db.old.save({ age: 15 }); -/// db.old.save({ age: 25 }); -/// db.old.save({ age: 30 }); -/// db.old.range("age", 10, 30).toArray(); -/// ~ db._drop("old") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief constructs a range query for a collection +`collection.range(attribute, left, right)` + +Returns all documents from a collection such that the *attribute* is +greater or equal than *left* and strictly less than *right*. + +You can use *toArray*, *next*, or *hasNext* to access the +result. The result can be limited using the *skip* and *limit* +operator. + +An attribute name of the form *a.b* is interpreted as attribute path, +not as attribute. + +For range queries it is required that a skiplist index is present for the +queried attribute. If no skiplist index is present on the attribute, an +error will be thrown. + +Note: the *range* simple query function is **deprecated** as of ArangoDB 2.6. +The function may be removed in future versions of ArangoDB. The preferred +way for retrieving documents from a collection within a specific range +is to use an AQL query as follows: + + FOR doc IN @@collection + FILTER doc.value >= @left && doc.value < @right + LIMIT @skip, @limit + RETURN doc + +@EXAMPLES + +Use *toArray* to get all documents at once: + +@EXAMPLE_ARANGOSH_OUTPUT{005_collectionRange} +~ db._create("old"); + db.old.ensureIndex({ type: "skiplist", fields: [ "age" ] }); + db.old.save({ age: 15 }); + db.old.save({ age: 25 }); + db.old.save({ age: 30 }); + db.old.range("age", 10, 30).toArray(); +~ db._drop("old") +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionRemoveByKeys.md b/Documentation/DocuBlocks/collectionRemoveByKeys.md index da605ededa..ad3ccf6709 100644 --- a/Documentation/DocuBlocks/collectionRemoveByKeys.md +++ b/Documentation/DocuBlocks/collectionRemoveByKeys.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionRemoveByKeys -/// @brief removes multiple documents by their keys -/// `collection.removeByKeys(keys)` -/// -/// Looks up the documents in the specified collection using the array of keys -/// provided, and removes all documents from the collection whose keys are -/// contained in the *keys* array. Keys for which no document can be found in -/// the underlying collection are ignored, and no exception will be thrown for -/// them. -/// -/// The method will return an object containing the number of removed documents -/// in the *removed* sub-attribute, and the number of not-removed/ignored -/// documents in the *ignored* sub-attribute. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionRemoveByKeys} -/// ~ db._drop("example"); -/// ~ db._create("example"); -/// keys = [ ]; -/// | for (var i = 0; i < 10; ++i) { -/// | db.example.insert({ _key: "test" + i, value: i }); -/// | keys.push("test" + i); -/// } -/// db.example.removeByKeys(keys); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief removes multiple documents by their keys +`collection.removeByKeys(keys)` + +Looks up the documents in the specified collection using the array of keys +provided, and removes all documents from the collection whose keys are +contained in the *keys* array. Keys for which no document can be found in +the underlying collection are ignored, and no exception will be thrown for +them. + +The method will return an object containing the number of removed documents +in the *removed* sub-attribute, and the number of not-removed/ignored +documents in the *ignored* sub-attribute. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionRemoveByKeys} +~ db._drop("example"); +~ db._create("example"); + keys = [ ]; +| for (var i = 0; i < 10; ++i) { +| db.example.insert({ _key: "test" + i, value: i }); +| keys.push("test" + i); + } + db.example.removeByKeys(keys); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionRename.md b/Documentation/DocuBlocks/collectionRename.md index e1832207be..aab87ad181 100644 --- a/Documentation/DocuBlocks/collectionRename.md +++ b/Documentation/DocuBlocks/collectionRename.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionRename -/// @brief renames a collection -/// `collection.rename(new-name)` -/// -/// Renames a collection using the *new-name*. The *new-name* must not -/// already be used for a different collection. *new-name* must also be a -/// valid collection name. For more information on valid collection names please -/// refer -/// to the [naming conventions](../NamingConventions/README.md). -/// -/// If renaming fails for any reason, an error is thrown. -/// If renaming the collection succeeds, then the collection is also renamed in -/// all graph definitions inside the `_graphs` collection in the current -/// database. -/// -/// **Note**: this method is not available in a cluster. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionRename} -/// ~ db._create("example"); -/// c = db.example; -/// c.rename("better-example"); -/// c; -/// ~ db._drop("better-example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief renames a collection +`collection.rename(new-name)` + +Renames a collection using the *new-name*. The *new-name* must not +already be used for a different collection. *new-name* must also be a +valid collection name. For more information on valid collection names please +refer +to the [naming conventions](../NamingConventions/README.md). + +If renaming fails for any reason, an error is thrown. +If renaming the collection succeeds, then the collection is also renamed in +all graph definitions inside the `_graphs` collection in the current +database. + +**Note**: this method is not available in a cluster. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{collectionRename} +~ db._create("example"); + c = db.example; + c.rename("better-example"); + c; +~ db._drop("better-example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/collectionRevision.md b/Documentation/DocuBlocks/collectionRevision.md index b8870e67dc..0c06e88586 100644 --- a/Documentation/DocuBlocks/collectionRevision.md +++ b/Documentation/DocuBlocks/collectionRevision.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionRevision -/// @brief returns the revision id of a collection -/// `collection.revision()` -/// -/// Returns the revision id of the collection -/// -/// The revision id is updated when the document data is modified, either by -/// inserting, deleting, updating or replacing documents in it. -/// -/// The revision id of a collection can be used by clients to check whether -/// data in a collection has changed or if it is still unmodified since a -/// previous fetch of the revision id. -/// -/// The revision id returned is a string value. Clients should treat this value -/// as an opaque string, and only use it for equality/non-equality comparisons. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the revision id of a collection +`collection.revision()` + +Returns the revision id of the collection + +The revision id is updated when the document data is modified, either by +inserting, deleting, updating or replacing documents in it. + +The revision id of a collection can be used by clients to check whether +data in a collection has changed or if it is still unmodified since a +previous fetch of the revision id. + +The revision id returned is a string value. Clients should treat this value +as an opaque string, and only use it for equality/non-equality comparisons. + diff --git a/Documentation/DocuBlocks/collectionRotate.md b/Documentation/DocuBlocks/collectionRotate.md index 7a8b2da727..2f34135091 100644 --- a/Documentation/DocuBlocks/collectionRotate.md +++ b/Documentation/DocuBlocks/collectionRotate.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionRotate -/// @brief rotates the current journal of a collection -/// `collection.rotate()` -/// -/// Rotates the current journal of a collection. This operation makes the -/// current journal of the collection a read-only datafile so it may become a -/// candidate for garbage collection. If there is currently no journal available -/// for the collection, the operation will fail with an error. -/// -/// **Note**: this method is not available in a cluster. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief rotates the current journal of a collection +`collection.rotate()` + +Rotates the current journal of a collection. This operation makes the +current journal of the collection a read-only datafile so it may become a +candidate for garbage collection. If there is currently no journal available +for the collection, the operation will fail with an error. + +**Note**: this method is not available in a cluster. + + diff --git a/Documentation/DocuBlocks/collectionToArray.md b/Documentation/DocuBlocks/collectionToArray.md index dac4acb860..c9c623cea1 100644 --- a/Documentation/DocuBlocks/collectionToArray.md +++ b/Documentation/DocuBlocks/collectionToArray.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionToArray -/// @brief converts collection into an array -/// `collection.toArray()` -/// -/// Converts the collection into an array of documents. Never use this call -/// in a production environment. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief converts collection into an array +`collection.toArray()` + +Converts the collection into an array of documents. Never use this call +in a production environment. + diff --git a/Documentation/DocuBlocks/collectionTruncate.md b/Documentation/DocuBlocks/collectionTruncate.md index 0a21940ae3..ca973992fc 100644 --- a/Documentation/DocuBlocks/collectionTruncate.md +++ b/Documentation/DocuBlocks/collectionTruncate.md @@ -1,23 +1,22 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionTruncate -/// @brief truncates a collection -/// `collection.truncate()` -/// -/// Truncates a *collection*, removing all documents but keeping all its -/// indexes. -/// -/// @EXAMPLES -/// -/// Truncates a collection: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{collectionTruncate} -/// ~ db._create("example"); -/// col = db.example; -/// col.save({ "Hello" : "World" }); -/// col.count(); -/// col.truncate(); -/// col.count(); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief truncates a collection +`collection.truncate()` + +Truncates a *collection*, removing all documents but keeping all its +indexes. + +@EXAMPLES + +Truncates a collection: + +@EXAMPLE_ARANGOSH_OUTPUT{collectionTruncate} +~ db._create("example"); + col = db.example; + col.save({ "Hello" : "World" }); + col.count(); + col.truncate(); + col.count(); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/collectionType.md b/Documentation/DocuBlocks/collectionType.md index 1689b7fab5..1538b6ca72 100644 --- a/Documentation/DocuBlocks/collectionType.md +++ b/Documentation/DocuBlocks/collectionType.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionType -/// @brief returns the type of a collection -/// `collection.type()` -/// -/// Returns the type of a collection. Possible values are: -/// - 2: document collection -/// - 3: edge collection -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the type of a collection +`collection.type()` + +Returns the type of a collection. Possible values are: +- 2: document collection +- 3: edge collection + diff --git a/Documentation/DocuBlocks/collectionUnload.md b/Documentation/DocuBlocks/collectionUnload.md index a7a66bb6bb..17c9fb0722 100644 --- a/Documentation/DocuBlocks/collectionUnload.md +++ b/Documentation/DocuBlocks/collectionUnload.md @@ -1,20 +1,19 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock collectionUnload -/// @brief unloads a collection -/// `collection.unload()` -/// -/// Starts unloading a collection from memory. Note that unloading is deferred -/// until all query have finished. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{CollectionUnload} -/// ~ db._create("example"); -/// col = db.example; -/// col.unload(); -/// col; -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief unloads a collection +`collection.unload()` + +Starts unloading a collection from memory. Note that unloading is deferred +until all query have finished. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{CollectionUnload} +~ db._create("example"); + col = db.example; + col.unload(); + col; +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/configurationFilename.md b/Documentation/DocuBlocks/configurationFilename.md index e466147814..ad2ea29eb8 100644 --- a/Documentation/DocuBlocks/configurationFilename.md +++ b/Documentation/DocuBlocks/configurationFilename.md @@ -1,78 +1,77 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock configurationFilename -/// @brief config file -/// `--configuration filename` -/// -/// `-c filename` -/// -/// Specifies the name of the configuration file to use. -/// -/// If this command is not passed to the server, then by default, the server -/// will attempt to first locate a file named *~/.arango/arangod.conf* in the -/// user's home directory. -/// -/// If no such file is found, the server will proceed to look for a file -/// *arangod.conf* in the system configuration directory. The system -/// configuration directory is platform-specific, and may be changed when -/// compiling ArangoDB yourself. It may default to */etc/arangodb* or -/// */usr/local/etc/arangodb*. This file is installed when using a package -/// manager like rpm or dpkg. If you modify this file and later upgrade to a -/// new -/// version of ArangoDB, then the package manager normally warns you about the -/// conflict. In order to avoid these warning for small adjustments, you can -/// put -/// local overrides into a file *arangod.conf.local*. -/// -/// Only command line options with a value should be set within the -/// configuration file. Command line options which act as flags should be -/// entered on the command line when starting the server. -/// -/// Whitespace in the configuration file is ignored. Each option is specified -/// on -/// a separate line in the form -/// -/// ```js -/// key = value -/// ``` -/// -/// Alternatively, a header section can be specified and options pertaining to -/// that section can be specified in a shorter form -/// -/// ```js -/// [log] -/// level = trace -/// ``` -/// -/// rather than specifying -/// -/// ```js -/// log.level = trace -/// ``` -/// -/// Comments can be placed in the configuration file, only if the line begins -/// with one or more hash symbols (#). -/// -/// There may be occasions where a configuration file exists and the user -/// wishes -/// to override configuration settings stored in a configuration file. Any -/// settings specified on the command line will overwrite the same setting -/// when -/// it appears in a configuration file. If the user wishes to completely -/// ignore -/// configuration files without necessarily deleting the file (or files), then -/// add the command line option -/// -/// ```js -/// -c none -/// ``` -/// -/// or -/// -/// ```js -/// --configuration none -/// ``` -/// -/// When starting up the server. Note that, the word *none* is -/// case-insensitive. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief config file +`--configuration filename` + +`-c filename` + +Specifies the name of the configuration file to use. + +If this command is not passed to the server, then by default, the server +will attempt to first locate a file named *~/.arango/arangod.conf* in the +user's home directory. + +If no such file is found, the server will proceed to look for a file +*arangod.conf* in the system configuration directory. The system +configuration directory is platform-specific, and may be changed when +compiling ArangoDB yourself. It may default to */etc/arangodb* or +*/usr/local/etc/arangodb*. This file is installed when using a package +manager like rpm or dpkg. If you modify this file and later upgrade to a +new +version of ArangoDB, then the package manager normally warns you about the +conflict. In order to avoid these warning for small adjustments, you can +put +local overrides into a file *arangod.conf.local*. + +Only command line options with a value should be set within the +configuration file. Command line options which act as flags should be +entered on the command line when starting the server. + +Whitespace in the configuration file is ignored. Each option is specified +on +a separate line in the form + +```js +key = value +``` + +Alternatively, a header section can be specified and options pertaining to +that section can be specified in a shorter form + +```js +[log] +level = trace +``` + +rather than specifying + +```js +log.level = trace +``` + +Comments can be placed in the configuration file, only if the line begins +with one or more hash symbols (#). + +There may be occasions where a configuration file exists and the user +wishes +to override configuration settings stored in a configuration file. Any +settings specified on the command line will overwrite the same setting +when +it appears in a configuration file. If the user wishes to completely +ignore +configuration files without necessarily deleting the file (or files), then +add the command line option + +```js +-c none +``` + +or + +```js +--configuration none +``` + +When starting up the server. Note that, the word *none* is +case-insensitive. + diff --git a/Documentation/DocuBlocks/configurationGid.md b/Documentation/DocuBlocks/configurationGid.md index 492c3218d5..8040471d33 100644 --- a/Documentation/DocuBlocks/configurationGid.md +++ b/Documentation/DocuBlocks/configurationGid.md @@ -1,16 +1,15 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock configurationGid -/// @brief the group id to use for the process -/// `--gid gid` -/// -/// The name (identity) of the group the server will run as. If this parameter -/// is not specified, then the server will not attempt to change its GID, so -/// that the GID the server runs as will be the primary group of the user who -/// started the server. If this parameter is specified, then the server will -/// change its GID after opening ports and reading configuration files, but -/// before accepting connections or opening other files (such as recovery -/// files). -/// -/// This parameter is related to the parameter uid. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief the group id to use for the process +`--gid gid` + +The name (identity) of the group the server will run as. If this parameter +is not specified, then the server will not attempt to change its GID, so +that the GID the server runs as will be the primary group of the user who +started the server. If this parameter is specified, then the server will +change its GID after opening ports and reading configuration files, but +before accepting connections or opening other files (such as recovery +files). + +This parameter is related to the parameter uid. + diff --git a/Documentation/DocuBlocks/configurationUid.md b/Documentation/DocuBlocks/configurationUid.md index e22197bfdb..5deec3ef6c 100644 --- a/Documentation/DocuBlocks/configurationUid.md +++ b/Documentation/DocuBlocks/configurationUid.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock configurationUid -/// @brief the user id to use for the process -/// `--uid uid` -/// -/// The name (identity) of the user the server will run as. If this parameter -/// is -/// not specified, the server will not attempt to change its UID, so that the -/// UID used by the server will be the same as the UID of the user who started -/// the server. If this parameter is specified, then the server will change -/// its -/// UID after opening ports and reading configuration files, but before -/// accepting connections or opening other files (such as recovery files). -/// This -/// is useful when the server must be started with raised privileges (in -/// certain -/// environments) but security considerations require that these privileges be -/// dropped once the server has started work. -/// -/// Observe that this parameter cannot be used to bypass operating system -/// security. In general, this parameter (and its corresponding relative gid) -/// can lower privileges but not raise them. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief the user id to use for the process +`--uid uid` + +The name (identity) of the user the server will run as. If this parameter +is +not specified, the server will not attempt to change its UID, so that the +UID used by the server will be the same as the UID of the user who started +the server. If this parameter is specified, then the server will change +its +UID after opening ports and reading configuration files, but before +accepting connections or opening other files (such as recovery files). +This +is useful when the server must be started with raised privileges (in +certain +environments) but security considerations require that these privileges be +dropped once the server has started work. + +Observe that this parameter cannot be used to bypass operating system +security. In general, this parameter (and its corresponding relative gid) +can lower privileges but not raise them. + diff --git a/Documentation/DocuBlocks/cursorCount.md b/Documentation/DocuBlocks/cursorCount.md index a7bf6cb46b..e995eaa3ef 100644 --- a/Documentation/DocuBlocks/cursorCount.md +++ b/Documentation/DocuBlocks/cursorCount.md @@ -1,52 +1,51 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock cursorCount -/// @brief counts the number of documents -/// `cursor.count()` -/// -/// The *count* operator counts the number of document in the result set and -/// returns that number. The *count* operator ignores any limits and returns -/// the total number of documents found. -/// -/// **Note**: Not all simple queries support counting. In this case *null* is -/// returned. -/// -/// `cursor.count(true)` -/// -/// If the result set was limited by the *limit* operator or documents were -/// skiped using the *skip* operator, the *count* operator with argument -/// *true* will use the number of elements in the final result set - after -/// applying *limit* and *skip*. -/// -/// **Note**: Not all simple queries support counting. In this case *null* is -/// returned. -/// -/// @EXAMPLES -/// -/// Ignore any limit: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{cursorCount} -/// ~ db._create("five"); -/// ~ db.five.save({ name : "one" }); -/// ~ db.five.save({ name : "two" }); -/// ~ db.five.save({ name : "three" }); -/// ~ db.five.save({ name : "four" }); -/// ~ db.five.save({ name : "five" }); -/// db.five.all().limit(2).count(); -/// ~ db._drop("five") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Counting any limit or skip: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{cursorCountLimit} -/// ~ db._create("five"); -/// ~ db.five.save({ name : "one" }); -/// ~ db.five.save({ name : "two" }); -/// ~ db.five.save({ name : "three" }); -/// ~ db.five.save({ name : "four" }); -/// ~ db.five.save({ name : "five" }); -/// db.five.all().limit(2).count(true); -/// ~ db._drop("five") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief counts the number of documents +`cursor.count()` + +The *count* operator counts the number of document in the result set and +returns that number. The *count* operator ignores any limits and returns +the total number of documents found. + +**Note**: Not all simple queries support counting. In this case *null* is +returned. + +`cursor.count(true)` + +If the result set was limited by the *limit* operator or documents were +skiped using the *skip* operator, the *count* operator with argument +*true* will use the number of elements in the final result set - after +applying *limit* and *skip*. + +**Note**: Not all simple queries support counting. In this case *null* is +returned. + +@EXAMPLES + +Ignore any limit: + +@EXAMPLE_ARANGOSH_OUTPUT{cursorCount} +~ db._create("five"); +~ db.five.save({ name : "one" }); +~ db.five.save({ name : "two" }); +~ db.five.save({ name : "three" }); +~ db.five.save({ name : "four" }); +~ db.five.save({ name : "five" }); + db.five.all().limit(2).count(); +~ db._drop("five") +@END_EXAMPLE_ARANGOSH_OUTPUT + +Counting any limit or skip: + +@EXAMPLE_ARANGOSH_OUTPUT{cursorCountLimit} +~ db._create("five"); +~ db.five.save({ name : "one" }); +~ db.five.save({ name : "two" }); +~ db.five.save({ name : "three" }); +~ db.five.save({ name : "four" }); +~ db.five.save({ name : "five" }); + db.five.all().limit(2).count(true); +~ db._drop("five") +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/cursorDispose.md b/Documentation/DocuBlocks/cursorDispose.md index 5e4f11c663..4c027c0756 100644 --- a/Documentation/DocuBlocks/cursorDispose.md +++ b/Documentation/DocuBlocks/cursorDispose.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock cursorDispose -/// @brief disposes the result -/// `cursor.dispose()` -/// -/// If you are no longer interested in any further results, you should call -/// *dispose* in order to free any resources associated with the cursor. -/// After calling *dispose* you can no longer access the cursor. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief disposes the result +`cursor.dispose()` + +If you are no longer interested in any further results, you should call +*dispose* in order to free any resources associated with the cursor. +After calling *dispose* you can no longer access the cursor. + diff --git a/Documentation/DocuBlocks/cursorGetBatchSize.md b/Documentation/DocuBlocks/cursorGetBatchSize.md index 4bb3282f24..97df3888df 100644 --- a/Documentation/DocuBlocks/cursorGetBatchSize.md +++ b/Documentation/DocuBlocks/cursorGetBatchSize.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock cursorGetBatchSize -/// @brief returns the batch size -/// `cursor.getBatchSize()` -/// -/// Returns the batch size for queries. If the returned value is undefined, the -/// server will determine a sensible batch size for any following requests. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the batch size +`cursor.getBatchSize()` + +Returns the batch size for queries. If the returned value is undefined, the +server will determine a sensible batch size for any following requests. + diff --git a/Documentation/DocuBlocks/cursorHasNext.md b/Documentation/DocuBlocks/cursorHasNext.md index 09385c598e..8d88249966 100644 --- a/Documentation/DocuBlocks/cursorHasNext.md +++ b/Documentation/DocuBlocks/cursorHasNext.md @@ -1,24 +1,23 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock cursorHasNext -/// @brief checks if the cursor is exhausted -/// `cursor.hasNext()` -/// -/// The *hasNext* operator returns *true*, then the cursor still has -/// documents. In this case the next document can be accessed using the -/// *next* operator, which will advance the cursor. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{cursorHasNext} -/// ~ db._create("five"); -/// ~ db.five.save({ name : "one" }); -/// ~ db.five.save({ name : "two" }); -/// ~ db.five.save({ name : "three" }); -/// ~ db.five.save({ name : "four" }); -/// ~ db.five.save({ name : "five" }); -/// var a = db.five.all(); -/// while (a.hasNext()) print(a.next()); -/// ~ db._drop("five") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief checks if the cursor is exhausted +`cursor.hasNext()` + +The *hasNext* operator returns *true*, then the cursor still has +documents. In this case the next document can be accessed using the +*next* operator, which will advance the cursor. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{cursorHasNext} +~ db._create("five"); +~ db.five.save({ name : "one" }); +~ db.five.save({ name : "two" }); +~ db.five.save({ name : "three" }); +~ db.five.save({ name : "four" }); +~ db.five.save({ name : "five" }); + var a = db.five.all(); + while (a.hasNext()) print(a.next()); +~ db._drop("five") +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/cursorNext.md b/Documentation/DocuBlocks/cursorNext.md index c77f90370c..a89e0a862d 100644 --- a/Documentation/DocuBlocks/cursorNext.md +++ b/Documentation/DocuBlocks/cursorNext.md @@ -1,25 +1,24 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock cursorNext -/// @brief returns the next result document -/// `cursor.next()` -/// -/// If the *hasNext* operator returns *true*, then the underlying -/// cursor of the simple query still has documents. In this case the -/// next document can be accessed using the *next* operator, which -/// will advance the underlying cursor. If you use *next* on an -/// exhausted cursor, then *undefined* is returned. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{cursorNext} -/// ~ db._create("five"); -/// ~ db.five.save({ name : "one" }); -/// ~ db.five.save({ name : "two" }); -/// ~ db.five.save({ name : "three" }); -/// ~ db.five.save({ name : "four" }); -/// ~ db.five.save({ name : "five" }); -/// db.five.all().next(); -/// ~ db._drop("five") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns the next result document +`cursor.next()` + +If the *hasNext* operator returns *true*, then the underlying +cursor of the simple query still has documents. In this case the +next document can be accessed using the *next* operator, which +will advance the underlying cursor. If you use *next* on an +exhausted cursor, then *undefined* is returned. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{cursorNext} +~ db._create("five"); +~ db.five.save({ name : "one" }); +~ db.five.save({ name : "two" }); +~ db.five.save({ name : "three" }); +~ db.five.save({ name : "four" }); +~ db.five.save({ name : "five" }); + db.five.all().next(); +~ db._drop("five") +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/cursorSetBatchSize.md b/Documentation/DocuBlocks/cursorSetBatchSize.md index 09d590ba91..5311ed2c36 100644 --- a/Documentation/DocuBlocks/cursorSetBatchSize.md +++ b/Documentation/DocuBlocks/cursorSetBatchSize.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock cursorSetBatchSize -/// @brief sets the batch size for any following requests -/// `cursor.setBatchSize(number)` -/// -/// Sets the batch size for queries. The batch size determines how many results -/// are at most transferred from the server to the client in one chunk. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief sets the batch size for any following requests +`cursor.setBatchSize(number)` + +Sets the batch size for queries. The batch size determines how many results +are at most transferred from the server to the client in one chunk. + diff --git a/Documentation/DocuBlocks/databaseCreateDatabase.md b/Documentation/DocuBlocks/databaseCreateDatabase.md index beb7df15d4..2ff5bcf2ef 100644 --- a/Documentation/DocuBlocks/databaseCreateDatabase.md +++ b/Documentation/DocuBlocks/databaseCreateDatabase.md @@ -1,52 +1,51 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseCreateDatabase -/// @brief create a new database -/// `db._createDatabase(name, options, users)` -/// -/// Creates a new database with the name specified by *name*. -/// There are restrictions for database names -/// (see [DatabaseNames](../NamingConventions/DatabaseNames.md)). -/// -/// Note that even if the database is created successfully, there will be no -/// change into the current database to the new database. Changing the current -/// database must explicitly be requested by using the -/// *db._useDatabase* method. -/// -/// The *options* attribute currently has no meaning and is reserved for -/// future use. -/// -/// The optional *users* attribute can be used to create initial users for -/// the new database. If specified, it must be a list of user objects. Each user -/// object can contain the following attributes: -/// -/// * *username*: the user name as a string. This attribute is mandatory. -/// * *passwd*: the user password as a string. If not specified, then it defaults -/// to the empty string. -/// * *active*: a boolean flag indicating whether the user account should be -/// active or not. The default value is *true*. -/// * *extra*: an optional JSON object with extra user information. The data -/// contained in *extra* will be stored for the user but not be interpreted -/// further by ArangoDB. -/// -/// If no initial users are specified, a default user *root* will be created -/// with an empty string password. This ensures that the new database will be -/// accessible via HTTP after it is created. -/// -/// You can create users in a database if no initial user is specified. Switch -/// into the new database (username and password must be identical to the current -/// session) and add or modify users with the following commands. -/// -/// ```js -/// require("@arangodb/users").save(username, password, true); -/// require("@arangodb/users").update(username, password, true); -/// require("@arangodb/users").remove(username); -/// ``` -/// Alternatively, you can specify user data directly. For example: -/// -/// ```js -/// db._createDatabase("newDB", [], [{ username: "newUser", passwd: "123456", active: true}]) -/// ``` -/// -/// Those methods can only be used from within the *_system* database. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief create a new database +`db._createDatabase(name, options, users)` + +Creates a new database with the name specified by *name*. +There are restrictions for database names +(see [DatabaseNames](../NamingConventions/DatabaseNames.md)). + +Note that even if the database is created successfully, there will be no +change into the current database to the new database. Changing the current +database must explicitly be requested by using the +*db._useDatabase* method. + +The *options* attribute currently has no meaning and is reserved for +future use. + +The optional *users* attribute can be used to create initial users for +the new database. If specified, it must be a list of user objects. Each user +object can contain the following attributes: + +* *username*: the user name as a string. This attribute is mandatory. +* *passwd*: the user password as a string. If not specified, then it defaults + to the empty string. +* *active*: a boolean flag indicating whether the user account should be + active or not. The default value is *true*. +* *extra*: an optional JSON object with extra user information. The data + contained in *extra* will be stored for the user but not be interpreted + further by ArangoDB. + +If no initial users are specified, a default user *root* will be created +with an empty string password. This ensures that the new database will be +accessible via HTTP after it is created. + +You can create users in a database if no initial user is specified. Switch +into the new database (username and password must be identical to the current +session) and add or modify users with the following commands. + +```js + require("@arangodb/users").save(username, password, true); + require("@arangodb/users").update(username, password, true); + require("@arangodb/users").remove(username); +``` +Alternatively, you can specify user data directly. For example: + +```js + db._createDatabase("newDB", [], [{ username: "newUser", passwd: "123456", active: true}]) +``` + +Those methods can only be used from within the *_system* database. + diff --git a/Documentation/DocuBlocks/databaseDisableQueryTracking.md b/Documentation/DocuBlocks/databaseDisableQueryTracking.md index 1ffe2f7eb8..ee35ba1960 100644 --- a/Documentation/DocuBlocks/databaseDisableQueryTracking.md +++ b/Documentation/DocuBlocks/databaseDisableQueryTracking.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseDisableQueryTracking -/// @brief disable the query tracking feature -/// `--database.disable-query-tracking flag` -/// -/// If *true*, the server's query tracking feature will be disabled by -/// default. -/// -/// The default is *false*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief disable the query tracking feature +`--database.disable-query-tracking flag` + +If *true*, the server's query tracking feature will be disabled by +default. + +The default is *false*. + diff --git a/Documentation/DocuBlocks/databaseDropDatabase.md b/Documentation/DocuBlocks/databaseDropDatabase.md index bd0d37af55..5b5c21f65e 100644 --- a/Documentation/DocuBlocks/databaseDropDatabase.md +++ b/Documentation/DocuBlocks/databaseDropDatabase.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseDropDatabase -/// @brief drop an existing database -/// `db._dropDatabase(name)` -/// -/// Drops the database specified by *name*. The database specified by -/// *name* must exist. -/// -/// **Note**: Dropping databases is only possible from within the *_system* -/// database. The *_system* database itself cannot be dropped. -/// -/// Databases are dropped asynchronously, and will be physically removed if -/// all clients have disconnected and references have been garbage-collected. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief drop an existing database +`db._dropDatabase(name)` + +Drops the database specified by *name*. The database specified by +*name* must exist. + +**Note**: Dropping databases is only possible from within the *_system* +database. The *_system* database itself cannot be dropped. + +Databases are dropped asynchronously, and will be physically removed if +all clients have disconnected and references have been garbage-collected. + diff --git a/Documentation/DocuBlocks/databaseId.md b/Documentation/DocuBlocks/databaseId.md index 958c199885..4179645839 100644 --- a/Documentation/DocuBlocks/databaseId.md +++ b/Documentation/DocuBlocks/databaseId.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseId -/// @brief return the database id -/// `db._id()` -/// -/// Returns the id of the current database as a string. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{dbId} -/// require("internal").db._id(); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief return the database id +`db._id()` + +Returns the id of the current database as a string. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{dbId} + require("internal").db._id(); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/databaseIgnoreDatafileErrors.md b/Documentation/DocuBlocks/databaseIgnoreDatafileErrors.md index 593ff913ed..15fdc6352b 100644 --- a/Documentation/DocuBlocks/databaseIgnoreDatafileErrors.md +++ b/Documentation/DocuBlocks/databaseIgnoreDatafileErrors.md @@ -1,35 +1,34 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseIgnoreDatafileErrors -/// @brief ignore datafile errors when loading collections -/// `--database.ignore-datafile-errors boolean` -/// -/// If set to `false`, CRC mismatch and other errors in collection datafiles -/// will lead to a collection not being loaded at all. The collection in this -/// case becomes unavailable. If such collection needs to be loaded during WAL -/// recovery, the WAL recovery will also abort (if not forced with option -/// `--wal.ignore-recovery-errors true`). -/// -/// Setting this flag to `false` protects users from unintentionally using a -/// collection with corrupted datafiles, from which only a subset of the -/// original data can be recovered. Working with such collection could lead -/// to data loss and follow up errors. -/// In order to access such collection, it is required to inspect and repair -/// the collection datafile with the datafile debugger (arango-dfdb). -/// -/// If set to `true`, CRC mismatch and other errors during the loading of a -/// collection will lead to the datafile being partially loaded, up to the -/// position of the first error. All data up to until the invalid position -/// will be loaded. This will enable users to continue with collection -/// datafiles -/// even if they are corrupted, but this will result in only a partial load -/// of the original data and potential follow up errors. The WAL recovery -/// will still abort when encountering a collection with a corrupted datafile, -/// at least if `--wal.ignore-recovery-errors` is not set to `true`. -/// -/// The default value is *false*, so collections with corrupted datafiles will -/// not be loaded at all, preventing partial loads and follow up errors. -/// However, -/// if such collection is required at server startup, during WAL recovery, the -/// server will abort the recovery and refuse to start. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ignore datafile errors when loading collections +`--database.ignore-datafile-errors boolean` + +If set to `false`, CRC mismatch and other errors in collection datafiles +will lead to a collection not being loaded at all. The collection in this +case becomes unavailable. If such collection needs to be loaded during WAL +recovery, the WAL recovery will also abort (if not forced with option +`--wal.ignore-recovery-errors true`). + +Setting this flag to `false` protects users from unintentionally using a +collection with corrupted datafiles, from which only a subset of the +original data can be recovered. Working with such collection could lead +to data loss and follow up errors. +In order to access such collection, it is required to inspect and repair +the collection datafile with the datafile debugger (arango-dfdb). + +If set to `true`, CRC mismatch and other errors during the loading of a +collection will lead to the datafile being partially loaded, up to the +position of the first error. All data up to until the invalid position +will be loaded. This will enable users to continue with collection +datafiles +even if they are corrupted, but this will result in only a partial load +of the original data and potential follow up errors. The WAL recovery +will still abort when encountering a collection with a corrupted datafile, +at least if `--wal.ignore-recovery-errors` is not set to `true`. + +The default value is *false*, so collections with corrupted datafiles will +not be loaded at all, preventing partial loads and follow up errors. +However, +if such collection is required at server startup, during WAL recovery, the +server will abort the recovery and refuse to start. + diff --git a/Documentation/DocuBlocks/databaseIsSystem.md b/Documentation/DocuBlocks/databaseIsSystem.md index a01d1cd742..1ac397a49d 100644 --- a/Documentation/DocuBlocks/databaseIsSystem.md +++ b/Documentation/DocuBlocks/databaseIsSystem.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseIsSystem -/// @brief return the database type -/// `db._isSystem()` -/// -/// Returns whether the currently used database is the *_system* database. -/// The system database has some special privileges and properties, for example, -/// database management operations such as create or drop can only be executed -/// from within this database. Additionally, the *_system* database itself -/// cannot be dropped. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief return the database type +`db._isSystem()` + +Returns whether the currently used database is the *_system* database. +The system database has some special privileges and properties, for example, +database management operations such as create or drop can only be executed +from within this database. Additionally, the *_system* database itself +cannot be dropped. + diff --git a/Documentation/DocuBlocks/databaseListDatabase.md b/Documentation/DocuBlocks/databaseListDatabase.md index a3a6524ee9..bf19bedf02 100644 --- a/Documentation/DocuBlocks/databaseListDatabase.md +++ b/Documentation/DocuBlocks/databaseListDatabase.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseListDatabase -/// @brief return the list of all existing databases -/// `db._listDatabases()` -/// -/// Returns the list of all databases. This method can only be used from within -/// the *_system* database. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief return the list of all existing databases +`db._listDatabases()` + +Returns the list of all databases. This method can only be used from within +the *_system* database. + diff --git a/Documentation/DocuBlocks/databaseName.md b/Documentation/DocuBlocks/databaseName.md index 8e94357dfc..7f4a4d964d 100644 --- a/Documentation/DocuBlocks/databaseName.md +++ b/Documentation/DocuBlocks/databaseName.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseName -/// @brief return the database name -/// `db._name()` -/// -/// Returns the name of the current database as a string. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{dbName} -/// require("internal").db._name(); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief return the database name +`db._name()` + +Returns the name of the current database as a string. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{dbName} + require("internal").db._name(); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/databasePath.md b/Documentation/DocuBlocks/databasePath.md index cf25623c9d..98bf8e5542 100644 --- a/Documentation/DocuBlocks/databasePath.md +++ b/Documentation/DocuBlocks/databasePath.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databasePath -/// @brief return the path to database files -/// `db._path()` -/// -/// Returns the filesystem path of the current database as a string. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{dbPath} -/// require("internal").db._path(); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief return the path to database files +`db._path()` + +Returns the filesystem path of the current database as a string. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{dbPath} + require("internal").db._path(); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/databaseThrowCollectionNotLoadedError.md b/Documentation/DocuBlocks/databaseThrowCollectionNotLoadedError.md index b123951ce7..3c3dafc6e3 100644 --- a/Documentation/DocuBlocks/databaseThrowCollectionNotLoadedError.md +++ b/Documentation/DocuBlocks/databaseThrowCollectionNotLoadedError.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseThrowCollectionNotLoadedError -/// @brief throw collection not loaded error -/// `--database.throw-collection-not-loaded-error flag` -/// -/// Accessing a not-yet loaded collection will automatically load a collection -/// on first access. This flag controls what happens in case an operation -/// would need to wait for another thread to finalize loading a collection. If -/// set to *true*, then the first operation that accesses an unloaded -/// collection -/// will load it. Further threads that try to access the same collection while -/// it is still loading will get an error (1238, *collection not loaded*). -/// When -/// the initial operation has completed loading the collection, all operations -/// on the collection can be carried out normally, and error 1238 will not be -/// thrown. -/// -/// If set to *false*, the first thread that accesses a not-yet loaded -/// collection -/// will still load it. Other threads that try to access the collection while -/// loading will not fail with error 1238 but instead block until the -/// collection -/// is fully loaded. This configuration might lead to all server threads being -/// blocked because they are all waiting for the same collection to complete -/// loading. Setting the option to *true* will prevent this from happening, -/// but -/// requires clients to catch error 1238 and react on it (maybe by scheduling -/// a retry for later). -/// -/// The default value is *false*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief throw collection not loaded error +`--database.throw-collection-not-loaded-error flag` + +Accessing a not-yet loaded collection will automatically load a collection +on first access. This flag controls what happens in case an operation +would need to wait for another thread to finalize loading a collection. If +set to *true*, then the first operation that accesses an unloaded +collection +will load it. Further threads that try to access the same collection while +it is still loading will get an error (1238, *collection not loaded*). +When +the initial operation has completed loading the collection, all operations +on the collection can be carried out normally, and error 1238 will not be +thrown. + +If set to *false*, the first thread that accesses a not-yet loaded +collection +will still load it. Other threads that try to access the collection while +loading will not fail with error 1238 but instead block until the +collection +is fully loaded. This configuration might lead to all server threads being +blocked because they are all waiting for the same collection to complete +loading. Setting the option to *true* will prevent this from happening, +but +requires clients to catch error 1238 and react on it (maybe by scheduling +a retry for later). + +The default value is *false*. + diff --git a/Documentation/DocuBlocks/databaseUseDatabase.md b/Documentation/DocuBlocks/databaseUseDatabase.md index 1f797dad90..63a2ba01ed 100644 --- a/Documentation/DocuBlocks/databaseUseDatabase.md +++ b/Documentation/DocuBlocks/databaseUseDatabase.md @@ -1,20 +1,19 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseUseDatabase -/// @brief change the current database -/// `db._useDatabase(name)` -/// -/// Changes the current database to the database specified by *name*. Note -/// that the database specified by *name* must already exist. -/// -/// Changing the database might be disallowed in some contexts, for example -/// server-side actions (including Foxx). -/// -/// When performing this command from arangosh, the current credentials (username -/// and password) will be re-used. These credentials might not be valid to -/// connect to the database specified by *name*. Additionally, the database -/// only be accessed from certain endpoints only. In this case, switching the -/// database might not work, and the connection / session should be closed and -/// restarted with different username and password credentials and/or -/// endpoint data. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief change the current database +`db._useDatabase(name)` + +Changes the current database to the database specified by *name*. Note +that the database specified by *name* must already exist. + +Changing the database might be disallowed in some contexts, for example +server-side actions (including Foxx). + +When performing this command from arangosh, the current credentials (username +and password) will be re-used. These credentials might not be valid to +connect to the database specified by *name*. Additionally, the database +only be accessed from certain endpoints only. In this case, switching the +database might not work, and the connection / session should be closed and +restarted with different username and password credentials and/or +endpoint data. + diff --git a/Documentation/DocuBlocks/databaseVersion.md b/Documentation/DocuBlocks/databaseVersion.md index f5a791e4f3..a964f4c397 100644 --- a/Documentation/DocuBlocks/databaseVersion.md +++ b/Documentation/DocuBlocks/databaseVersion.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock databaseVersion -/// @brief return the server version string -/// `db._version()` -/// -/// Returns the server version string. Note that this is not the version of the -/// database. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{dbVersion} -/// require("internal").db._version(); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief return the server version string +`db._version()` + +Returns the server version string. Note that this is not the version of the +database. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{dbVersion} + require("internal").db._version(); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/documentsCollectionAny.md b/Documentation/DocuBlocks/documentsCollectionAny.md index c7f9c96ffd..331e31daf3 100644 --- a/Documentation/DocuBlocks/documentsCollectionAny.md +++ b/Documentation/DocuBlocks/documentsCollectionAny.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionAny -/// @brief returns any document from a collection -/// `collection.any()` -/// -/// Returns a random document from the collection or *null* if none exists. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns any document from a collection +`collection.any()` + +Returns a random document from the collection or *null* if none exists. + diff --git a/Documentation/DocuBlocks/documentsCollectionExists.md b/Documentation/DocuBlocks/documentsCollectionExists.md index b1986136dd..f8d6ef177a 100644 --- a/Documentation/DocuBlocks/documentsCollectionExists.md +++ b/Documentation/DocuBlocks/documentsCollectionExists.md @@ -1,28 +1,27 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionExists -/// @brief checks whether a document exists -/// `collection.exists(document)` -/// -/// The *exists* method determines whether a document exists given its -/// identifier. Instead of returning the found document or an error, this -/// method will return either *true* or *false*. It can thus be used -/// for easy existence checks. -/// -/// The *document* method finds a document given its identifier. It returns -/// the document. Note that the returned document contains two -/// pseudo-attributes, namely *_id* and *_rev*. *_id* contains the -/// document-handle and *_rev* the revision of the document. -/// -/// No error will be thrown if the sought document or collection does not -/// exist. -/// Still this method will throw an error if used improperly, e.g. when called -/// with a non-document handle, a non-document, or when a cross-collection -/// request is performed. -/// -/// `collection.exists(document-handle)` -/// -/// As before. Instead of document a *document-handle* can be passed as -/// first argument. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief checks whether a document exists +`collection.exists(document)` + +The *exists* method determines whether a document exists given its +identifier. Instead of returning the found document or an error, this +method will return either *true* or *false*. It can thus be used +for easy existence checks. + +The *document* method finds a document given its identifier. It returns +the document. Note that the returned document contains two +pseudo-attributes, namely *_id* and *_rev*. *_id* contains the +document-handle and *_rev* the revision of the document. + +No error will be thrown if the sought document or collection does not +exist. +Still this method will throw an error if used improperly, e.g. when called +with a non-document handle, a non-document, or when a cross-collection +request is performed. + +`collection.exists(document-handle)` + +As before. Instead of document a *document-handle* can be passed as +first argument. + + diff --git a/Documentation/DocuBlocks/documentsCollectionFirst.md b/Documentation/DocuBlocks/documentsCollectionFirst.md index d8500f8c43..8673f7f580 100644 --- a/Documentation/DocuBlocks/documentsCollectionFirst.md +++ b/Documentation/DocuBlocks/documentsCollectionFirst.md @@ -1,40 +1,39 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionFirst -/// @brief selects the n first documents in the collection -/// `collection.first(count)` -/// -/// The *first* method returns the n first documents from the collection, in -/// order of document insertion/update time. -/// -/// If called with the *count* argument, the result is a list of up to -/// *count* documents. If *count* is bigger than the number of documents -/// in the collection, then the result will contain as many documents as there -/// are in the collection. -/// The result list is ordered, with the "oldest" documents being positioned at -/// the beginning of the result list. -/// -/// When called without an argument, the result is the first document from the -/// collection. If the collection does not contain any documents, the result -/// returned is *null*. -/// -/// **Note**: this method is not supported in sharded collections with more than -/// one shard. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionFirst} -/// ~ db._create("example"); -/// ~ db.example.save({ Hello : "world" }); -/// ~ db.example.save({ Foo : "bar" }); -/// db.example.first(1); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionFirstNull} -/// ~ db._create("example"); -/// ~ db.example.save({ Hello : "world" }); -/// db.example.first(); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief selects the n first documents in the collection +`collection.first(count)` + +The *first* method returns the n first documents from the collection, in +order of document insertion/update time. + +If called with the *count* argument, the result is a list of up to +*count* documents. If *count* is bigger than the number of documents +in the collection, then the result will contain as many documents as there +are in the collection. +The result list is ordered, with the "oldest" documents being positioned at +the beginning of the result list. + +When called without an argument, the result is the first document from the +collection. If the collection does not contain any documents, the result +returned is *null*. + +**Note**: this method is not supported in sharded collections with more than +one shard. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionFirst} +~ db._create("example"); +~ db.example.save({ Hello : "world" }); +~ db.example.save({ Foo : "bar" }); + db.example.first(1); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionFirstNull} +~ db._create("example"); +~ db.example.save({ Hello : "world" }); + db.example.first(); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/documentsCollectionInsert.md b/Documentation/DocuBlocks/documentsCollectionInsert.md index f050978520..6ce1d594a7 100644 --- a/Documentation/DocuBlocks/documentsCollectionInsert.md +++ b/Documentation/DocuBlocks/documentsCollectionInsert.md @@ -1,39 +1,38 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionInsert -/// @brief insert a new document -/// `collection.insert(data)` -/// -/// Creates a new document in the *collection* from the given *data*. The -/// *data* must be an object. -/// -/// The method returns a document with the attributes *_id* and *_rev*. -/// The attribute *_id* contains the document handle of the newly created -/// document, the attribute *_rev* contains the document revision. -/// -/// `collection.insert(data, waitForSync)` -/// -/// Creates a new document in the *collection* from the given *data* as -/// above. The optional *waitForSync* parameter can be used to force -/// synchronization of the document creation operation to disk even in case -/// that the *waitForSync* flag had been disabled for the entire collection. -/// Thus, the *waitForSync* parameter can be used to force synchronization -/// of just specific operations. To use this, set the *waitForSync* parameter -/// to *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// Note: since ArangoDB 2.2, *insert* is an alias for *save*. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionInsert} -/// ~ db._create("example"); -/// db.example.insert({ Hello : "World" }); -/// db.example.insert({ Hello : "World" }, true); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief insert a new document +`collection.insert(data)` + +Creates a new document in the *collection* from the given *data*. The +*data* must be an object. + +The method returns a document with the attributes *_id* and *_rev*. +The attribute *_id* contains the document handle of the newly created +document, the attribute *_rev* contains the document revision. + +`collection.insert(data, waitForSync)` + +Creates a new document in the *collection* from the given *data* as +above. The optional *waitForSync* parameter can be used to force +synchronization of the document creation operation to disk even in case +that the *waitForSync* flag had been disabled for the entire collection. +Thus, the *waitForSync* parameter can be used to force synchronization +of just specific operations. To use this, set the *waitForSync* parameter +to *true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +Note: since ArangoDB 2.2, *insert* is an alias for *save*. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionInsert} +~ db._create("example"); + db.example.insert({ Hello : "World" }); + db.example.insert({ Hello : "World" }, true); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsCollectionLast.md b/Documentation/DocuBlocks/documentsCollectionLast.md index 21235fa2b7..fd237cbe26 100644 --- a/Documentation/DocuBlocks/documentsCollectionLast.md +++ b/Documentation/DocuBlocks/documentsCollectionLast.md @@ -1,41 +1,40 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionLast -/// @brief selects the n last documents in the collection -/// `collection.last(count)` -/// -/// The *last* method returns the n last documents from the collection, in -/// order of document insertion/update time. -/// -/// If called with the *count* argument, the result is a list of up to -/// *count* documents. If *count* is bigger than the number of documents -/// in the collection, then the result will contain as many documents as there -/// are in the collection. -/// The result list is ordered, with the "latest" documents being positioned at -/// the beginning of the result list. -/// -/// When called without an argument, the result is the last document from the -/// collection. If the collection does not contain any documents, the result -/// returned is *null*. -/// -/// **Note**: this method is not supported in sharded collections with more than -/// one shard. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionLast} -/// ~ db._create("example"); -/// ~ db.example.save({ Hello : "world" }); -/// ~ db.example.save({ Foo : "bar" }); -/// db.example.last(2); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionLastNull} -/// ~ db._create("example"); -/// ~ db.example.save({ Hello : "world" }); -/// db.example.last(1); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief selects the n last documents in the collection +`collection.last(count)` + +The *last* method returns the n last documents from the collection, in +order of document insertion/update time. + +If called with the *count* argument, the result is a list of up to +*count* documents. If *count* is bigger than the number of documents +in the collection, then the result will contain as many documents as there +are in the collection. +The result list is ordered, with the "latest" documents being positioned at +the beginning of the result list. + +When called without an argument, the result is the last document from the +collection. If the collection does not contain any documents, the result +returned is *null*. + +**Note**: this method is not supported in sharded collections with more than +one shard. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionLast} +~ db._create("example"); +~ db.example.save({ Hello : "world" }); +~ db.example.save({ Foo : "bar" }); + db.example.last(2); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionLastNull} +~ db._create("example"); +~ db.example.save({ Hello : "world" }); + db.example.last(1); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsCollectionName.md b/Documentation/DocuBlocks/documentsCollectionName.md index 8a5a4e6f06..eaf169340e 100644 --- a/Documentation/DocuBlocks/documentsCollectionName.md +++ b/Documentation/DocuBlocks/documentsCollectionName.md @@ -1,57 +1,56 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionName -/// @brief looks up a document -/// `collection.document(document)` -/// -/// The *document* method finds a document given its identifier or a document -/// object containing the *_id* or *_key* attribute. The method returns -/// the document if it can be found. -/// -/// An error is thrown if *_rev* is specified but the document found has a -/// different revision already. An error is also thrown if no document exists -/// with the given *_id* or *_key* value. -/// -/// Please note that if the method is executed on the arangod server (e.g. from -/// inside a Foxx application), an immutable document object will be returned -/// for performance reasons. It is not possible to change attributes of this -/// immutable object. To update or patch the returned document, it needs to be -/// cloned/copied into a regular JavaScript object first. This is not necessary -/// if the *document* method is called from out of arangosh or from any other -/// client. -/// -/// `collection.document(document-handle)` -/// -/// As before. Instead of document a *document-handle* can be passed as -/// first argument. -/// -/// *Examples* -/// -/// Returns the document for a document-handle: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionName} -/// ~ db._create("example"); -/// ~ var myid = db.example.insert({_key: "2873916"}); -/// db.example.document("example/2873916"); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// An error is raised if the document is unknown: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionNameUnknown} -/// ~ db._create("example"); -/// ~ var myid = db.example.insert({_key: "2873916"}); -/// | db.example.document("example/4472917"); -/// ~ // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND) -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// An error is raised if the handle is invalid: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionNameHandle} -/// ~ db._create("example"); -/// db.example.document(""); // xpError(ERROR_ARANGO_DOCUMENT_HANDLE_BAD) -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief looks up a document +`collection.document(document)` + +The *document* method finds a document given its identifier or a document +object containing the *_id* or *_key* attribute. The method returns +the document if it can be found. + +An error is thrown if *_rev* is specified but the document found has a +different revision already. An error is also thrown if no document exists +with the given *_id* or *_key* value. + +Please note that if the method is executed on the arangod server (e.g. from +inside a Foxx application), an immutable document object will be returned +for performance reasons. It is not possible to change attributes of this +immutable object. To update or patch the returned document, it needs to be +cloned/copied into a regular JavaScript object first. This is not necessary +if the *document* method is called from out of arangosh or from any other +client. + +`collection.document(document-handle)` + +As before. Instead of document a *document-handle* can be passed as +first argument. + +*Examples* + +Returns the document for a document-handle: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionName} +~ db._create("example"); +~ var myid = db.example.insert({_key: "2873916"}); + db.example.document("example/2873916"); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +An error is raised if the document is unknown: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionNameUnknown} +~ db._create("example"); +~ var myid = db.example.insert({_key: "2873916"}); +| db.example.document("example/4472917"); +~ // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND) +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +An error is raised if the handle is invalid: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionNameHandle} +~ db._create("example"); + db.example.document(""); // xpError(ERROR_ARANGO_DOCUMENT_HANDLE_BAD) +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsCollectionRemove.md b/Documentation/DocuBlocks/documentsCollectionRemove.md index 020f5e653b..75b7e5222c 100644 --- a/Documentation/DocuBlocks/documentsCollectionRemove.md +++ b/Documentation/DocuBlocks/documentsCollectionRemove.md @@ -1,59 +1,58 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionRemove -/// @brief removes a document -/// `collection.remove(document)` -/// -/// Removes a document. If there is revision mismatch, then an error is thrown. -/// -/// `collection.remove(document, true)` -/// -/// Removes a document. If there is revision mismatch, then mismatch is ignored -/// and document is deleted. The function returns *true* if the document -/// existed and was deleted. It returns *false*, if the document was already -/// deleted. -/// -/// `collection.remove(document, true, waitForSync)` -/// -/// The optional *waitForSync* parameter can be used to force synchronization -/// of the document deletion operation to disk even in case that the -/// *waitForSync* flag had been disabled for the entire collection. Thus, -/// the *waitForSync* parameter can be used to force synchronization of just -/// specific operations. To use this, set the *waitForSync* parameter to -/// *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// `collection.remove(document-handle, data)` -/// -/// As before. Instead of document a *document-handle* can be passed as -/// first argument. -/// -/// @EXAMPLES -/// -/// Remove a document: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentDocumentRemove} -/// ~ db._create("example"); -/// a1 = db.example.insert({ a : 1 }); -/// db.example.document(a1); -/// db.example.remove(a1); -/// db.example.document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Remove a document with a conflict: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentDocumentRemoveConflict} -/// ~ db._create("example"); -/// a1 = db.example.insert({ a : 1 }); -/// a2 = db.example.replace(a1, { a : 2 }); -/// db.example.remove(a1); // xpError(ERROR_ARANGO_CONFLICT); -/// db.example.remove(a1, true); -/// db.example.document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief removes a document +`collection.remove(document)` + +Removes a document. If there is revision mismatch, then an error is thrown. + +`collection.remove(document, true)` + +Removes a document. If there is revision mismatch, then mismatch is ignored +and document is deleted. The function returns *true* if the document +existed and was deleted. It returns *false*, if the document was already +deleted. + +`collection.remove(document, true, waitForSync)` + +The optional *waitForSync* parameter can be used to force synchronization +of the document deletion operation to disk even in case that the +*waitForSync* flag had been disabled for the entire collection. Thus, +the *waitForSync* parameter can be used to force synchronization of just +specific operations. To use this, set the *waitForSync* parameter to +*true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +`collection.remove(document-handle, data)` + +As before. Instead of document a *document-handle* can be passed as +first argument. + +@EXAMPLES + +Remove a document: + +@EXAMPLE_ARANGOSH_OUTPUT{documentDocumentRemove} +~ db._create("example"); + a1 = db.example.insert({ a : 1 }); + db.example.document(a1); + db.example.remove(a1); + db.example.document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Remove a document with a conflict: + +@EXAMPLE_ARANGOSH_OUTPUT{documentDocumentRemoveConflict} +~ db._create("example"); + a1 = db.example.insert({ a : 1 }); + a2 = db.example.replace(a1, { a : 2 }); + db.example.remove(a1); // xpError(ERROR_ARANGO_CONFLICT); + db.example.remove(a1, true); + db.example.document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsCollectionRemoveByExample.md b/Documentation/DocuBlocks/documentsCollectionRemoveByExample.md index 217450035c..fab77b87d5 100644 --- a/Documentation/DocuBlocks/documentsCollectionRemoveByExample.md +++ b/Documentation/DocuBlocks/documentsCollectionRemoveByExample.md @@ -1,37 +1,36 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionRemoveByExample -/// @brief removes documents matching an example -/// `collection.removeByExample(example)` -/// -/// Removes all documents matching an example. -/// -/// `collection.removeByExample(document, waitForSync)` -/// -/// The optional *waitForSync* parameter can be used to force synchronization -/// of the document deletion operation to disk even in case that the -/// *waitForSync* flag had been disabled for the entire collection. Thus, -/// the *waitForSync* parameter can be used to force synchronization of just -/// specific operations. To use this, set the *waitForSync* parameter to -/// *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// `collection.removeByExample(document, waitForSync, limit)` -/// -/// The optional *limit* parameter can be used to restrict the number of -/// removals to the specified value. If *limit* is specified but less than the -/// number of documents in the collection, it is undefined which documents are -/// removed. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{010_documentsCollectionRemoveByExample} -/// ~ db._create("example"); -/// ~ db.example.save({ Hello : "world" }); -/// db.example.removeByExample( {Hello : "world"} ); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief removes documents matching an example +`collection.removeByExample(example)` + +Removes all documents matching an example. + +`collection.removeByExample(document, waitForSync)` + +The optional *waitForSync* parameter can be used to force synchronization +of the document deletion operation to disk even in case that the +*waitForSync* flag had been disabled for the entire collection. Thus, +the *waitForSync* parameter can be used to force synchronization of just +specific operations. To use this, set the *waitForSync* parameter to +*true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +`collection.removeByExample(document, waitForSync, limit)` + +The optional *limit* parameter can be used to restrict the number of +removals to the specified value. If *limit* is specified but less than the +number of documents in the collection, it is undefined which documents are +removed. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{010_documentsCollectionRemoveByExample} +~ db._create("example"); +~ db.example.save({ Hello : "world" }); + db.example.removeByExample( {Hello : "world"} ); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/documentsCollectionReplace.md b/Documentation/DocuBlocks/documentsCollectionReplace.md index 488e2382cd..352445bcb6 100644 --- a/Documentation/DocuBlocks/documentsCollectionReplace.md +++ b/Documentation/DocuBlocks/documentsCollectionReplace.md @@ -1,67 +1,66 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionReplace -/// @brief replaces a document -/// `collection.replace(document, data)` -/// -/// Replaces an existing *document*. The *document* must be a document in -/// the current collection. This document is then replaced with the -/// *data* given as second argument. -/// -/// The method returns a document with the attributes *_id*, *_rev* and -/// *{_oldRev*. The attribute *_id* contains the document handle of the -/// updated document, the attribute *_rev* contains the document revision of -/// the updated document, the attribute *_oldRev* contains the revision of -/// the old (now replaced) document. -/// -/// If there is a conflict, i. e. if the revision of the *document* does not -/// match the revision in the collection, then an error is thrown. -/// -/// `collection.replace(document, data, true)` or -/// `collection.replace(document, data, overwrite: true)` -/// -/// As before, but in case of a conflict, the conflict is ignored and the old -/// document is overwritten. -/// -/// `collection.replace(document, data, true, waitForSync)` or -/// `collection.replace(document, data, overwrite: true, waitForSync: true or false)` -/// -/// The optional *waitForSync* parameter can be used to force -/// synchronization of the document replacement operation to disk even in case -/// that the *waitForSync* flag had been disabled for the entire collection. -/// Thus, the *waitForSync* parameter can be used to force synchronization -/// of just specific operations. To use this, set the *waitForSync* parameter -/// to *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// `collection.replace(document-handle, data)` -/// -/// As before. Instead of document a *document-handle* can be passed as -/// first argument. -/// -/// @EXAMPLES -/// -/// Create and update a document: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionReplace} -/// ~ db._create("example"); -/// a1 = db.example.insert({ a : 1 }); -/// a2 = db.example.replace(a1, { a : 2 }); -/// a3 = db.example.replace(a1, { a : 3 }); // xpError(ERROR_ARANGO_CONFLICT); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Use a document handle: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionReplaceHandle} -/// ~ db._create("example"); -/// ~ var myid = db.example.insert({_key: "3903044"}); -/// a1 = db.example.insert({ a : 1 }); -/// a2 = db.example.replace("example/3903044", { a : 2 }); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief replaces a document +`collection.replace(document, data)` + +Replaces an existing *document*. The *document* must be a document in +the current collection. This document is then replaced with the +*data* given as second argument. + +The method returns a document with the attributes *_id*, *_rev* and +*{_oldRev*. The attribute *_id* contains the document handle of the +updated document, the attribute *_rev* contains the document revision of +the updated document, the attribute *_oldRev* contains the revision of +the old (now replaced) document. + +If there is a conflict, i. e. if the revision of the *document* does not +match the revision in the collection, then an error is thrown. + +`collection.replace(document, data, true)` or +`collection.replace(document, data, overwrite: true)` + +As before, but in case of a conflict, the conflict is ignored and the old +document is overwritten. + +`collection.replace(document, data, true, waitForSync)` or +`collection.replace(document, data, overwrite: true, waitForSync: true or false)` + +The optional *waitForSync* parameter can be used to force +synchronization of the document replacement operation to disk even in case +that the *waitForSync* flag had been disabled for the entire collection. +Thus, the *waitForSync* parameter can be used to force synchronization +of just specific operations. To use this, set the *waitForSync* parameter +to *true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +`collection.replace(document-handle, data)` + +As before. Instead of document a *document-handle* can be passed as +first argument. + +@EXAMPLES + +Create and update a document: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionReplace} +~ db._create("example"); + a1 = db.example.insert({ a : 1 }); + a2 = db.example.replace(a1, { a : 2 }); + a3 = db.example.replace(a1, { a : 3 }); // xpError(ERROR_ARANGO_CONFLICT); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Use a document handle: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionReplaceHandle} +~ db._create("example"); +~ var myid = db.example.insert({_key: "3903044"}); + a1 = db.example.insert({ a : 1 }); + a2 = db.example.replace("example/3903044", { a : 2 }); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsCollectionReplaceByExample.md b/Documentation/DocuBlocks/documentsCollectionReplaceByExample.md index a80a618625..440cda3c9b 100644 --- a/Documentation/DocuBlocks/documentsCollectionReplaceByExample.md +++ b/Documentation/DocuBlocks/documentsCollectionReplaceByExample.md @@ -1,40 +1,39 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionReplaceByExample -/// @brief replaces documents matching an example -/// `collection.replaceByExample(example, newValue)` -/// -/// Replaces all documents matching an example with a new document body. -/// The entire document body of each document matching the *example* will be -/// replaced with *newValue*. The document meta-attributes such as *_id*, -/// *_key*, *_from*, *_to* will not be replaced. -/// -/// `collection.replaceByExample(document, newValue, waitForSync)` -/// -/// The optional *waitForSync* parameter can be used to force synchronization -/// of the document replacement operation to disk even in case that the -/// *waitForSync* flag had been disabled for the entire collection. Thus, -/// the *waitForSync* parameter can be used to force synchronization of just -/// specific operations. To use this, set the *waitForSync* parameter to -/// *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// `collection.replaceByExample(document, newValue, waitForSync, limit)` -/// -/// The optional *limit* parameter can be used to restrict the number of -/// replacements to the specified value. If *limit* is specified but less than -/// the number of documents in the collection, it is undefined which documents are -/// replaced. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{011_documentsCollectionReplaceByExample} -/// ~ db._create("example"); -/// db.example.save({ Hello : "world" }); -/// db.example.replaceByExample({ Hello: "world" }, {Hello: "mars"}, false, 5); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief replaces documents matching an example +`collection.replaceByExample(example, newValue)` + +Replaces all documents matching an example with a new document body. +The entire document body of each document matching the *example* will be +replaced with *newValue*. The document meta-attributes such as *_id*, +*_key*, *_from*, *_to* will not be replaced. + +`collection.replaceByExample(document, newValue, waitForSync)` + +The optional *waitForSync* parameter can be used to force synchronization +of the document replacement operation to disk even in case that the +*waitForSync* flag had been disabled for the entire collection. Thus, +the *waitForSync* parameter can be used to force synchronization of just +specific operations. To use this, set the *waitForSync* parameter to +*true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +`collection.replaceByExample(document, newValue, waitForSync, limit)` + +The optional *limit* parameter can be used to restrict the number of +replacements to the specified value. If *limit* is specified but less than +the number of documents in the collection, it is undefined which documents are +replaced. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{011_documentsCollectionReplaceByExample} +~ db._create("example"); + db.example.save({ Hello : "world" }); + db.example.replaceByExample({ Hello: "world" }, {Hello: "mars"}, false, 5); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/documentsCollectionUpdate.md b/Documentation/DocuBlocks/documentsCollectionUpdate.md index ec2e4b9f31..7a7be121d3 100644 --- a/Documentation/DocuBlocks/documentsCollectionUpdate.md +++ b/Documentation/DocuBlocks/documentsCollectionUpdate.md @@ -1,109 +1,108 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionUpdate -/// @brief updates a document -/// `collection.update(document, data, overwrite, keepNull, waitForSync)` or -/// `collection.update(document, data, -/// overwrite: true or false, keepNull: true or false, waitForSync: true or false)` -/// -/// Updates an existing *document*. The *document* must be a document in -/// the current collection. This document is then patched with the -/// *data* given as second argument. The optional *overwrite* parameter can -/// be used to control the behavior in case of version conflicts (see below). -/// The optional *keepNull* parameter can be used to modify the behavior when -/// handling *null* values. Normally, *null* values are stored in the -/// database. By setting the *keepNull* parameter to *false*, this behavior -/// can be changed so that all attributes in *data* with *null* values will -/// be removed from the target document. -/// -/// The optional *waitForSync* parameter can be used to force -/// synchronization of the document update operation to disk even in case -/// that the *waitForSync* flag had been disabled for the entire collection. -/// Thus, the *waitForSync* parameter can be used to force synchronization -/// of just specific operations. To use this, set the *waitForSync* parameter -/// to *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// The method returns a document with the attributes *_id*, *_rev* and -/// *_oldRev*. The attribute *_id* contains the document handle of the -/// updated document, the attribute *_rev* contains the document revision of -/// the updated document, the attribute *_oldRev* contains the revision of -/// the old (now replaced) document. -/// -/// If there is a conflict, i. e. if the revision of the *document* does not -/// match the revision in the collection, then an error is thrown. -/// -/// `collection.update(document, data, true)` -/// -/// As before, but in case of a conflict, the conflict is ignored and the old -/// document is overwritten. -/// -/// collection.update(document-handle, data)` -/// -/// As before. Instead of document a document-handle can be passed as -/// first argument. -/// -/// *Examples* -/// -/// Create and update a document: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdate} -/// ~ db._create("example"); -/// a1 = db.example.insert({"a" : 1}); -/// a2 = db.example.update(a1, {"b" : 2, "c" : 3}); -/// a3 = db.example.update(a1, {"d" : 4}); // xpError(ERROR_ARANGO_CONFLICT); -/// a4 = db.example.update(a2, {"e" : 5, "f" : 6 }); -/// db.example.document(a4); -/// a5 = db.example.update(a4, {"a" : 1, c : 9, e : 42 }); -/// db.example.document(a5); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Use a document handle: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandle} -/// ~ db._create("example"); -/// ~ var myid = db.example.insert({_key: "18612115"}); -/// a1 = db.example.insert({"a" : 1}); -/// a2 = db.example.update("example/18612115", { "x" : 1, "y" : 2 }); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Use the keepNull parameter to remove attributes with null values: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandleKeepNull} -/// ~ db._create("example"); -/// ~ var myid = db.example.insert({_key: "19988371"}); -/// db.example.insert({"a" : 1}); -/// |db.example.update("example/19988371", -/// { "b" : null, "c" : null, "d" : 3 }); -/// db.example.document("example/19988371"); -/// db.example.update("example/19988371", { "a" : null }, false, false); -/// db.example.document("example/19988371"); -/// | db.example.update("example/19988371", -/// { "b" : null, "c": null, "d" : null }, false, false); -/// db.example.document("example/19988371"); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Patching array values: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandleArray} -/// ~ db._create("example"); -/// ~ var myid = db.example.insert({_key: "20774803"}); -/// | db.example.insert({"a" : { "one" : 1, "two" : 2, "three" : 3 }, -/// "b" : { }}); -/// | db.example.update("example/20774803", {"a" : { "four" : 4 }, -/// "b" : { "b1" : 1 }}); -/// db.example.document("example/20774803"); -/// | db.example.update("example/20774803", { "a" : { "one" : null }, -/// | "b" : null }, -/// false, false); -/// db.example.document("example/20774803"); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief updates a document +`collection.update(document, data, overwrite, keepNull, waitForSync)` or +`collection.update(document, data, +overwrite: true or false, keepNull: true or false, waitForSync: true or false)` + +Updates an existing *document*. The *document* must be a document in +the current collection. This document is then patched with the +*data* given as second argument. The optional *overwrite* parameter can +be used to control the behavior in case of version conflicts (see below). +The optional *keepNull* parameter can be used to modify the behavior when +handling *null* values. Normally, *null* values are stored in the +database. By setting the *keepNull* parameter to *false*, this behavior +can be changed so that all attributes in *data* with *null* values will +be removed from the target document. + +The optional *waitForSync* parameter can be used to force +synchronization of the document update operation to disk even in case +that the *waitForSync* flag had been disabled for the entire collection. +Thus, the *waitForSync* parameter can be used to force synchronization +of just specific operations. To use this, set the *waitForSync* parameter +to *true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +The method returns a document with the attributes *_id*, *_rev* and +*_oldRev*. The attribute *_id* contains the document handle of the +updated document, the attribute *_rev* contains the document revision of +the updated document, the attribute *_oldRev* contains the revision of +the old (now replaced) document. + +If there is a conflict, i. e. if the revision of the *document* does not +match the revision in the collection, then an error is thrown. + +`collection.update(document, data, true)` + +As before, but in case of a conflict, the conflict is ignored and the old +document is overwritten. + +collection.update(document-handle, data)` + +As before. Instead of document a document-handle can be passed as +first argument. + +*Examples* + +Create and update a document: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdate} +~ db._create("example"); + a1 = db.example.insert({"a" : 1}); + a2 = db.example.update(a1, {"b" : 2, "c" : 3}); + a3 = db.example.update(a1, {"d" : 4}); // xpError(ERROR_ARANGO_CONFLICT); + a4 = db.example.update(a2, {"e" : 5, "f" : 6 }); + db.example.document(a4); + a5 = db.example.update(a4, {"a" : 1, c : 9, e : 42 }); + db.example.document(a5); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Use a document handle: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandle} +~ db._create("example"); +~ var myid = db.example.insert({_key: "18612115"}); + a1 = db.example.insert({"a" : 1}); + a2 = db.example.update("example/18612115", { "x" : 1, "y" : 2 }); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Use the keepNull parameter to remove attributes with null values: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandleKeepNull} +~ db._create("example"); +~ var myid = db.example.insert({_key: "19988371"}); + db.example.insert({"a" : 1}); +|db.example.update("example/19988371", + { "b" : null, "c" : null, "d" : 3 }); + db.example.document("example/19988371"); + db.example.update("example/19988371", { "a" : null }, false, false); + db.example.document("example/19988371"); +| db.example.update("example/19988371", + { "b" : null, "c": null, "d" : null }, false, false); + db.example.document("example/19988371"); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Patching array values: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionUpdateHandleArray} +~ db._create("example"); +~ var myid = db.example.insert({_key: "20774803"}); +| db.example.insert({"a" : { "one" : 1, "two" : 2, "three" : 3 }, + "b" : { }}); +| db.example.update("example/20774803", {"a" : { "four" : 4 }, + "b" : { "b1" : 1 }}); + db.example.document("example/20774803"); +| db.example.update("example/20774803", { "a" : { "one" : null }, +| "b" : null }, + false, false); + db.example.document("example/20774803"); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsCollectionUpdateByExample.md b/Documentation/DocuBlocks/documentsCollectionUpdateByExample.md index 4c41beaccd..3a46b5c32a 100644 --- a/Documentation/DocuBlocks/documentsCollectionUpdateByExample.md +++ b/Documentation/DocuBlocks/documentsCollectionUpdateByExample.md @@ -1,60 +1,59 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsCollectionUpdateByExample -/// @brief partially updates documents matching an example -/// `collection.updateByExample(example, newValue)` -/// -/// Partially updates all documents matching an example with a new document body. -/// Specific attributes in the document body of each document matching the -/// *example* will be updated with the values from *newValue*. -/// The document meta-attributes such as *_id*, *_key*, *_from*, -/// *_to* cannot be updated. -/// -/// Partial update could also be used to append new fields, -/// if there were no old field with same name. -/// -/// `collection.updateByExample(document, newValue, keepNull, waitForSync)` -/// -/// The optional *keepNull* parameter can be used to modify the behavior when -/// handling *null* values. Normally, *null* values are stored in the -/// database. By setting the *keepNull* parameter to *false*, this behavior -/// can be changed so that all attributes in *data* with *null* values will -/// be removed from the target document. -/// -/// The optional *waitForSync* parameter can be used to force synchronization -/// of the document replacement operation to disk even in case that the -/// *waitForSync* flag had been disabled for the entire collection. Thus, -/// the *waitForSync* parameter can be used to force synchronization of just -/// specific operations. To use this, set the *waitForSync* parameter to -/// *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// `collection.updateByExample(document, newValue, keepNull, waitForSync, limit)` -/// -/// The optional *limit* parameter can be used to restrict the number of -/// updates to the specified value. If *limit* is specified but less than -/// the number of documents in the collection, it is undefined which documents are -/// updated. -/// -/// `collection.updateByExample(document, newValue, options)` -/// -/// Using this variant, the options for the operation can be passed using -/// an object with the following sub-attributes: -/// - *keepNull* -/// - *waitForSync* -/// - *limit* -/// - *mergeObjects* -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{012_documentsCollectionUpdateByExample} -/// ~ db._create("example"); -/// db.example.save({ Hello : "world", foo : "bar" }); -/// db.example.updateByExample({ Hello: "world" }, { Hello: "foo", World: "bar" }, false); -/// db.example.byExample({ Hello: "foo" }).toArray() -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief partially updates documents matching an example +`collection.updateByExample(example, newValue)` + +Partially updates all documents matching an example with a new document body. +Specific attributes in the document body of each document matching the +*example* will be updated with the values from *newValue*. +The document meta-attributes such as *_id*, *_key*, *_from*, +*_to* cannot be updated. + +Partial update could also be used to append new fields, +if there were no old field with same name. + +`collection.updateByExample(document, newValue, keepNull, waitForSync)` + +The optional *keepNull* parameter can be used to modify the behavior when +handling *null* values. Normally, *null* values are stored in the +database. By setting the *keepNull* parameter to *false*, this behavior +can be changed so that all attributes in *data* with *null* values will +be removed from the target document. + +The optional *waitForSync* parameter can be used to force synchronization +of the document replacement operation to disk even in case that the +*waitForSync* flag had been disabled for the entire collection. Thus, +the *waitForSync* parameter can be used to force synchronization of just +specific operations. To use this, set the *waitForSync* parameter to +*true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +`collection.updateByExample(document, newValue, keepNull, waitForSync, limit)` + +The optional *limit* parameter can be used to restrict the number of +updates to the specified value. If *limit* is specified but less than +the number of documents in the collection, it is undefined which documents are +updated. + +`collection.updateByExample(document, newValue, options)` + +Using this variant, the options for the operation can be passed using +an object with the following sub-attributes: +- *keepNull* +- *waitForSync* +- *limit* +- *mergeObjects* + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{012_documentsCollectionUpdateByExample} +~ db._create("example"); + db.example.save({ Hello : "world", foo : "bar" }); + db.example.updateByExample({ Hello: "world" }, { Hello: "foo", World: "bar" }, false); + db.example.byExample({ Hello: "foo" }).toArray() +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/documentsDocumentExists.md b/Documentation/DocuBlocks/documentsDocumentExists.md index c3e64f80c2..2e85ce9956 100644 --- a/Documentation/DocuBlocks/documentsDocumentExists.md +++ b/Documentation/DocuBlocks/documentsDocumentExists.md @@ -1,20 +1,19 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsDocumentExists -/// @brief checks whether a document exists -/// `db._exists(document)` -/// -/// This method determines whether a document exists given its identifier. -/// Instead of returning the found document or an error, this method will -/// return either *true* or *false*. It can thus be used -/// for easy existence checks. -/// -/// No error will be thrown if the sought document or collection does not -/// exist. -/// Still this method will throw an error if used improperly, e.g. when called -/// with a non-document handle. -/// -/// `db._exists(document-handle)` -/// -/// As before, but instead of a document a document-handle can be passed. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief checks whether a document exists +`db._exists(document)` + +This method determines whether a document exists given its identifier. +Instead of returning the found document or an error, this method will +return either *true* or *false*. It can thus be used +for easy existence checks. + +No error will be thrown if the sought document or collection does not +exist. +Still this method will throw an error if used improperly, e.g. when called +with a non-document handle. + +`db._exists(document-handle)` + +As before, but instead of a document a document-handle can be passed. + diff --git a/Documentation/DocuBlocks/documentsDocumentName.md b/Documentation/DocuBlocks/documentsDocumentName.md index 233de98dff..b84b9bacca 100644 --- a/Documentation/DocuBlocks/documentsDocumentName.md +++ b/Documentation/DocuBlocks/documentsDocumentName.md @@ -1,36 +1,35 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsDocumentName -/// @brief looks up a document and returns it -/// `db._document(document)` -/// -/// This method finds a document given its identifier. It returns the document -/// if the document exists. An error is thrown if no document with the given -/// identifier exists, or if the specified *_rev* value does not match the -/// current revision of the document. -/// -/// **Note**: If the method is executed on the arangod server (e.g. from -/// inside a Foxx application), an immutable document object will be returned -/// for performance reasons. It is not possible to change attributes of this -/// immutable object. To update or patch the returned document, it needs to be -/// cloned/copied into a regular JavaScript object first. This is not necessary -/// if the *_document* method is called from out of arangosh or from any -/// other client. -/// -/// `db._document(document-handle)` -/// -/// As before. Instead of document a *document-handle* can be passed as -/// first argument. -/// -/// @EXAMPLES -/// -/// Returns the document: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsDocumentName} -/// ~ db._create("example"); -/// ~ var myid = db.example.insert({_key: "12345"}); -/// db._document("example/12345"); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief looks up a document and returns it +`db._document(document)` + +This method finds a document given its identifier. It returns the document +if the document exists. An error is thrown if no document with the given +identifier exists, or if the specified *_rev* value does not match the +current revision of the document. + +**Note**: If the method is executed on the arangod server (e.g. from +inside a Foxx application), an immutable document object will be returned +for performance reasons. It is not possible to change attributes of this +immutable object. To update or patch the returned document, it needs to be +cloned/copied into a regular JavaScript object first. This is not necessary +if the *_document* method is called from out of arangosh or from any +other client. + +`db._document(document-handle)` + +As before. Instead of document a *document-handle* can be passed as +first argument. + +@EXAMPLES + +Returns the document: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsDocumentName} +~ db._create("example"); +~ var myid = db.example.insert({_key: "12345"}); + db._document("example/12345"); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsDocumentRemove.md b/Documentation/DocuBlocks/documentsDocumentRemove.md index ea9695454d..8a324e0090 100644 --- a/Documentation/DocuBlocks/documentsDocumentRemove.md +++ b/Documentation/DocuBlocks/documentsDocumentRemove.md @@ -1,70 +1,69 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsDocumentRemove -/// @brief removes a document -/// `db._remove(document)` -/// -/// Removes a document. If there is revision mismatch, then an error is thrown. -/// -/// `db._remove(document, true)` -/// -/// Removes a document. If there is revision mismatch, then mismatch is ignored -/// and document is deleted. The function returns *true* if the document -/// existed and was deleted. It returns *false*, if the document was already -/// deleted. -/// -/// `db._remove(document, true, waitForSync)` or -/// `db._remove(document, {overwrite: true or false, waitForSync: true or false})` -/// -/// The optional *waitForSync* parameter can be used to force synchronization -/// of the document deletion operation to disk even in case that the -/// *waitForSync* flag had been disabled for the entire collection. Thus, -/// the *waitForSync* parameter can be used to force synchronization of just -/// specific operations. To use this, set the *waitForSync* parameter to -/// *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// `db._remove(document-handle, data)` -/// -/// As before. Instead of document a *document-handle* can be passed as first -/// argument. -/// -/// @EXAMPLES -/// -/// Remove a document: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionRemove} -/// ~ db._create("example"); -/// a1 = db.example.insert({ a : 1 }); -/// db._remove(a1); -/// db._remove(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); -/// db._remove(a1, true); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Remove a document with a conflict: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionRemoveConflict} -/// ~ db._create("example"); -/// a1 = db.example.insert({ a : 1 }); -/// a2 = db._replace(a1, { a : 2 }); -/// db._remove(a1); // xpError(ERROR_ARANGO_CONFLICT) -/// db._remove(a1, true); -/// db._document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND) -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// Remove a document using new signature: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionRemoveSignature} -/// ~ db._create("example"); -/// db.example.insert({ a: 1 } ); -/// | db.example.remove("example/11265325374", -/// { overwrite: true, waitForSync: false}) -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief removes a document +`db._remove(document)` + +Removes a document. If there is revision mismatch, then an error is thrown. + +`db._remove(document, true)` + +Removes a document. If there is revision mismatch, then mismatch is ignored +and document is deleted. The function returns *true* if the document +existed and was deleted. It returns *false*, if the document was already +deleted. + +`db._remove(document, true, waitForSync)` or +`db._remove(document, {overwrite: true or false, waitForSync: true or false})` + +The optional *waitForSync* parameter can be used to force synchronization +of the document deletion operation to disk even in case that the +*waitForSync* flag had been disabled for the entire collection. Thus, +the *waitForSync* parameter can be used to force synchronization of just +specific operations. To use this, set the *waitForSync* parameter to +*true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +`db._remove(document-handle, data)` + +As before. Instead of document a *document-handle* can be passed as first +argument. + +@EXAMPLES + +Remove a document: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionRemove} +~ db._create("example"); + a1 = db.example.insert({ a : 1 }); + db._remove(a1); + db._remove(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND); + db._remove(a1, true); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Remove a document with a conflict: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionRemoveConflict} +~ db._create("example"); + a1 = db.example.insert({ a : 1 }); + a2 = db._replace(a1, { a : 2 }); + db._remove(a1); // xpError(ERROR_ARANGO_CONFLICT) + db._remove(a1, true); + db._document(a1); // xpError(ERROR_ARANGO_DOCUMENT_NOT_FOUND) +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + +Remove a document using new signature: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsCollectionRemoveSignature} +~ db._create("example"); + db.example.insert({ a: 1 } ); +| db.example.remove("example/11265325374", + { overwrite: true, waitForSync: false}) +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsDocumentReplace.md b/Documentation/DocuBlocks/documentsDocumentReplace.md index 287cafb28f..d02f9a3b7e 100644 --- a/Documentation/DocuBlocks/documentsDocumentReplace.md +++ b/Documentation/DocuBlocks/documentsDocumentReplace.md @@ -1,51 +1,50 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsDocumentReplace -/// @brief replaces a document -/// `db._replace(document, data)` -/// -/// The method returns a document with the attributes *_id*, *_rev* and -/// *_oldRev*. The attribute *_id* contains the document handle of the -/// updated document, the attribute *_rev* contains the document revision of -/// the updated document, the attribute *_oldRev* contains the revision of -/// the old (now replaced) document. -/// -/// If there is a conflict, i. e. if the revision of the *document* does not -/// match the revision in the collection, then an error is thrown. -/// -/// `db._replace(document, data, true)` -/// -/// As before, but in case of a conflict, the conflict is ignored and the old -/// document is overwritten. -/// -/// `db._replace(document, data, true, waitForSync)` -/// -/// The optional *waitForSync* parameter can be used to force -/// synchronization of the document replacement operation to disk even in case -/// that the *waitForSync* flag had been disabled for the entire collection. -/// Thus, the *waitForSync* parameter can be used to force synchronization -/// of just specific operations. To use this, set the *waitForSync* parameter -/// to *true*. If the *waitForSync* parameter is not specified or set to -/// *false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// `db._replace(document-handle, data)` -/// -/// As before. Instead of document a *document-handle* can be passed as -/// first argument. -/// -/// @EXAMPLES -/// -/// Create and replace a document: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentsDocumentReplace} -/// ~ db._create("example"); -/// a1 = db.example.insert({ a : 1 }); -/// a2 = db._replace(a1, { a : 2 }); -/// a3 = db._replace(a1, { a : 3 }); // xpError(ERROR_ARANGO_CONFLICT); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief replaces a document +`db._replace(document, data)` + +The method returns a document with the attributes *_id*, *_rev* and +*_oldRev*. The attribute *_id* contains the document handle of the +updated document, the attribute *_rev* contains the document revision of +the updated document, the attribute *_oldRev* contains the revision of +the old (now replaced) document. + +If there is a conflict, i. e. if the revision of the *document* does not +match the revision in the collection, then an error is thrown. + +`db._replace(document, data, true)` + +As before, but in case of a conflict, the conflict is ignored and the old +document is overwritten. + +`db._replace(document, data, true, waitForSync)` + +The optional *waitForSync* parameter can be used to force +synchronization of the document replacement operation to disk even in case +that the *waitForSync* flag had been disabled for the entire collection. +Thus, the *waitForSync* parameter can be used to force synchronization +of just specific operations. To use this, set the *waitForSync* parameter +to *true*. If the *waitForSync* parameter is not specified or set to +*false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +`db._replace(document-handle, data)` + +As before. Instead of document a *document-handle* can be passed as +first argument. + +@EXAMPLES + +Create and replace a document: + +@EXAMPLE_ARANGOSH_OUTPUT{documentsDocumentReplace} +~ db._create("example"); + a1 = db.example.insert({ a : 1 }); + a2 = db._replace(a1, { a : 2 }); + a3 = db._replace(a1, { a : 3 }); // xpError(ERROR_ARANGO_CONFLICT); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/documentsDocumentUpdate.md b/Documentation/DocuBlocks/documentsDocumentUpdate.md index bc3a888aa9..67729e116c 100644 --- a/Documentation/DocuBlocks/documentsDocumentUpdate.md +++ b/Documentation/DocuBlocks/documentsDocumentUpdate.md @@ -1,59 +1,58 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock documentsDocumentUpdate -/// @brief update a document -/// `db._update(document, data, overwrite, keepNull, waitForSync)` -/// -/// Updates an existing *document*. The *document* must be a document in -/// the current collection. This document is then patched with the -/// *data* given as second argument. The optional *overwrite* parameter can -/// be used to control the behavior in case of version conflicts (see below). -/// The optional *keepNull* parameter can be used to modify the behavior when -/// handling *null* values. Normally, *null* values are stored in the -/// database. By setting the *keepNull* parameter to *false*, this behavior -/// can be changed so that all attributes in *data* with *null* values will -/// be removed from the target document. -/// -/// The optional *waitForSync* parameter can be used to force -/// synchronization of the document update operation to disk even in case -/// that the *waitForSync* flag had been disabled for the entire collection. -/// Thus, the *waitForSync* parameter can be used to force synchronization -/// of just specific operations. To use this, set the *waitForSync* parameter -/// to *true*. If the *waitForSync* parameter is not specified or set to -/// false*, then the collection's default *waitForSync* behavior is -/// applied. The *waitForSync* parameter cannot be used to disable -/// synchronization for collections that have a default *waitForSync* value -/// of *true*. -/// -/// The method returns a document with the attributes *_id*, *_rev* and -/// *_oldRev*. The attribute *_id* contains the document handle of the -/// updated document, the attribute *_rev* contains the document revision of -/// the updated document, the attribute *_oldRev* contains the revision of -/// the old (now replaced) document. -/// -/// If there is a conflict, i. e. if the revision of the *document* does not -/// match the revision in the collection, then an error is thrown. -/// -/// `db._update(document, data, true)` -/// -/// As before, but in case of a conflict, the conflict is ignored and the old -/// document is overwritten. -/// -/// `db._update(document-handle, data)` -/// -/// As before. Instead of document a *document-handle* can be passed as -/// first argument. -/// -/// @EXAMPLES -/// -/// Create and update a document: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{documentDocumentUpdate} -/// ~ db._create("example"); -/// a1 = db.example.insert({ a : 1 }); -/// a2 = db._update(a1, { b : 2 }); -/// a3 = db._update(a1, { c : 3 }); // xpError(ERROR_ARANGO_CONFLICT); -/// ~ db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief update a document +`db._update(document, data, overwrite, keepNull, waitForSync)` + +Updates an existing *document*. The *document* must be a document in +the current collection. This document is then patched with the +*data* given as second argument. The optional *overwrite* parameter can +be used to control the behavior in case of version conflicts (see below). +The optional *keepNull* parameter can be used to modify the behavior when +handling *null* values. Normally, *null* values are stored in the +database. By setting the *keepNull* parameter to *false*, this behavior +can be changed so that all attributes in *data* with *null* values will +be removed from the target document. + +The optional *waitForSync* parameter can be used to force +synchronization of the document update operation to disk even in case +that the *waitForSync* flag had been disabled for the entire collection. +Thus, the *waitForSync* parameter can be used to force synchronization +of just specific operations. To use this, set the *waitForSync* parameter +to *true*. If the *waitForSync* parameter is not specified or set to +false*, then the collection's default *waitForSync* behavior is +applied. The *waitForSync* parameter cannot be used to disable +synchronization for collections that have a default *waitForSync* value +of *true*. + +The method returns a document with the attributes *_id*, *_rev* and +*_oldRev*. The attribute *_id* contains the document handle of the +updated document, the attribute *_rev* contains the document revision of +the updated document, the attribute *_oldRev* contains the revision of +the old (now replaced) document. + +If there is a conflict, i. e. if the revision of the *document* does not +match the revision in the collection, then an error is thrown. + +`db._update(document, data, true)` + +As before, but in case of a conflict, the conflict is ignored and the old +document is overwritten. + +`db._update(document-handle, data)` + +As before. Instead of document a *document-handle* can be passed as +first argument. + +@EXAMPLES + +Create and update a document: + +@EXAMPLE_ARANGOSH_OUTPUT{documentDocumentUpdate} +~ db._create("example"); + a1 = db.example.insert({ a : 1 }); + a2 = db._update(a1, { b : 2 }); + a3 = db._update(a1, { c : 3 }); // xpError(ERROR_ARANGO_CONFLICT); +~ db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/dropIndex.md b/Documentation/DocuBlocks/dropIndex.md index 415b1f3048..d42c5f0b6c 100644 --- a/Documentation/DocuBlocks/dropIndex.md +++ b/Documentation/DocuBlocks/dropIndex.md @@ -1,25 +1,24 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock dropIndex -/// @brief drops an index -/// `db._dropIndex(index)` -/// -/// Drops the *index*. If the index does not exist, then *false* is -/// returned. If the index existed and was dropped, then *true* is -/// returned. -/// -/// `db._dropIndex(index-handle)` -/// -/// Drops the index with *index-handle*. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{dropIndex} -/// ~db._create("example"); -/// db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] }); -/// var indexInfo = db.example.getIndexes(); -/// indexInfo; -/// db._dropIndex(indexInfo[0]) -/// db._dropIndex(indexInfo[1].id) -/// indexInfo = db.example.getIndexes(); -/// ~db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief drops an index +`db._dropIndex(index)` + +Drops the *index*. If the index does not exist, then *false* is +returned. If the index existed and was dropped, then *true* is +returned. + +`db._dropIndex(index-handle)` + +Drops the index with *index-handle*. + +@EXAMPLE_ARANGOSH_OUTPUT{dropIndex} +~db._create("example"); +db.example.ensureIndex({ type: "skiplist", fields: [ "a", "b" ] }); +var indexInfo = db.example.getIndexes(); +indexInfo; +db._dropIndex(indexInfo[0]) +db._dropIndex(indexInfo[1].id) +indexInfo = db.example.getIndexes(); +~db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/edgeCollectionEdges.md b/Documentation/DocuBlocks/edgeCollectionEdges.md index 3caa6360ef..4bd4858fcd 100644 --- a/Documentation/DocuBlocks/edgeCollectionEdges.md +++ b/Documentation/DocuBlocks/edgeCollectionEdges.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock edgeCollectionEdges -/// @brief selects all edges for a set of vertices -/// `edge-collection.edges(vertex)` -/// -/// The *edges* operator finds all edges starting from (outbound) or ending -/// in (inbound) *vertex*. -/// -/// `edge-collection.edges(vertices)` -/// -/// The *edges* operator finds all edges starting from (outbound) or ending -/// in (inbound) a document from *vertices*, which must a list of documents -/// or document handles. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_02_Relation} -/// db._create("vertex"); -/// db._createEdgeCollection("relation"); -/// ~ var myGraph = {}; -/// myGraph.v1 = db.vertex.insert({ name : "vertex 1" }); -/// myGraph.v2 = db.vertex.insert({ name : "vertex 2" }); -/// | myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2, -/// { label : "knows"}); -/// db._document(myGraph.e1); -/// db.relation.edges(myGraph.e1._id); -/// ~ db._drop("relation"); -/// ~ db._drop("vertex"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief selects all edges for a set of vertices +`edge-collection.edges(vertex)` + +The *edges* operator finds all edges starting from (outbound) or ending +in (inbound) *vertex*. + +`edge-collection.edges(vertices)` + +The *edges* operator finds all edges starting from (outbound) or ending +in (inbound) a document from *vertices*, which must a list of documents +or document handles. + +@EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_02_Relation} + db._create("vertex"); + db._createEdgeCollection("relation"); +~ var myGraph = {}; + myGraph.v1 = db.vertex.insert({ name : "vertex 1" }); + myGraph.v2 = db.vertex.insert({ name : "vertex 2" }); +| myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2, + { label : "knows"}); + db._document(myGraph.e1); + db.relation.edges(myGraph.e1._id); +~ db._drop("relation"); +~ db._drop("vertex"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/edgeCollectionInEdges.md b/Documentation/DocuBlocks/edgeCollectionInEdges.md index 164bcf771d..9b538eeee7 100644 --- a/Documentation/DocuBlocks/edgeCollectionInEdges.md +++ b/Documentation/DocuBlocks/edgeCollectionInEdges.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock edgeCollectionInEdges -/// @brief selects all inbound edges -/// `edge-collection.inEdges(vertex)` -/// -/// The *edges* operator finds all edges ending in (inbound) *vertex*. -/// -/// `edge-collection.inEdges(vertices)` -/// -/// The *edges* operator finds all edges ending in (inbound) a document from -/// *vertices*, which must a list of documents or document handles. -/// -/// @EXAMPLES -/// @EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_02_inEdges} -/// db._create("vertex"); -/// db._createEdgeCollection("relation"); -/// ~ var myGraph = {}; -/// myGraph.v1 = db.vertex.insert({ name : "vertex 1" }); -/// myGraph.v2 = db.vertex.insert({ name : "vertex 2" }); -/// | myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2, -/// { label : "knows"}); -/// db._document(myGraph.e1); -/// db.relation.inEdges(myGraph.v1._id); -/// db.relation.inEdges(myGraph.v2._id); -/// ~ db._drop("relation"); -/// ~ db._drop("vertex"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief selects all inbound edges +`edge-collection.inEdges(vertex)` + +The *edges* operator finds all edges ending in (inbound) *vertex*. + +`edge-collection.inEdges(vertices)` + +The *edges* operator finds all edges ending in (inbound) a document from +*vertices*, which must a list of documents or document handles. + +@EXAMPLES +@EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_02_inEdges} + db._create("vertex"); + db._createEdgeCollection("relation"); +~ var myGraph = {}; + myGraph.v1 = db.vertex.insert({ name : "vertex 1" }); + myGraph.v2 = db.vertex.insert({ name : "vertex 2" }); +| myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2, + { label : "knows"}); + db._document(myGraph.e1); + db.relation.inEdges(myGraph.v1._id); + db.relation.inEdges(myGraph.v2._id); +~ db._drop("relation"); +~ db._drop("vertex"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/edgeCollectionOutEdges.md b/Documentation/DocuBlocks/edgeCollectionOutEdges.md index c6f97c42c5..9032a45d29 100644 --- a/Documentation/DocuBlocks/edgeCollectionOutEdges.md +++ b/Documentation/DocuBlocks/edgeCollectionOutEdges.md @@ -1,31 +1,30 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock edgeCollectionOutEdges -/// @brief selects all outbound edges -/// `edge-collection.outEdges(vertex)` -/// -/// The *edges* operator finds all edges starting from (outbound) -/// *vertices*. -/// -/// `edge-collection.outEdges(vertices)` -/// -/// The *edges* operator finds all edges starting from (outbound) a document -/// from *vertices*, which must a list of documents or document handles. -/// -/// @EXAMPLES -/// @EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_02_outEdges} -/// db._create("vertex"); -/// db._createEdgeCollection("relation"); -/// ~ var myGraph = {}; -/// myGraph.v1 = db.vertex.insert({ name : "vertex 1" }); -/// myGraph.v2 = db.vertex.insert({ name : "vertex 2" }); -/// | myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2, -/// { label : "knows"}); -/// db._document(myGraph.e1); -/// db.relation.outEdges(myGraph.v1._id); -/// db.relation.outEdges(myGraph.v2._id); -/// ~ db._drop("relation"); -/// ~ db._drop("vertex"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief selects all outbound edges +`edge-collection.outEdges(vertex)` + +The *edges* operator finds all edges starting from (outbound) +*vertices*. + +`edge-collection.outEdges(vertices)` + +The *edges* operator finds all edges starting from (outbound) a document +from *vertices*, which must a list of documents or document handles. + +@EXAMPLES +@EXAMPLE_ARANGOSH_OUTPUT{EDGCOL_02_outEdges} + db._create("vertex"); + db._createEdgeCollection("relation"); +~ var myGraph = {}; + myGraph.v1 = db.vertex.insert({ name : "vertex 1" }); + myGraph.v2 = db.vertex.insert({ name : "vertex 2" }); +| myGraph.e1 = db.relation.insert(myGraph.v1, myGraph.v2, + { label : "knows"}); + db._document(myGraph.e1); + db.relation.outEdges(myGraph.v1._id); + db.relation.outEdges(myGraph.v2._id); +~ db._drop("relation"); +~ db._drop("vertex"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/edgeSetProperty.md b/Documentation/DocuBlocks/edgeSetProperty.md index 2dbf72cebf..886bbd895c 100644 --- a/Documentation/DocuBlocks/edgeSetProperty.md +++ b/Documentation/DocuBlocks/edgeSetProperty.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock edgeSetProperty -/// -/// `edge.setProperty(name, value)` -/// -/// Changes or sets the property *name* an *edges* to *value*. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + + +`edge.setProperty(name, value)` + +Changes or sets the property *name* an *edges* to *value*. + + diff --git a/Documentation/DocuBlocks/ensureFulltextIndex.md b/Documentation/DocuBlocks/ensureFulltextIndex.md index 51e2f9da5b..dca713cd78 100644 --- a/Documentation/DocuBlocks/ensureFulltextIndex.md +++ b/Documentation/DocuBlocks/ensureFulltextIndex.md @@ -1,38 +1,37 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock ensureFulltextIndex -/// @brief ensures that a fulltext index exists -/// `collection.ensureIndex({ type: "fulltext", fields: [ "field" ], minLength: minLength })` -/// -/// Creates a fulltext index on all documents on attribute *field*. -/// -/// Fulltext indexes are implicitly sparse: all documents which do not have -/// the specified *field* attribute or that have a non-qualifying value in their -/// *field* attribute will be ignored for indexing. -/// -/// Only a single attribute can be indexed. Specifying multiple attributes is -/// unsupported. -/// -/// The minimum length of words that are indexed can be specified via the -/// *minLength* parameter. Words shorter than minLength characters will -/// not be indexed. *minLength* has a default value of 2, but this value might -/// be changed in future versions of ArangoDB. It is thus recommended to explicitly -/// specify this value. -/// -/// In case that the index was successfully created, an object with the index -/// details is returned. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{ensureFulltextIndex} -/// ~db._create("example"); -/// db.example.ensureIndex({ type: "fulltext", fields: [ "text" ], minLength: 3 }); -/// db.example.save({ text : "the quick brown", b : { c : 1 } }); -/// db.example.save({ text : "quick brown fox", b : { c : 2 } }); -/// db.example.save({ text : "brown fox jums", b : { c : 3 } }); -/// db.example.save({ text : "fox jumps over", b : { c : 4 } }); -/// db.example.save({ text : "jumps over the", b : { c : 5 } }); -/// db.example.save({ text : "over the lazy", b : { c : 6 } }); -/// db.example.save({ text : "the lazy dog", b : { c : 7 } }); -/// db._query("FOR document IN FULLTEXT(example, 'text', 'the') RETURN document"); -/// ~db._drop("example"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a fulltext index exists +`collection.ensureIndex({ type: "fulltext", fields: [ "field" ], minLength: minLength })` + +Creates a fulltext index on all documents on attribute *field*. + +Fulltext indexes are implicitly sparse: all documents which do not have +the specified *field* attribute or that have a non-qualifying value in their +*field* attribute will be ignored for indexing. + +Only a single attribute can be indexed. Specifying multiple attributes is +unsupported. + +The minimum length of words that are indexed can be specified via the +*minLength* parameter. Words shorter than minLength characters will +not be indexed. *minLength* has a default value of 2, but this value might +be changed in future versions of ArangoDB. It is thus recommended to explicitly +specify this value. + +In case that the index was successfully created, an object with the index +details is returned. + +@EXAMPLE_ARANGOSH_OUTPUT{ensureFulltextIndex} +~db._create("example"); +db.example.ensureIndex({ type: "fulltext", fields: [ "text" ], minLength: 3 }); +db.example.save({ text : "the quick brown", b : { c : 1 } }); +db.example.save({ text : "quick brown fox", b : { c : 2 } }); +db.example.save({ text : "brown fox jums", b : { c : 3 } }); +db.example.save({ text : "fox jumps over", b : { c : 4 } }); +db.example.save({ text : "jumps over the", b : { c : 5 } }); +db.example.save({ text : "over the lazy", b : { c : 6 } }); +db.example.save({ text : "the lazy dog", b : { c : 7 } }); +db._query("FOR document IN FULLTEXT(example, 'text', 'the') RETURN document"); +~db._drop("example"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/ensureHashIndex.md b/Documentation/DocuBlocks/ensureHashIndex.md index 9b7cab2e40..0f02bed012 100644 --- a/Documentation/DocuBlocks/ensureHashIndex.md +++ b/Documentation/DocuBlocks/ensureHashIndex.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock ensureHashIndex -/// @brief ensures that a non-unique hash index exists -/// `collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ] })` -/// -/// Creates a non-unique hash index on all documents using *field1*, ... *fieldn* -/// as attribute paths. At least one attribute path has to be given. -/// The index will be non-sparse by default. -/// -/// To create a sparse unique index, set the *sparse* attribute to `true`: -/// -/// `collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ], sparse: true })` -/// -/// In case that the index was successfully created, an object with the index -/// details, including the index-identifier, is returned. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{ensureHashIndex} -/// ~db._create("test"); -/// db.test.ensureIndex({ type: "hash", fields: [ "a" ] }); -/// db.test.save({ a : 1 }); -/// db.test.save({ a : 1 }); -/// db.test.save({ a : null }); -/// ~db._drop("test"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a non-unique hash index exists +`collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ] })` + +Creates a non-unique hash index on all documents using *field1*, ... *fieldn* +as attribute paths. At least one attribute path has to be given. +The index will be non-sparse by default. + +To create a sparse unique index, set the *sparse* attribute to `true`: + +`collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ], sparse: true })` + +In case that the index was successfully created, an object with the index +details, including the index-identifier, is returned. + +@EXAMPLE_ARANGOSH_OUTPUT{ensureHashIndex} +~db._create("test"); +db.test.ensureIndex({ type: "hash", fields: [ "a" ] }); +db.test.save({ a : 1 }); +db.test.save({ a : 1 }); +db.test.save({ a : null }); +~db._drop("test"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/ensureSkiplist.md b/Documentation/DocuBlocks/ensureSkiplist.md index c2a77708ae..e2e4933d15 100644 --- a/Documentation/DocuBlocks/ensureSkiplist.md +++ b/Documentation/DocuBlocks/ensureSkiplist.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock ensureSkiplist -/// @brief ensures that a non-unique skiplist index exists -/// `collection.ensureIndex({ type: "skiplist", fields: [ "field1", ..., "fieldn" ] })` -/// -/// Creates a non-unique skiplist index on all documents using *field1*, ... -/// *fieldn* as attribute paths. At least one attribute path has to be given. -/// The index will be non-sparse by default. -/// -/// To create a sparse unique index, set the *sparse* attribute to `true`. -/// -/// In case that the index was successfully created, an object with the index -/// details, including the index-identifier, is returned. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{ensureSkiplist} -/// ~db._create("names"); -/// db.names.ensureIndex({ type: "skiplist", fields: [ "first" ] }); -/// db.names.save({ "first" : "Tim" }); -/// db.names.save({ "first" : "Tom" }); -/// db.names.save({ "first" : "John" }); -/// db.names.save({ "first" : "Tim" }); -/// db.names.save({ "first" : "Tom" }); -/// ~db._drop("names"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a non-unique skiplist index exists +`collection.ensureIndex({ type: "skiplist", fields: [ "field1", ..., "fieldn" ] })` + +Creates a non-unique skiplist index on all documents using *field1*, ... +*fieldn* as attribute paths. At least one attribute path has to be given. +The index will be non-sparse by default. + +To create a sparse unique index, set the *sparse* attribute to `true`. + +In case that the index was successfully created, an object with the index +details, including the index-identifier, is returned. + +@EXAMPLE_ARANGOSH_OUTPUT{ensureSkiplist} +~db._create("names"); +db.names.ensureIndex({ type: "skiplist", fields: [ "first" ] }); +db.names.save({ "first" : "Tim" }); +db.names.save({ "first" : "Tom" }); +db.names.save({ "first" : "John" }); +db.names.save({ "first" : "Tim" }); +db.names.save({ "first" : "Tom" }); +~db._drop("names"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/ensureUniqueConstraint.md b/Documentation/DocuBlocks/ensureUniqueConstraint.md index 47fff9323b..b26e7a8977 100644 --- a/Documentation/DocuBlocks/ensureUniqueConstraint.md +++ b/Documentation/DocuBlocks/ensureUniqueConstraint.md @@ -1,41 +1,40 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock ensureUniqueConstraint -/// @brief ensures that a unique constraint exists -/// `collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ], unique: true })` -/// -/// Creates a unique hash index on all documents using *field1*, ... *fieldn* -/// as attribute paths. At least one attribute path has to be given. -/// The index will be non-sparse by default. -/// -/// All documents in the collection must differ in terms of the indexed -/// attributes. Creating a new document or updating an existing document will -/// will fail if the attribute uniqueness is violated. -/// -/// To create a sparse unique index, set the *sparse* attribute to `true`: -/// -/// `collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ], unique: true, sparse: true })` -/// -/// In case that the index was successfully created, the index identifier is returned. -/// -/// Non-existing attributes will default to `null`. -/// In a sparse index all documents will be excluded from the index for which all -/// specified index attributes are `null`. Such documents will not be taken into account -/// for uniqueness checks. -/// -/// In a non-sparse index, **all** documents regardless of `null` - attributes will be -/// indexed and will be taken into account for uniqueness checks. -/// -/// In case that the index was successfully created, an object with the index -/// details, including the index-identifier, is returned. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{ensureUniqueConstraint} -/// ~db._create("test"); -/// db.test.ensureIndex({ type: "hash", fields: [ "a", "b.c" ], unique: true }); -/// db.test.save({ a : 1, b : { c : 1 } }); -/// db.test.save({ a : 1, b : { c : 1 } }); // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) -/// db.test.save({ a : 1, b : { c : null } }); -/// db.test.save({ a : 1 }); // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) -/// ~db._drop("test"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a unique constraint exists +`collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ], unique: true })` + +Creates a unique hash index on all documents using *field1*, ... *fieldn* +as attribute paths. At least one attribute path has to be given. +The index will be non-sparse by default. + +All documents in the collection must differ in terms of the indexed +attributes. Creating a new document or updating an existing document will +will fail if the attribute uniqueness is violated. + +To create a sparse unique index, set the *sparse* attribute to `true`: + +`collection.ensureIndex({ type: "hash", fields: [ "field1", ..., "fieldn" ], unique: true, sparse: true })` + +In case that the index was successfully created, the index identifier is returned. + +Non-existing attributes will default to `null`. +In a sparse index all documents will be excluded from the index for which all +specified index attributes are `null`. Such documents will not be taken into account +for uniqueness checks. + +In a non-sparse index, **all** documents regardless of `null` - attributes will be +indexed and will be taken into account for uniqueness checks. + +In case that the index was successfully created, an object with the index +details, including the index-identifier, is returned. + +@EXAMPLE_ARANGOSH_OUTPUT{ensureUniqueConstraint} +~db._create("test"); +db.test.ensureIndex({ type: "hash", fields: [ "a", "b.c" ], unique: true }); +db.test.save({ a : 1, b : { c : 1 } }); +db.test.save({ a : 1, b : { c : 1 } }); // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) +db.test.save({ a : 1, b : { c : null } }); +db.test.save({ a : 1 }); // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) +~db._drop("test"); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/ensureUniqueSkiplist.md b/Documentation/DocuBlocks/ensureUniqueSkiplist.md index 2bc9257318..a48821155e 100644 --- a/Documentation/DocuBlocks/ensureUniqueSkiplist.md +++ b/Documentation/DocuBlocks/ensureUniqueSkiplist.md @@ -1,51 +1,50 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock ensureUniqueSkiplist -/// @brief ensures that a unique skiplist index exists -/// `collection.ensureIndex({ type: "skiplist", fields: [ "field1", ..., "fieldn" ], unique: true })` -/// -/// Creates a unique skiplist index on all documents using *field1*, ... *fieldn* -/// as attribute paths. At least one attribute path has to be given. The index will -/// be non-sparse by default. -/// -/// All documents in the collection must differ in terms of the indexed -/// attributes. Creating a new document or updating an existing document will -/// will fail if the attribute uniqueness is violated. -/// -/// To create a sparse unique index, set the *sparse* attribute to `true`: -/// -/// `collection.ensureIndex({ type: "skiplist", fields: [ "field1", ..., "fieldn" ], unique: true, sparse: true })` -/// -/// In a sparse index all documents will be excluded from the index that do not -/// contain at least one of the specified index attributes or that have a value -/// of `null` in any of the specified index attributes. Such documents will -/// not be indexed, and not be taken into account for uniqueness checks. -/// -/// In a non-sparse index, these documents will be indexed (for non-present -/// indexed attributes, a value of `null` will be used) and will be taken into -/// account for uniqueness checks. -/// -/// In case that the index was successfully created, an object with the index -/// details, including the index-identifier, is returned. -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{ensureUniqueSkiplist} -/// ~db._create("ids"); -/// db.ids.ensureIndex({ type: "skiplist", fields: [ "myId" ], unique: true }); -/// db.ids.save({ "myId": 123 }); -/// db.ids.save({ "myId": 456 }); -/// db.ids.save({ "myId": 789 }); -/// db.ids.save({ "myId": 123 }); // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) -/// ~db._drop("ids"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @EXAMPLE_ARANGOSH_OUTPUT{ensureUniqueSkiplistMultiColmun} -/// ~db._create("ids"); -/// db.ids.ensureIndex({ type: "skiplist", fields: [ "name.first", "name.last" ], unique: true }); -/// db.ids.save({ "name" : { "first" : "hans", "last": "hansen" }}); -/// db.ids.save({ "name" : { "first" : "jens", "last": "jensen" }}); -/// db.ids.save({ "name" : { "first" : "hans", "last": "jensen" }}); -/// | db.ids.save({ "name" : { "first" : "hans", "last": "hansen" }}); -/// ~ // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) -/// ~db._drop("ids"); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ensures that a unique skiplist index exists +`collection.ensureIndex({ type: "skiplist", fields: [ "field1", ..., "fieldn" ], unique: true })` + +Creates a unique skiplist index on all documents using *field1*, ... *fieldn* +as attribute paths. At least one attribute path has to be given. The index will +be non-sparse by default. + +All documents in the collection must differ in terms of the indexed +attributes. Creating a new document or updating an existing document will +will fail if the attribute uniqueness is violated. + +To create a sparse unique index, set the *sparse* attribute to `true`: + +`collection.ensureIndex({ type: "skiplist", fields: [ "field1", ..., "fieldn" ], unique: true, sparse: true })` + +In a sparse index all documents will be excluded from the index that do not +contain at least one of the specified index attributes or that have a value +of `null` in any of the specified index attributes. Such documents will +not be indexed, and not be taken into account for uniqueness checks. + +In a non-sparse index, these documents will be indexed (for non-present +indexed attributes, a value of `null` will be used) and will be taken into +account for uniqueness checks. + +In case that the index was successfully created, an object with the index +details, including the index-identifier, is returned. + +@EXAMPLE_ARANGOSH_OUTPUT{ensureUniqueSkiplist} +~db._create("ids"); +db.ids.ensureIndex({ type: "skiplist", fields: [ "myId" ], unique: true }); +db.ids.save({ "myId": 123 }); +db.ids.save({ "myId": 456 }); +db.ids.save({ "myId": 789 }); +db.ids.save({ "myId": 123 }); // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) +~db._drop("ids"); +@END_EXAMPLE_ARANGOSH_OUTPUT +@EXAMPLE_ARANGOSH_OUTPUT{ensureUniqueSkiplistMultiColmun} +~db._create("ids"); +db.ids.ensureIndex({ type: "skiplist", fields: [ "name.first", "name.last" ], unique: true }); +db.ids.save({ "name" : { "first" : "hans", "last": "hansen" }}); +db.ids.save({ "name" : { "first" : "jens", "last": "jensen" }}); +db.ids.save({ "name" : { "first" : "hans", "last": "jensen" }}); +| db.ids.save({ "name" : { "first" : "hans", "last": "hansen" }}); +~ // xpError(ERROR_ARANGO_UNIQUE_CONSTRAINT_VIOLATED) +~db._drop("ids"); +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/executeTransaction.md b/Documentation/DocuBlocks/executeTransaction.md index 8679af9a4f..1a025e2745 100644 --- a/Documentation/DocuBlocks/executeTransaction.md +++ b/Documentation/DocuBlocks/executeTransaction.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock executeTransaction -/// @brief executes a transaction -/// `db._executeTransaction(object)` -/// -/// Executes a server-side transaction, as specified by *object*. -/// -/// *object* must have the following attributes: -/// - *collections*: a sub-object that defines which collections will be -/// used in the transaction. *collections* can have these attributes: -/// - *read*: a single collection or a list of collections that will be -/// used in the transaction in read-only mode -/// - *write*: a single collection or a list of collections that will be -/// used in the transaction in write or read mode. -/// - *action*: a Javascript function or a string with Javascript code -/// containing all the instructions to be executed inside the transaction. -/// If the code runs through successfully, the transaction will be committed -/// at the end. If the code throws an exception, the transaction will be -/// rolled back and all database operations will be rolled back. -/// -/// Additionally, *object* can have the following optional attributes: -/// - *waitForSync*: boolean flag indicating whether the transaction -/// is forced to be synchronous. -/// - *lockTimeout*: a numeric value that can be used to set a timeout for -/// waiting on collection locks. If not specified, a default value will be -/// used. Setting *lockTimeout* to *0* will make ArangoDB not time -/// out waiting for a lock. -/// - *params*: optional arguments passed to the function specified in -/// *action*. -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief executes a transaction +`db._executeTransaction(object)` + +Executes a server-side transaction, as specified by *object*. + +*object* must have the following attributes: +- *collections*: a sub-object that defines which collections will be + used in the transaction. *collections* can have these attributes: + - *read*: a single collection or a list of collections that will be + used in the transaction in read-only mode + - *write*: a single collection or a list of collections that will be + used in the transaction in write or read mode. +- *action*: a Javascript function or a string with Javascript code + containing all the instructions to be executed inside the transaction. + If the code runs through successfully, the transaction will be committed + at the end. If the code throws an exception, the transaction will be + rolled back and all database operations will be rolled back. + +Additionally, *object* can have the following optional attributes: +- *waitForSync*: boolean flag indicating whether the transaction + is forced to be synchronous. +- *lockTimeout*: a numeric value that can be used to set a timeout for + waiting on collection locks. If not specified, a default value will be + used. Setting *lockTimeout* to *0* will make ArangoDB not time + out waiting for a lock. +- *params*: optional arguments passed to the function specified in + *action*. + + diff --git a/Documentation/DocuBlocks/generalHelp.md b/Documentation/DocuBlocks/generalHelp.md index 6ddb03f975..acf2470e8e 100644 --- a/Documentation/DocuBlocks/generalHelp.md +++ b/Documentation/DocuBlocks/generalHelp.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock generalHelp -/// @brief program options -/// `--help` -/// -/// `-h` -/// -/// Prints a list of the most common options available and then -/// exits. In order to see all options use *--help-all*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief program options +`--help` + +`-h` + +Prints a list of the most common options available and then +exits. In order to see all options use *--help-all*. + diff --git a/Documentation/DocuBlocks/generalVersion.md b/Documentation/DocuBlocks/generalVersion.md index e1f0d624c7..91dd2300a9 100644 --- a/Documentation/DocuBlocks/generalVersion.md +++ b/Documentation/DocuBlocks/generalVersion.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock generalVersion -/// @brief version of the application -/// `--version` -/// -/// `-v` -/// -/// Prints the version of the server and exits. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief version of the application +`--version` + +`-v` + +Prints the version of the server and exits. + diff --git a/Documentation/DocuBlocks/indexThreads.md b/Documentation/DocuBlocks/indexThreads.md index 288d4eb28e..b9bc150763 100644 --- a/Documentation/DocuBlocks/indexThreads.md +++ b/Documentation/DocuBlocks/indexThreads.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock indexThreads -/// @brief number of background threads for parallel index creation -/// `--database.index-threads` -/// -/// Specifies the *number* of background threads for index creation. When a -/// collection contains extra indexes other than the primary index, these -/// other -/// indexes can be built by multiple threads in parallel. The index threads -/// are shared among multiple collections and databases. Specifying a value of -/// *0* will turn off parallel building, meaning that indexes for each -/// collection -/// are built sequentially by the thread that opened the collection. -/// If the number of index threads is greater than 1, it will also be used to -/// built the edge index of a collection in parallel (this also requires the -/// edge index in the collection to be split into multiple buckets). -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief number of background threads for parallel index creation +`--database.index-threads` + +Specifies the *number* of background threads for index creation. When a +collection contains extra indexes other than the primary index, these +other +indexes can be built by multiple threads in parallel. The index threads +are shared among multiple collections and databases. Specifying a value of +*0* will turn off parallel building, meaning that indexes for each +collection +are built sequentially by the thread that opened the collection. +If the number of index threads is greater than 1, it will also be used to +built the edge index of a collection in parallel (this also requires the +edge index in the collection to be split into multiple buckets). + diff --git a/Documentation/DocuBlocks/jsGcFrequency.md b/Documentation/DocuBlocks/jsGcFrequency.md index 75de551475..e2a2c259d5 100644 --- a/Documentation/DocuBlocks/jsGcFrequency.md +++ b/Documentation/DocuBlocks/jsGcFrequency.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock jsGcFrequency -/// @brief JavaScript garbage collection frequency (each x seconds) -/// `--javascript.gc-frequency frequency` -/// -/// Specifies the frequency (in seconds) for the automatic garbage collection -/// of -/// JavaScript objects. This setting is useful to have the garbage collection -/// still work in periods with no or little numbers of requests. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief JavaScript garbage collection frequency (each x seconds) +`--javascript.gc-frequency frequency` + +Specifies the frequency (in seconds) for the automatic garbage collection +of +JavaScript objects. This setting is useful to have the garbage collection +still work in periods with no or little numbers of requests. + diff --git a/Documentation/DocuBlocks/jsStartupGcInterval.md b/Documentation/DocuBlocks/jsStartupGcInterval.md index 3659150996..ccaaecfc11 100644 --- a/Documentation/DocuBlocks/jsStartupGcInterval.md +++ b/Documentation/DocuBlocks/jsStartupGcInterval.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock jsStartupGcInterval -/// @brief JavaScript garbage collection interval (each x requests) -/// `--javascript.gc-interval interval` -/// -/// Specifies the interval (approximately in number of requests) that the -/// garbage collection for JavaScript objects will be run in each thread. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief JavaScript garbage collection interval (each x requests) +`--javascript.gc-interval interval` + +Specifies the interval (approximately in number of requests) that the +garbage collection for JavaScript objects will be run in each thread. + diff --git a/Documentation/DocuBlocks/jsV8Options.md b/Documentation/DocuBlocks/jsV8Options.md index 614089670d..fa6c44e95d 100644 --- a/Documentation/DocuBlocks/jsV8Options.md +++ b/Documentation/DocuBlocks/jsV8Options.md @@ -1,35 +1,34 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock jsV8Options -/// @brief optional arguments to pass to v8 -/// `--javascript.v8-options options` -/// -/// Optional arguments to pass to the V8 Javascript engine. The V8 engine will -/// run with default settings unless explicit options are specified using this -/// option. The options passed will be forwarded to the V8 engine which will -/// parse them on its own. Passing invalid options may result in an error -/// being -/// printed on stderr and the option being ignored. -/// -/// Options need to be passed in one string, with V8 option names being -/// prefixed -/// with double dashes. Multiple options need to be separated by whitespace. -/// To get a list of all available V8 options, you can use -/// the value *"--help"* as follows: -/// ``` -/// --javascript.v8-options "--help" -/// ``` -/// -/// Another example of specific V8 options being set at startup: -/// -/// ``` -/// --javascript.v8-options "--harmony --log" -/// ``` -/// -/// Names and features or usable options depend on the version of V8 being -/// used, -/// and might change in the future if a different version of V8 is being used -/// in ArangoDB. Not all options offered by V8 might be sensible to use in the -/// context of ArangoDB. Use the specific options only if you are sure that -/// they are not harmful for the regular database operation. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief optional arguments to pass to v8 +`--javascript.v8-options options` + +Optional arguments to pass to the V8 Javascript engine. The V8 engine will +run with default settings unless explicit options are specified using this +option. The options passed will be forwarded to the V8 engine which will +parse them on its own. Passing invalid options may result in an error +being +printed on stderr and the option being ignored. + +Options need to be passed in one string, with V8 option names being +prefixed +with double dashes. Multiple options need to be separated by whitespace. +To get a list of all available V8 options, you can use +the value *"--help"* as follows: +``` +--javascript.v8-options "--help" +``` + +Another example of specific V8 options being set at startup: + +``` +--javascript.v8-options "--harmony --log" +``` + +Names and features or usable options depend on the version of V8 being +used, +and might change in the future if a different version of V8 is being used +in ArangoDB. Not all options offered by V8 might be sensible to use in the +context of ArangoDB. Use the specific options only if you are sure that +they are not harmful for the regular database operation. + diff --git a/Documentation/DocuBlocks/listEndpoints.md b/Documentation/DocuBlocks/listEndpoints.md index 8ca50f3184..302b6174cc 100644 --- a/Documentation/DocuBlocks/listEndpoints.md +++ b/Documentation/DocuBlocks/listEndpoints.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock listEndpoints -/// @brief returns a list of all endpoints -/// `db._listEndpoints()` -/// -/// Returns a list of all endpoints and their mapped databases. -/// -/// Please note that managing endpoints can only be performed from out of the -/// *_system* database. When not in the default database, you must first switch -/// to it using the "db._useDatabase" method. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief returns a list of all endpoints +`db._listEndpoints()` + +Returns a list of all endpoints and their mapped databases. + +Please note that managing endpoints can only be performed from out of the +*_system* database. When not in the default database, you must first switch +to it using the "db._useDatabase" method. + diff --git a/Documentation/DocuBlocks/logApplication.md b/Documentation/DocuBlocks/logApplication.md index 9621c9183f..dcc9e9c797 100644 --- a/Documentation/DocuBlocks/logApplication.md +++ b/Documentation/DocuBlocks/logApplication.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logApplication -/// @brief log application name -/// `--log.application name` -/// -/// Specifies the *name* of the application which should be logged if this -/// item of -/// information is to be logged. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log application name +`--log.application name` + +Specifies the *name* of the application which should be logged if this +item of +information is to be logged. + diff --git a/Documentation/DocuBlocks/logContentFilter.md b/Documentation/DocuBlocks/logContentFilter.md index 2ea2276234..91a4996b94 100644 --- a/Documentation/DocuBlocks/logContentFilter.md +++ b/Documentation/DocuBlocks/logContentFilter.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logContentFilter -/// @brief log content filter -/// `--log.content-filter arg` -/// -/// Only log message containing the specified string *arg*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log content filter +`--log.content-filter arg` + +Only log message containing the specified string *arg*. + diff --git a/Documentation/DocuBlocks/logFacility.md b/Documentation/DocuBlocks/logFacility.md index 41912b0400..7ed6986902 100644 --- a/Documentation/DocuBlocks/logFacility.md +++ b/Documentation/DocuBlocks/logFacility.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logFacility -/// @brief log facility -/// `--log.facility name` -/// -/// If this option is set, then in addition to output being directed to the -/// standard output (or to a specified file, in the case that the command line -/// log.file option was set), log output is also sent to the system logging -/// facility. The *arg* is the system log facility to use. See syslog for -/// further details. -/// -/// The value of *arg* depends on your syslog configuration. In general it -/// will be *user*. Fatal messages are mapped to *crit*, so if *arg* -/// is *user*, these messages will be logged as *user.crit*. Error -/// messages are mapped to *err*. Warnings are mapped to *warn*. Info -/// messages are mapped to *notice*. Debug messages are mapped to -/// *info*. Trace messages are mapped to *debug*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log facility +`--log.facility name` + +If this option is set, then in addition to output being directed to the +standard output (or to a specified file, in the case that the command line +log.file option was set), log output is also sent to the system logging +facility. The *arg* is the system log facility to use. See syslog for +further details. + +The value of *arg* depends on your syslog configuration. In general it +will be *user*. Fatal messages are mapped to *crit*, so if *arg* +is *user*, these messages will be logged as *user.crit*. Error +messages are mapped to *err*. Warnings are mapped to *warn*. Info +messages are mapped to *notice*. Debug messages are mapped to +*info*. Trace messages are mapped to *debug*. + diff --git a/Documentation/DocuBlocks/logFile.md b/Documentation/DocuBlocks/logFile.md index 3e0fae69c5..8bd78d4237 100644 --- a/Documentation/DocuBlocks/logFile.md +++ b/Documentation/DocuBlocks/logFile.md @@ -1,5 +1,4 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logFile -/// @brief log file -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log file + diff --git a/Documentation/DocuBlocks/logLevel.md b/Documentation/DocuBlocks/logLevel.md index ade455004c..6e95b1d2b2 100644 --- a/Documentation/DocuBlocks/logLevel.md +++ b/Documentation/DocuBlocks/logLevel.md @@ -1,95 +1,94 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logLevel -/// @brief log level -/// `--log.level level` -/// -/// `--log level` -/// -/// Allows the user to choose the level of information which is logged by the -/// server. The argument *level* is specified as a string and can be one of -/// the values listed below. Note that, fatal errors, that is, errors which -/// cause the server to terminate, are always logged irrespective of the log -/// level assigned by the user. The variant *c* log.level can be used in -/// configuration files, the variant *c* log for command line options. -/// -/// **fatal**: -/// Logs errors which cause the server to terminate. -/// -/// Fatal errors generally indicate some inconsistency with the manner in -/// which -/// the server has been coded. Fatal errors may also indicate a problem with -/// the -/// platform on which the server is running. Fatal errors always cause the -/// server to terminate. For example, -/// -/// ``` -/// 2010-09-20T07:32:12Z [4742] FATAL a http server has already been created -/// ``` -/// -/// **error**: -/// Logs errors which the server has encountered. -/// -/// These errors may not necessarily result in the termination of the -/// server. For example, -/// -/// ``` -/// 2010-09-17T13:10:22Z [13967] ERROR strange log level 'errors'\, going to -/// 'warning' -/// ``` -/// -/// **warning**: -/// Provides information on errors encountered by the server, -/// which are not necessarily detrimental to it's continued operation. -/// -/// For example, -/// -/// ``` -/// 2010-09-20T08:15:26Z [5533] WARNING got corrupted HTTP request 'POS?' -/// ``` -/// -/// **Note**: The setting the log level to warning will also result in all -/// errors -/// to be logged as well. -/// -/// **info**: -/// Logs information about the status of the server. -/// -/// For example, -/// -/// ``` -/// 2010-09-20T07:40:38Z [4998] INFO SimpleVOC ready for business -/// ``` -/// -/// **Note**: The setting the log level to info will also result in all errors -/// and -/// warnings to be logged as well. -/// -/// **debug**: -/// Logs all errors, all warnings and debug information. -/// -/// Debug log information is generally useful to find out the state of the -/// server in the case of an error. For example, -/// -/// ``` -/// 2010-09-17T13:02:53Z [13783] DEBUG opened port 7000 for any -/// ``` -/// -/// **Note**: The setting the log level to debug will also result in all -/// errors, -/// warnings and server status information to be logged as well. -/// -/// **trace**: -/// As the name suggests, logs information which may be useful to trace -/// problems encountered with using the server. -/// -/// For example, -/// -/// ``` -/// 2010-09-20T08:23:12Z [5687] TRACE trying to open port 8000 -/// ``` -/// -/// **Note**: The setting the log level to trace will also result in all -/// errors, -/// warnings, status information, and debug information to be logged as well. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log level +`--log.level level` + +`--log level` + +Allows the user to choose the level of information which is logged by the +server. The argument *level* is specified as a string and can be one of +the values listed below. Note that, fatal errors, that is, errors which +cause the server to terminate, are always logged irrespective of the log +level assigned by the user. The variant *c* log.level can be used in +configuration files, the variant *c* log for command line options. + +**fatal**: +Logs errors which cause the server to terminate. + +Fatal errors generally indicate some inconsistency with the manner in +which +the server has been coded. Fatal errors may also indicate a problem with +the +platform on which the server is running. Fatal errors always cause the +server to terminate. For example, + +``` +2010-09-20T07:32:12Z [4742] FATAL a http server has already been created +``` + +**error**: +Logs errors which the server has encountered. + +These errors may not necessarily result in the termination of the +server. For example, + +``` +2010-09-17T13:10:22Z [13967] ERROR strange log level 'errors'\, going to +'warning' +``` + +**warning**: +Provides information on errors encountered by the server, +which are not necessarily detrimental to it's continued operation. + +For example, + +``` +2010-09-20T08:15:26Z [5533] WARNING got corrupted HTTP request 'POS?' +``` + +**Note**: The setting the log level to warning will also result in all +errors +to be logged as well. + +**info**: +Logs information about the status of the server. + +For example, + +``` +2010-09-20T07:40:38Z [4998] INFO SimpleVOC ready for business +``` + +**Note**: The setting the log level to info will also result in all errors +and +warnings to be logged as well. + +**debug**: +Logs all errors, all warnings and debug information. + +Debug log information is generally useful to find out the state of the +server in the case of an error. For example, + +``` +2010-09-17T13:02:53Z [13783] DEBUG opened port 7000 for any +``` + +**Note**: The setting the log level to debug will also result in all +errors, +warnings and server status information to be logged as well. + +**trace**: +As the name suggests, logs information which may be useful to trace +problems encountered with using the server. + +For example, + +``` +2010-09-20T08:23:12Z [5687] TRACE trying to open port 8000 +``` + +**Note**: The setting the log level to trace will also result in all +errors, +warnings, status information, and debug information to be logged as well. + diff --git a/Documentation/DocuBlocks/logLineNumber.md b/Documentation/DocuBlocks/logLineNumber.md index fb1b4076e3..3b44b133a3 100644 --- a/Documentation/DocuBlocks/logLineNumber.md +++ b/Documentation/DocuBlocks/logLineNumber.md @@ -1,13 +1,12 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logLineNumber -/// @brief log line number -/// `--log.line-number` -/// -/// Normally, if an human readable fatal, error, warning or info message is -/// logged, no information about the file and line number is provided. The -/// file -/// and line number is only logged for debug and trace message. This option -/// can -/// be use to always log these pieces of information. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log line number +`--log.line-number` + +Normally, if an human readable fatal, error, warning or info message is +logged, no information about the file and line number is provided. The +file +and line number is only logged for debug and trace message. This option +can +be use to always log these pieces of information. + diff --git a/Documentation/DocuBlocks/logLocalTime.md b/Documentation/DocuBlocks/logLocalTime.md index 4c92754565..4252a486fe 100644 --- a/Documentation/DocuBlocks/logLocalTime.md +++ b/Documentation/DocuBlocks/logLocalTime.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logLocalTime -/// @brief log dates and times in local time zone -/// `--log.use-local-time` -/// -/// If specified, all dates and times in log messages will use the server's -/// local time-zone. If not specified, all dates and times in log messages -/// will be printed in UTC / Zulu time. The date and time format used in logs -/// is always `YYYY-MM-DD HH:MM:SS`, regardless of this setting. If UTC time -/// is used, a `Z` will be appended to indicate Zulu time. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log dates and times in local time zone +`--log.use-local-time` + +If specified, all dates and times in log messages will use the server's +local time-zone. If not specified, all dates and times in log messages +will be printed in UTC / Zulu time. The date and time format used in logs +is always `YYYY-MM-DD HH:MM:SS`, regardless of this setting. If UTC time +is used, a `Z` will be appended to indicate Zulu time. + diff --git a/Documentation/DocuBlocks/logPerformance.md b/Documentation/DocuBlocks/logPerformance.md index ba45418c81..a34d2c7ece 100644 --- a/Documentation/DocuBlocks/logPerformance.md +++ b/Documentation/DocuBlocks/logPerformance.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logPerformance -/// @brief performance logging -/// `--log.performance` -/// -/// If this option is set, performance-related info messages will be logged -/// via -/// the regular logging mechanisms. These will consist of mostly timing and -/// debugging information for performance-critical operations. -/// -/// Currently performance-related operations are logged as INFO messages. -/// Messages starting with prefix `[action]` indicate that an instrumented -/// operation was started (note that its end won't be logged). Messages with -/// prefix `[timer]` will contain timing information for operations. Note that -/// no timing information will be logged for operations taking less time than -/// 1 second. This is to ensure that sub-second operations do not pollute -/// logs. -/// -/// The contents of performance-related log messages enabled by this option -/// are subject to change in future versions of ArangoDB. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief performance logging +`--log.performance` + +If this option is set, performance-related info messages will be logged +via +the regular logging mechanisms. These will consist of mostly timing and +debugging information for performance-critical operations. + +Currently performance-related operations are logged as INFO messages. +Messages starting with prefix `[action]` indicate that an instrumented +operation was started (note that its end won't be logged). Messages with +prefix `[timer]` will contain timing information for operations. Note that +no timing information will be logged for operations taking less time than +1 second. This is to ensure that sub-second operations do not pollute +logs. + +The contents of performance-related log messages enabled by this option +are subject to change in future versions of ArangoDB. + diff --git a/Documentation/DocuBlocks/logPrefix.md b/Documentation/DocuBlocks/logPrefix.md index 0dcb520318..91b6134874 100644 --- a/Documentation/DocuBlocks/logPrefix.md +++ b/Documentation/DocuBlocks/logPrefix.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logPrefix -/// @brief log prefix -/// `--log.prefix prefix` -/// -/// This option is used specify an prefix to logged text. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log prefix +`--log.prefix prefix` + +This option is used specify an prefix to logged text. + diff --git a/Documentation/DocuBlocks/logRequests.md b/Documentation/DocuBlocks/logRequests.md index 9792117121..9dcb35b5f3 100644 --- a/Documentation/DocuBlocks/logRequests.md +++ b/Documentation/DocuBlocks/logRequests.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logRequests -/// @brief log file for requests -/// `--log.requests-file filename` -/// -/// This option allows the user to specify the name of a file to which -/// requests are logged. By default, no log file is used and requests are -/// not logged. Note that if the file named by *filename* does not -/// exist, it will be created. If the file cannot be created (e.g. due to -/// missing file privileges), the server will refuse to start. If the -/// specified -/// file already exists, output is appended to that file. -/// -/// Use *+* to log to standard error. Use *-* to log to standard output. -/// Use *""* to disable request logging altogether. -/// -/// The log format is -/// - `"http-request"`: static string indicating that an HTTP request was -/// logged -/// - client address: IP address of client -/// - HTTP method type, e.g. `GET`, `POST` -/// - HTTP version, e.g. `HTTP/1.1` -/// - HTTP response code, e.g. 200 -/// - request body length in bytes -/// - response body length in bytes -/// - server request processing time, containing the time span between -/// fetching -/// the first byte of the HTTP request and the start of the HTTP response -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log file for requests +`--log.requests-file filename` + +This option allows the user to specify the name of a file to which +requests are logged. By default, no log file is used and requests are +not logged. Note that if the file named by *filename* does not +exist, it will be created. If the file cannot be created (e.g. due to +missing file privileges), the server will refuse to start. If the +specified +file already exists, output is appended to that file. + +Use *+* to log to standard error. Use *-* to log to standard output. +Use *""* to disable request logging altogether. + +The log format is +- `"http-request"`: static string indicating that an HTTP request was +logged +- client address: IP address of client +- HTTP method type, e.g. `GET`, `POST` +- HTTP version, e.g. `HTTP/1.1` +- HTTP response code, e.g. 200 +- request body length in bytes +- response body length in bytes +- server request processing time, containing the time span between +fetching + the first byte of the HTTP request and the start of the HTTP response + diff --git a/Documentation/DocuBlocks/logSourceFilter.md b/Documentation/DocuBlocks/logSourceFilter.md index d889cc6544..37d3aab805 100644 --- a/Documentation/DocuBlocks/logSourceFilter.md +++ b/Documentation/DocuBlocks/logSourceFilter.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logSourceFilter -/// @brief log source filter -/// `--log.source-filter arg` -/// -/// For debug and trace messages, only log those messages originated from the -/// C source file *arg*. The argument can be used multiple times. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log source filter +`--log.source-filter arg` + +For debug and trace messages, only log those messages originated from the +C source file *arg*. The argument can be used multiple times. + diff --git a/Documentation/DocuBlocks/logThread.md b/Documentation/DocuBlocks/logThread.md index fcfb2a82af..a868a3d7f2 100644 --- a/Documentation/DocuBlocks/logThread.md +++ b/Documentation/DocuBlocks/logThread.md @@ -1,22 +1,21 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock logThread -/// @brief log thread identifier -/// `--log.thread` -/// -/// Whenever log output is generated, the process ID is written as part of the -/// log information. Setting this option appends the thread id of the calling -/// thread to the process id. For example, -/// -/// ``` -/// 2010-09-20T13:04:01Z [19355] INFO ready for business -/// ``` -/// -/// when no thread is logged and -/// -/// ``` -/// 2010-09-20T13:04:17Z [19371-18446744072487317056] ready for business -/// ``` -/// -/// when this command line option is set. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief log thread identifier +`--log.thread` + +Whenever log output is generated, the process ID is written as part of the +log information. Setting this option appends the thread id of the calling +thread to the process id. For example, + +``` +2010-09-20T13:04:01Z [19355] INFO ready for business +``` + +when no thread is logged and + +``` +2010-09-20T13:04:17Z [19371-18446744072487317056] ready for business +``` + +when this command line option is set. + diff --git a/Documentation/DocuBlocks/lookUpFulltextIndex.md b/Documentation/DocuBlocks/lookUpFulltextIndex.md index 5d0a65f1ba..aae66e01f3 100644 --- a/Documentation/DocuBlocks/lookUpFulltextIndex.md +++ b/Documentation/DocuBlocks/lookUpFulltextIndex.md @@ -1,8 +1,7 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock lookUpFulltextIndex -/// @brief looks up a fulltext index -/// `collection.lookupFulltextIndex(attribute, minLength)` -/// -/// Checks whether a fulltext index on the given attribute *attribute* exists. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief looks up a fulltext index +`collection.lookupFulltextIndex(attribute, minLength)` + +Checks whether a fulltext index on the given attribute *attribute* exists. + diff --git a/Documentation/DocuBlocks/pidFile.md b/Documentation/DocuBlocks/pidFile.md index d78e70bd0c..73b4c7f29c 100644 --- a/Documentation/DocuBlocks/pidFile.md +++ b/Documentation/DocuBlocks/pidFile.md @@ -1,10 +1,9 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock pidFile -/// @brief pid file -/// `--pid-file filename` -/// -/// The name of the process ID file to use when running the server as a -/// daemon. This parameter must be specified if either the flag *daemon* or -/// *supervisor* is set. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief pid file +`--pid-file filename` + +The name of the process ID file to use when running the server as a +daemon. This parameter must be specified if either the flag *daemon* or +*supervisor* is set. + diff --git a/Documentation/DocuBlocks/queryCacheMaxResults.md b/Documentation/DocuBlocks/queryCacheMaxResults.md index bc072459f0..722c896f30 100644 --- a/Documentation/DocuBlocks/queryCacheMaxResults.md +++ b/Documentation/DocuBlocks/queryCacheMaxResults.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock queryCacheMaxResults -/// @brief maximum number of elements in the query cache per database -/// `--database.query-cache-max-results` -/// -/// Maximum number of query results that can be stored per database-specific -/// query cache. If a query is eligible for caching and the number of items in -/// the database's query cache is equal to this threshold value, another -/// cached -/// query result will be removed from the cache. -/// -/// This option only has an effect if the query cache mode is set to either -/// *on* or *demand*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief maximum number of elements in the query cache per database +`--database.query-cache-max-results` + +Maximum number of query results that can be stored per database-specific +query cache. If a query is eligible for caching and the number of items in +the database's query cache is equal to this threshold value, another +cached +query result will be removed from the cache. + +This option only has an effect if the query cache mode is set to either +*on* or *demand*. + diff --git a/Documentation/DocuBlocks/queryCacheMode.md b/Documentation/DocuBlocks/queryCacheMode.md index f1ed446c87..7c66a5978f 100644 --- a/Documentation/DocuBlocks/queryCacheMode.md +++ b/Documentation/DocuBlocks/queryCacheMode.md @@ -1,15 +1,14 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock queryCacheMode -/// @brief whether or not to enable the AQL query cache -/// `--database.query-cache-mode` -/// -/// Toggles the AQL query cache behavior. Possible values are: -/// -/// * *off*: do not use query cache -/// * *on*: always use query cache, except for queries that have their *cache* -/// attribute set to *false* -/// * *demand*: use query cache only for queries that have their *cache* -/// attribute set to *true* -/// set -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief whether or not to enable the AQL query cache +`--database.query-cache-mode` + +Toggles the AQL query cache behavior. Possible values are: + +* *off*: do not use query cache +* *on*: always use query cache, except for queries that have their *cache* + attribute set to *false* +* *demand*: use query cache only for queries that have their *cache* + attribute set to *true* + set + diff --git a/Documentation/DocuBlocks/queryExecute.md b/Documentation/DocuBlocks/queryExecute.md index c433e37318..34cec06df8 100644 --- a/Documentation/DocuBlocks/queryExecute.md +++ b/Documentation/DocuBlocks/queryExecute.md @@ -1,38 +1,37 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock queryExecute -/// @brief executes a query -/// `query.execute(batchSize)` -/// -/// Executes a simple query. If the optional batchSize value is specified, -/// the server will return at most batchSize values in one roundtrip. -/// The batchSize cannot be adjusted after the query is first executed. -/// -/// **Note**: There is no need to explicitly call the execute method if another -/// means of fetching the query results is chosen. The following two approaches -/// lead to the same result: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{executeQuery} -/// ~ db._create("users"); -/// ~ db.users.save({ name: "Gerhard" }); -/// ~ db.users.save({ name: "Helmut" }); -/// ~ db.users.save({ name: "Angela" }); -/// result = db.users.all().toArray(); -/// q = db.users.all(); q.execute(); result = [ ]; while (q.hasNext()) { result.push(q.next()); } -/// ~ db._drop("users") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// The following two alternatives both use a batchSize and return the same -/// result: -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{executeQueryBatchSize} -/// ~ db._create("users"); -/// ~ db.users.save({ name: "Gerhard" }); -/// ~ db.users.save({ name: "Helmut" }); -/// ~ db.users.save({ name: "Angela" }); -/// q = db.users.all(); q.setBatchSize(20); q.execute(); while (q.hasNext()) { print(q.next()); } -/// q = db.users.all(); q.execute(20); while (q.hasNext()) { print(q.next()); } -/// ~ db._drop("users") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief executes a query +`query.execute(batchSize)` + +Executes a simple query. If the optional batchSize value is specified, +the server will return at most batchSize values in one roundtrip. +The batchSize cannot be adjusted after the query is first executed. + +**Note**: There is no need to explicitly call the execute method if another +means of fetching the query results is chosen. The following two approaches +lead to the same result: + +@EXAMPLE_ARANGOSH_OUTPUT{executeQuery} +~ db._create("users"); +~ db.users.save({ name: "Gerhard" }); +~ db.users.save({ name: "Helmut" }); +~ db.users.save({ name: "Angela" }); + result = db.users.all().toArray(); + q = db.users.all(); q.execute(); result = [ ]; while (q.hasNext()) { result.push(q.next()); } +~ db._drop("users") +@END_EXAMPLE_ARANGOSH_OUTPUT + +The following two alternatives both use a batchSize and return the same +result: + +@EXAMPLE_ARANGOSH_OUTPUT{executeQueryBatchSize} +~ db._create("users"); +~ db.users.save({ name: "Gerhard" }); +~ db.users.save({ name: "Helmut" }); +~ db.users.save({ name: "Angela" }); + q = db.users.all(); q.setBatchSize(20); q.execute(); while (q.hasNext()) { print(q.next()); } + q = db.users.all(); q.execute(20); while (q.hasNext()) { print(q.next()); } +~ db._drop("users") +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/queryLimit.md b/Documentation/DocuBlocks/queryLimit.md index bc04643e73..057880b226 100644 --- a/Documentation/DocuBlocks/queryLimit.md +++ b/Documentation/DocuBlocks/queryLimit.md @@ -1,28 +1,27 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock queryLimit -/// @brief limit -/// `query.limit(number)` -/// -/// Limits a result to the first *number* documents. Specifying a limit of -/// *0* will return no documents at all. If you do not need a limit, just do -/// not add the limit operator. The limit must be non-negative. -/// -/// In general the input to *limit* should be sorted. Otherwise it will be -/// unclear which documents will be included in the result set. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{queryLimit} -/// ~ db._create("five"); -/// ~ db.five.save({ name : "one" }); -/// ~ db.five.save({ name : "two" }); -/// ~ db.five.save({ name : "three" }); -/// ~ db.five.save({ name : "four" }); -/// ~ db.five.save({ name : "five" }); -/// db.five.all().toArray(); -/// db.five.all().limit(2).toArray(); -/// ~ db._drop("five") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief limit +`query.limit(number)` + +Limits a result to the first *number* documents. Specifying a limit of +*0* will return no documents at all. If you do not need a limit, just do +not add the limit operator. The limit must be non-negative. + +In general the input to *limit* should be sorted. Otherwise it will be +unclear which documents will be included in the result set. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{queryLimit} +~ db._create("five"); +~ db.five.save({ name : "one" }); +~ db.five.save({ name : "two" }); +~ db.five.save({ name : "three" }); +~ db.five.save({ name : "four" }); +~ db.five.save({ name : "five" }); + db.five.all().toArray(); + db.five.all().limit(2).toArray(); +~ db._drop("five") +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/querySkip.md b/Documentation/DocuBlocks/querySkip.md index eadb9ea9a7..09660f1d20 100644 --- a/Documentation/DocuBlocks/querySkip.md +++ b/Documentation/DocuBlocks/querySkip.md @@ -1,30 +1,29 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock querySkip -/// @brief skip -/// `query.skip(number)` -/// -/// Skips the first *number* documents. If *number* is positive, then this -/// number of documents are skipped before returning the query results. -/// -/// In general the input to *skip* should be sorted. Otherwise it will be -/// unclear which documents will be included in the result set. -/// -/// Note: using negative *skip* values is **deprecated** as of ArangoDB 2.6 and -/// will not be supported in future versions of ArangoDB. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{querySkip} -/// ~ db._create("five"); -/// ~ db.five.save({ name : "one" }); -/// ~ db.five.save({ name : "two" }); -/// ~ db.five.save({ name : "three" }); -/// ~ db.five.save({ name : "four" }); -/// ~ db.five.save({ name : "five" }); -/// db.five.all().toArray(); -/// db.five.all().skip(3).toArray(); -/// ~ db._drop("five") -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief skip +`query.skip(number)` + +Skips the first *number* documents. If *number* is positive, then this +number of documents are skipped before returning the query results. + +In general the input to *skip* should be sorted. Otherwise it will be +unclear which documents will be included in the result set. + +Note: using negative *skip* values is **deprecated** as of ArangoDB 2.6 and +will not be supported in future versions of ArangoDB. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{querySkip} +~ db._create("five"); +~ db.five.save({ name : "one" }); +~ db.five.save({ name : "two" }); +~ db.five.save({ name : "three" }); +~ db.five.save({ name : "four" }); +~ db.five.save({ name : "five" }); + db.five.all().toArray(); + db.five.all().skip(3).toArray(); +~ db._drop("five") +@END_EXAMPLE_ARANGOSH_OUTPUT + + diff --git a/Documentation/DocuBlocks/randomGenerator.md b/Documentation/DocuBlocks/randomGenerator.md index ddc105154a..4b11e614c0 100644 --- a/Documentation/DocuBlocks/randomGenerator.md +++ b/Documentation/DocuBlocks/randomGenerator.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock randomGenerator -/// @brief random number generator to use -/// `--random.generator arg` -/// -/// The argument is an integer (1,2,3 or 4) which sets the manner in which -/// random numbers are generated. The default method (3) is to use the a -/// non-blocking random (or pseudorandom) number generator supplied by the -/// operating system. -/// -/// Specifying an argument of 2, uses a blocking random (or -/// pseudorandom) number generator. Specifying an argument 1 sets a -/// pseudorandom -/// number generator using an implication of the Mersenne Twister MT19937 -/// algorithm. Algorithm 4 is a combination of the blocking random number -/// generator and the Mersenne Twister. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief random number generator to use +`--random.generator arg` + +The argument is an integer (1,2,3 or 4) which sets the manner in which +random numbers are generated. The default method (3) is to use the a +non-blocking random (or pseudorandom) number generator supplied by the +operating system. + +Specifying an argument of 2, uses a blocking random (or +pseudorandom) number generator. Specifying an argument 1 sets a +pseudorandom +number generator using an implication of the Mersenne Twister MT19937 +algorithm. Algorithm 4 is a combination of the blocking random number +generator and the Mersenne Twister. + diff --git a/Documentation/DocuBlocks/schedulerBackend.md b/Documentation/DocuBlocks/schedulerBackend.md index edea4a80b3..541ae1d21c 100644 --- a/Documentation/DocuBlocks/schedulerBackend.md +++ b/Documentation/DocuBlocks/schedulerBackend.md @@ -1,11 +1,10 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock schedulerBackend -/// @brief scheduler backend -/// `--scheduler.backend arg` -/// -/// The I/O method used by the event handler. The default (if this option is -/// not specified) is to try all recommended backends. This is platform -/// specific. See libev for further details and the meaning of select, poll -/// and epoll. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief scheduler backend +`--scheduler.backend arg` + +The I/O method used by the event handler. The default (if this option is +not specified) is to try all recommended backends. This is platform +specific. See libev for further details and the meaning of select, poll +and epoll. + diff --git a/Documentation/DocuBlocks/schedulerMaximalQueueSize.md b/Documentation/DocuBlocks/schedulerMaximalQueueSize.md index ae39a89d13..8eefc9dfe8 100644 --- a/Documentation/DocuBlocks/schedulerMaximalQueueSize.md +++ b/Documentation/DocuBlocks/schedulerMaximalQueueSize.md @@ -1,13 +1,12 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock schedulerMaximalQueueSize -/// @brief maximum size of the dispatcher queue for asynchronous requests -/// `--scheduler.maximal-queue-size size` -/// -/// Specifies the maximum *size* of the dispatcher queue for asynchronous -/// task execution. If the queue already contains *size* tasks, new tasks -/// will be rejected until other tasks are popped from the queue. Setting this -/// value may help preventing from running out of memory if the queue is -/// filled -/// up faster than the server can process requests. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief maximum size of the dispatcher queue for asynchronous requests +`--scheduler.maximal-queue-size size` + +Specifies the maximum *size* of the dispatcher queue for asynchronous +task execution. If the queue already contains *size* tasks, new tasks +will be rejected until other tasks are popped from the queue. Setting this +value may help preventing from running out of memory if the queue is +filled +up faster than the server can process requests. + diff --git a/Documentation/DocuBlocks/schedulerThreads.md b/Documentation/DocuBlocks/schedulerThreads.md index e6edf76e34..336a4958d4 100644 --- a/Documentation/DocuBlocks/schedulerThreads.md +++ b/Documentation/DocuBlocks/schedulerThreads.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock schedulerThreads -/// @brief number of scheduler threads -/// `--scheduler.threads arg` -/// -/// An integer argument which sets the number of threads to use in the IO -/// scheduler. The default is 1. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief number of scheduler threads +`--scheduler.threads arg` + +An integer argument which sets the number of threads to use in the IO +scheduler. The default is 1. + diff --git a/Documentation/DocuBlocks/serverAllowMethod.md b/Documentation/DocuBlocks/serverAllowMethod.md index db6202eb95..bce4996fc4 100644 --- a/Documentation/DocuBlocks/serverAllowMethod.md +++ b/Documentation/DocuBlocks/serverAllowMethod.md @@ -1,26 +1,25 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverAllowMethod -/// @brief allow HTTP method override via custom headers? -/// `--server.allow-method-override` -/// -/// When this option is set to *true*, the HTTP request method will optionally -/// be fetched from one of the following HTTP request headers if present in -/// the request: -/// -/// - *x-http-method* -/// - *x-http-method-override* -/// - *x-method-override* -/// -/// If the option is set to *true* and any of these headers is set, the -/// request method will be overridden by the value of the header. For example, -/// this allows issuing an HTTP DELETE request which to the outside world will -/// look like an HTTP GET request. This allows bypassing proxies and tools -/// that -/// will only let certain request types pass. -/// -/// Setting this option to *true* may impose a security risk so it should only -/// be used in controlled environments. -/// -/// The default value for this option is *false*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief allow HTTP method override via custom headers? +`--server.allow-method-override` + +When this option is set to *true*, the HTTP request method will optionally +be fetched from one of the following HTTP request headers if present in +the request: + +- *x-http-method* +- *x-http-method-override* +- *x-method-override* + +If the option is set to *true* and any of these headers is set, the +request method will be overridden by the value of the header. For example, +this allows issuing an HTTP DELETE request which to the outside world will +look like an HTTP GET request. This allows bypassing proxies and tools +that +will only let certain request types pass. + +Setting this option to *true* may impose a security risk so it should only +be used in controlled environments. + +The default value for this option is *false*. + diff --git a/Documentation/DocuBlocks/serverAuthenticationDisable.md b/Documentation/DocuBlocks/serverAuthenticationDisable.md index 1e3bf8d7c7..8e8bbd677a 100644 --- a/Documentation/DocuBlocks/serverAuthenticationDisable.md +++ b/Documentation/DocuBlocks/serverAuthenticationDisable.md @@ -1,20 +1,19 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverAuthenticationDisable -/// @brief disable authentication for requests via UNIX domain sockets -/// `--server.disable-authentication-unix-sockets value` -/// -/// Setting *value* to true will turn off authentication on the server side -/// for requests coming in via UNIX domain sockets. With this flag enabled, -/// clients located on the same host as the ArangoDB server can use UNIX -/// domain -/// sockets to connect to the server without authentication. -/// Requests coming in by other means (e.g. TCP/IP) are not affected by this -/// option. -/// -/// The default value is *false*. -/// -/// **Note**: this option is only available on platforms that support UNIX -/// domain -/// sockets. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief disable authentication for requests via UNIX domain sockets +`--server.disable-authentication-unix-sockets value` + +Setting *value* to true will turn off authentication on the server side +for requests coming in via UNIX domain sockets. With this flag enabled, +clients located on the same host as the ArangoDB server can use UNIX +domain +sockets to connect to the server without authentication. +Requests coming in by other means (e.g. TCP/IP) are not affected by this +option. + +The default value is *false*. + +**Note**: this option is only available on platforms that support UNIX +domain +sockets. + diff --git a/Documentation/DocuBlocks/serverBacklog.md b/Documentation/DocuBlocks/serverBacklog.md index 1c4878861b..1f78bf0279 100644 --- a/Documentation/DocuBlocks/serverBacklog.md +++ b/Documentation/DocuBlocks/serverBacklog.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverBacklog -/// @brief listen backlog size -/// `--server.backlog-size` -/// -/// Allows to specify the size of the backlog for the *listen* system call -/// The default value is 10. The maximum value is platform-dependent. -/// Specifying -/// a higher value than defined in the system header's SOMAXCONN may result in -/// a warning on server start. The actual value used by *listen* may also be -/// silently truncated on some platforms (this happens inside the *listen* -/// system call). -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief listen backlog size +`--server.backlog-size` + +Allows to specify the size of the backlog for the *listen* system call +The default value is 10. The maximum value is platform-dependent. +Specifying +a higher value than defined in the system header's SOMAXCONN may result in +a warning on server start. The actual value used by *listen* may also be +silently truncated on some platforms (this happens inside the *listen* +system call). + diff --git a/Documentation/DocuBlocks/serverCafile.md b/Documentation/DocuBlocks/serverCafile.md index 684d0688fc..b2920930f6 100644 --- a/Documentation/DocuBlocks/serverCafile.md +++ b/Documentation/DocuBlocks/serverCafile.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverCafile -/// @brief CA file -/// `--server.cafile filename` -/// -/// This option can be used to specify a file with CA certificates that are -/// sent -/// to the client whenever the server requests a client certificate. If the -/// file is specified, The server will only accept client requests with -/// certificates issued by these CAs. Do not specify this option if you want -/// clients to be able to connect without specific certificates. -/// -/// The certificates in *filename* must be PEM formatted. -/// -/// **Note**: this option is only relevant if at least one SSL endpoint is -/// used. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief CA file +`--server.cafile filename` + +This option can be used to specify a file with CA certificates that are +sent +to the client whenever the server requests a client certificate. If the +file is specified, The server will only accept client requests with +certificates issued by these CAs. Do not specify this option if you want +clients to be able to connect without specific certificates. + +The certificates in *filename* must be PEM formatted. + +**Note**: this option is only relevant if at least one SSL endpoint is +used. + diff --git a/Documentation/DocuBlocks/serverDefaultApi.md b/Documentation/DocuBlocks/serverDefaultApi.md index f9fbfea6e6..9585b2e213 100644 --- a/Documentation/DocuBlocks/serverDefaultApi.md +++ b/Documentation/DocuBlocks/serverDefaultApi.md @@ -1,25 +1,24 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverDefaultApi -/// @brief default API compatibility -/// `--server.default-api-compatibility` -/// -/// This option can be used to determine the API compatibility of the ArangoDB -/// server. It expects an ArangoDB version number as an integer, calculated as -/// follows: -/// -/// *10000 \* major + 100 \* minor (example: *10400* for ArangoDB 1.4)* -/// -/// The value of this option will have an influence on some API return values -/// when the HTTP client used does not send any compatibility information. -/// -/// In most cases it will be sufficient to not set this option explicitly but -/// to -/// keep the default value. However, in case an "old" ArangoDB client is used -/// that does not send any compatibility information and that cannot handle -/// the -/// responses of the current version of ArangoDB, it might be reasonable to -/// set -/// the option to an old version number to improve compatibility with older -/// clients. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief default API compatibility +`--server.default-api-compatibility` + +This option can be used to determine the API compatibility of the ArangoDB +server. It expects an ArangoDB version number as an integer, calculated as +follows: + +*10000 \* major + 100 \* minor (example: *10400* for ArangoDB 1.4)* + +The value of this option will have an influence on some API return values +when the HTTP client used does not send any compatibility information. + +In most cases it will be sufficient to not set this option explicitly but +to +keep the default value. However, in case an "old" ArangoDB client is used +that does not send any compatibility information and that cannot handle +the +responses of the current version of ArangoDB, it might be reasonable to +set +the option to an old version number to improve compatibility with older +clients. + diff --git a/Documentation/DocuBlocks/serverDisableReplicationApplier.md b/Documentation/DocuBlocks/serverDisableReplicationApplier.md index 12bde154c1..113887a86f 100644 --- a/Documentation/DocuBlocks/serverDisableReplicationApplier.md +++ b/Documentation/DocuBlocks/serverDisableReplicationApplier.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverDisableReplicationApplier -/// @brief disable the replication applier on server startup -/// `--server.disable-replication-applier flag` -/// -/// If *true* the server will start with the replication applier turned off, -/// even if the replication applier is configured with the *autoStart* option. -/// Using the command-line option will not change the value of the *autoStart* -/// option in the applier configuration, but will suppress auto-starting the -/// replication applier just once. -/// -/// If the option is not used, ArangoDB will read the applier configuration -/// from -/// the file *REPLICATION-APPLIER-CONFIG* on startup, and use the value of the -/// *autoStart* attribute from this file. -/// -/// The default is *false*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief disable the replication applier on server startup +`--server.disable-replication-applier flag` + +If *true* the server will start with the replication applier turned off, +even if the replication applier is configured with the *autoStart* option. +Using the command-line option will not change the value of the *autoStart* +option in the applier configuration, but will suppress auto-starting the +replication applier just once. + +If the option is not used, ArangoDB will read the applier configuration +from +the file *REPLICATION-APPLIER-CONFIG* on startup, and use the value of the +*autoStart* attribute from this file. + +The default is *false*. + diff --git a/Documentation/DocuBlocks/serverHideProductHeader.md b/Documentation/DocuBlocks/serverHideProductHeader.md index 58eb3286bf..f57aad407b 100644 --- a/Documentation/DocuBlocks/serverHideProductHeader.md +++ b/Documentation/DocuBlocks/serverHideProductHeader.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverHideProductHeader -/// @brief hide the "Server: ArangoDB" header in HTTP responses -/// `--server.hide-product-header` -/// -/// If *true*, the server will exclude the HTTP header "Server: ArangoDB" in -/// HTTP responses. If set to *false*, the server will send the header in -/// responses. -/// -/// The default is *false*. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief hide the "Server: ArangoDB" header in HTTP responses +`--server.hide-product-header` + +If *true*, the server will exclude the HTTP header "Server: ArangoDB" in +HTTP responses. If set to *false*, the server will send the header in +responses. + +The default is *false*. + diff --git a/Documentation/DocuBlocks/serverKeyfile.md b/Documentation/DocuBlocks/serverKeyfile.md index e6099638a3..71834e617e 100644 --- a/Documentation/DocuBlocks/serverKeyfile.md +++ b/Documentation/DocuBlocks/serverKeyfile.md @@ -1,59 +1,58 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverKeyfile -/// @brief keyfile containing server certificate -/// `--server.keyfile filename` -/// -/// If SSL encryption is used, this option must be used to specify the -/// filename -/// of the server private key. The file must be PEM formatted and contain both -/// the certificate and the server's private key. -/// -/// The file specified by *filename* should have the following structure: -/// -/// ``` -/// # create private key in file "server.key" -/// openssl genrsa -des3 -out server.key 1024 -/// -/// # create certificate signing request (csr) in file "server.csr" -/// openssl req -new -key server.key -out server.csr -/// -/// # copy away original private key to "server.key.org" -/// cp server.key server.key.org -/// -/// # remove passphrase from the private key -/// openssl rsa -in server.key.org -out server.key -/// -/// # sign the csr with the key, creates certificate PEM file "server.crt" -/// openssl x509 -req -days 365 -in server.csr -signkey server.key -out -/// server.crt -/// -/// # combine certificate and key into single PEM file "server.pem" -/// cat server.crt server.key > server.pem -/// ``` -/// -/// You may use certificates issued by a Certificate Authority or self-signed -/// certificates. Self-signed certificates can be created by a tool of your -/// choice. When using OpenSSL for creating the self-signed certificate, the -/// following commands should create a valid keyfile: -/// -/// ``` -/// -----BEGIN CERTIFICATE----- -/// -/// (base64 encoded certificate) -/// -/// -----END CERTIFICATE----- -/// -----BEGIN RSA PRIVATE KEY----- -/// -/// (base64 encoded private key) -/// -/// -----END RSA PRIVATE KEY----- -/// ``` -/// -/// For further information please check the manuals of the tools you use to -/// create the certificate. -/// -/// **Note**: the \-\-server.keyfile option must be set if the server is -/// started with -/// at least one SSL endpoint. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief keyfile containing server certificate +`--server.keyfile filename` + +If SSL encryption is used, this option must be used to specify the +filename +of the server private key. The file must be PEM formatted and contain both +the certificate and the server's private key. + +The file specified by *filename* should have the following structure: + +``` +# create private key in file "server.key" +openssl genrsa -des3 -out server.key 1024 + +# create certificate signing request (csr) in file "server.csr" +openssl req -new -key server.key -out server.csr + +# copy away original private key to "server.key.org" +cp server.key server.key.org + +# remove passphrase from the private key +openssl rsa -in server.key.org -out server.key + +# sign the csr with the key, creates certificate PEM file "server.crt" +openssl x509 -req -days 365 -in server.csr -signkey server.key -out +server.crt + +# combine certificate and key into single PEM file "server.pem" +cat server.crt server.key > server.pem +``` + +You may use certificates issued by a Certificate Authority or self-signed +certificates. Self-signed certificates can be created by a tool of your +choice. When using OpenSSL for creating the self-signed certificate, the +following commands should create a valid keyfile: + +``` +-----BEGIN CERTIFICATE----- + +(base64 encoded certificate) + +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- + +(base64 encoded private key) + +-----END RSA PRIVATE KEY----- +``` + +For further information please check the manuals of the tools you use to +create the certificate. + +**Note**: the \-\-server.keyfile option must be set if the server is +started with +at least one SSL endpoint. + diff --git a/Documentation/DocuBlocks/serverReuseAddress.md b/Documentation/DocuBlocks/serverReuseAddress.md index fe998bbae8..d28ba2456e 100644 --- a/Documentation/DocuBlocks/serverReuseAddress.md +++ b/Documentation/DocuBlocks/serverReuseAddress.md @@ -1,19 +1,18 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverReuseAddress -/// @brief try to reuse address -/// `--server.reuse-address` -/// -/// If this boolean option is set to *true* then the socket option -/// SO_REUSEADDR is set on all server endpoints, which is the default. -/// If this option is set to *false* it is possible that it takes up -/// to a minute after a server has terminated until it is possible for -/// a new server to use the same endpoint again. This is why this is -/// activated by default. -/// -/// Please note however that under some operating systems this can be -/// a security risk because it might be possible for another process -/// to bind to the same address and port, possibly hijacking network -/// traffic. Under Windows, ArangoDB additionally sets the flag -/// SO_EXCLUSIVEADDRUSE as a measure to alleviate this problem. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief try to reuse address +`--server.reuse-address` + +If this boolean option is set to *true* then the socket option +SO_REUSEADDR is set on all server endpoints, which is the default. +If this option is set to *false* it is possible that it takes up +to a minute after a server has terminated until it is possible for +a new server to use the same endpoint again. This is why this is +activated by default. + +Please note however that under some operating systems this can be +a security risk because it might be possible for another process +to bind to the same address and port, possibly hijacking network +traffic. Under Windows, ArangoDB additionally sets the flag +SO_EXCLUSIVEADDRUSE as a measure to alleviate this problem. + diff --git a/Documentation/DocuBlocks/serverSSLCache.md b/Documentation/DocuBlocks/serverSSLCache.md index c9f4725f97..3a4bfeb4a5 100644 --- a/Documentation/DocuBlocks/serverSSLCache.md +++ b/Documentation/DocuBlocks/serverSSLCache.md @@ -1,14 +1,13 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverSSLCache -/// @brief whether or not to use SSL session caching -/// `--server.ssl-cache value` -/// -/// Set to true if SSL session caching should be used. -/// -/// *value* has a default value of *false* (i.e. no caching). -/// -/// **Note**: this option is only relevant if at least one SSL endpoint is -/// used, and -/// only if the client supports sending the session id. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief whether or not to use SSL session caching +`--server.ssl-cache value` + +Set to true if SSL session caching should be used. + +*value* has a default value of *false* (i.e. no caching). + +**Note**: this option is only relevant if at least one SSL endpoint is +used, and +only if the client supports sending the session id. + diff --git a/Documentation/DocuBlocks/serverSSLCipher.md b/Documentation/DocuBlocks/serverSSLCipher.md index 2f35d30355..9a35151254 100644 --- a/Documentation/DocuBlocks/serverSSLCipher.md +++ b/Documentation/DocuBlocks/serverSSLCipher.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverSSLCipher -/// @brief ssl cipher list to use -/// `--server.ssl-cipher-list cipher-list` -/// -/// This option can be used to restrict the server to certain SSL ciphers -/// only, -/// and to define the relative usage preference of SSL ciphers. -/// -/// The format of *cipher-list* is documented in the OpenSSL documentation. -/// -/// To check which ciphers are available on your platform, you may use the -/// following shell command: -/// -/// ``` -/// > openssl ciphers -v -/// -/// ECDHE-RSA-AES256-SHA SSLv3 Kx=ECDH Au=RSA Enc=AES(256) Mac=SHA1 -/// ECDHE-ECDSA-AES256-SHA SSLv3 Kx=ECDH Au=ECDSA Enc=AES(256) Mac=SHA1 -/// DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1 -/// DHE-DSS-AES256-SHA SSLv3 Kx=DH Au=DSS Enc=AES(256) Mac=SHA1 -/// DHE-RSA-CAMELLIA256-SHA SSLv3 Kx=DH Au=RSA Enc=Camellia(256) -/// Mac=SHA1 -/// ... -/// ``` -/// -/// The default value for *cipher-list* is "ALL". -/// -/// **Note**: this option is only relevant if at least one SSL endpoint is -/// used. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ssl cipher list to use +`--server.ssl-cipher-list cipher-list` + +This option can be used to restrict the server to certain SSL ciphers +only, +and to define the relative usage preference of SSL ciphers. + +The format of *cipher-list* is documented in the OpenSSL documentation. + +To check which ciphers are available on your platform, you may use the +following shell command: + +``` +> openssl ciphers -v + +ECDHE-RSA-AES256-SHA SSLv3 Kx=ECDH Au=RSA Enc=AES(256) Mac=SHA1 +ECDHE-ECDSA-AES256-SHA SSLv3 Kx=ECDH Au=ECDSA Enc=AES(256) Mac=SHA1 +DHE-RSA-AES256-SHA SSLv3 Kx=DH Au=RSA Enc=AES(256) Mac=SHA1 +DHE-DSS-AES256-SHA SSLv3 Kx=DH Au=DSS Enc=AES(256) Mac=SHA1 +DHE-RSA-CAMELLIA256-SHA SSLv3 Kx=DH Au=RSA Enc=Camellia(256) +Mac=SHA1 +... +``` + +The default value for *cipher-list* is "ALL". + +**Note**: this option is only relevant if at least one SSL endpoint is +used. + diff --git a/Documentation/DocuBlocks/serverSSLOptions.md b/Documentation/DocuBlocks/serverSSLOptions.md index 1f0426e3f9..3f8acaafd2 100644 --- a/Documentation/DocuBlocks/serverSSLOptions.md +++ b/Documentation/DocuBlocks/serverSSLOptions.md @@ -1,32 +1,31 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverSSLOptions -/// @brief ssl options to use -/// `--server.ssl-options value` -/// -/// This option can be used to set various SSL-related options. Individual -/// option values must be combined using bitwise OR. -/// -/// Which options are available on your platform is determined by the OpenSSL -/// version you use. The list of options available on your platform might be -/// retrieved by the following shell command: -/// -/// ``` -/// > grep "#define SSL_OP_.*" /usr/include/openssl/ssl.h -/// -/// #define SSL_OP_MICROSOFT_SESS_ID_BUG 0x00000001L -/// #define SSL_OP_NETSCAPE_CHALLENGE_BUG 0x00000002L -/// #define SSL_OP_LEGACY_SERVER_CONNECT 0x00000004L -/// #define SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 0x00000008L -/// #define SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 0x00000010L -/// #define SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 0x00000020L -/// ... -/// ``` -/// -/// A description of the options can be found online in the -/// [OpenSSL -/// documentation](http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html) -/// -/// **Note**: this option is only relevant if at least one SSL endpoint is -/// used. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief ssl options to use +`--server.ssl-options value` + +This option can be used to set various SSL-related options. Individual +option values must be combined using bitwise OR. + +Which options are available on your platform is determined by the OpenSSL +version you use. The list of options available on your platform might be +retrieved by the following shell command: + +``` + > grep "#define SSL_OP_.*" /usr/include/openssl/ssl.h + + #define SSL_OP_MICROSOFT_SESS_ID_BUG 0x00000001L + #define SSL_OP_NETSCAPE_CHALLENGE_BUG 0x00000002L + #define SSL_OP_LEGACY_SERVER_CONNECT 0x00000004L + #define SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 0x00000008L + #define SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 0x00000010L + #define SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 0x00000020L + ... +``` + +A description of the options can be found online in the +[OpenSSL +documentation](http://www.openssl.org/docs/ssl/SSL_CTX_set_options.html) + +**Note**: this option is only relevant if at least one SSL endpoint is +used. + diff --git a/Documentation/DocuBlocks/serverSSLProtocol.md b/Documentation/DocuBlocks/serverSSLProtocol.md index 18cf1f26ac..8165b6a9f0 100644 --- a/Documentation/DocuBlocks/serverSSLProtocol.md +++ b/Documentation/DocuBlocks/serverSSLProtocol.md @@ -1,18 +1,17 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverSSLProtocol -/// @brief SSL protocol type to use -/// `--server.ssl-protocolvalue` -/// -/// Use this option to specify the default encryption protocol to be used. -/// The following variants are available: -/// - 1: SSLv2 -/// - 2: SSLv23 -/// - 3: SSLv3 -/// - 4: TLSv1 -/// -/// The default *value* is 4 (i.e. TLSv1). -/// -/// **Note**: this option is only relevant if at least one SSL endpoint is -/// used. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief SSL protocol type to use +`--server.ssl-protocolvalue` + +Use this option to specify the default encryption protocol to be used. +The following variants are available: +- 1: SSLv2 +- 2: SSLv23 +- 3: SSLv3 +- 4: TLSv1 + +The default *value* is 4 (i.e. TLSv1). + +**Note**: this option is only relevant if at least one SSL endpoint is +used. + diff --git a/Documentation/DocuBlocks/serverThreads.md b/Documentation/DocuBlocks/serverThreads.md index 686c67dd1f..32e691f163 100644 --- a/Documentation/DocuBlocks/serverThreads.md +++ b/Documentation/DocuBlocks/serverThreads.md @@ -1,9 +1,8 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock serverThreads -/// @brief number of dispatcher threads -/// `--server.threads number` -/// -/// Specifies the *number* of threads that are spawned to handle HTTP REST -/// requests. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief number of dispatcher threads +`--server.threads number` + +Specifies the *number* of threads that are spawned to handle HTTP REST +requests. + diff --git a/Documentation/DocuBlocks/v8Contexts.md b/Documentation/DocuBlocks/v8Contexts.md index cdfb976ae6..5a29d187f9 100644 --- a/Documentation/DocuBlocks/v8Contexts.md +++ b/Documentation/DocuBlocks/v8Contexts.md @@ -1,12 +1,11 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock v8Contexts -/// @brief number of V8 contexts for executing JavaScript actions -/// `--server.v8-contexts number` -/// -/// Specifies the *number* of V8 contexts that are created for executing -/// JavaScript code. More contexts allow execute more JavaScript actions in -/// parallel, provided that there are also enough threads available. Please -/// note that each V8 context will use a substantial amount of memory and -/// requires periodic CPU processing time for garbage collection. -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief number of V8 contexts for executing JavaScript actions +`--server.v8-contexts number` + +Specifies the *number* of V8 contexts that are created for executing +JavaScript code. More contexts allow execute more JavaScript actions in +parallel, provided that there are also enough threads available. Please +note that each V8 context will use a substantial amount of memory and +requires periodic CPU processing time for garbage collection. + diff --git a/Documentation/DocuBlocks/walFlush.md b/Documentation/DocuBlocks/walFlush.md index e136433dc4..07d9e03370 100644 --- a/Documentation/DocuBlocks/walFlush.md +++ b/Documentation/DocuBlocks/walFlush.md @@ -1,28 +1,27 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock walFlush -/// @brief flushes the currently open WAL logfile -/// `internal.wal.flush(waitForSync, waitForCollector)` -/// -/// Flushes the write-ahead log. By flushing the currently active write-ahead -/// logfile, the data in it can be transferred to collection journals and -/// datafiles. This is useful to ensure that all data for a collection is -/// present in the collection journals and datafiles, for example, when dumping -/// the data of a collection. -/// -/// The *waitForSync* option determines whether or not the operation should -/// block until the not-yet synchronized data in the write-ahead log was -/// synchronized to disk. -/// -/// The *waitForCollector* operation can be used to specify that the operation -/// should block until the data in the flushed log has been collected by the -/// write-ahead log garbage collector. Note that setting this option to *true* -/// might block for a long time if there are long-running transactions and -/// the write-ahead log garbage collector cannot finish garbage collection. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{WalFlush} -/// require("internal").wal.flush(); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief flushes the currently open WAL logfile +`internal.wal.flush(waitForSync, waitForCollector)` + +Flushes the write-ahead log. By flushing the currently active write-ahead +logfile, the data in it can be transferred to collection journals and +datafiles. This is useful to ensure that all data for a collection is +present in the collection journals and datafiles, for example, when dumping +the data of a collection. + +The *waitForSync* option determines whether or not the operation should +block until the not-yet synchronized data in the write-ahead log was +synchronized to disk. + +The *waitForCollector* operation can be used to specify that the operation +should block until the data in the flushed log has been collected by the +write-ahead log garbage collector. Note that setting this option to *true* +might block for a long time if there are long-running transactions and +the write-ahead log garbage collector cannot finish garbage collection. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{WalFlush} + require("internal").wal.flush(); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/walPropertiesGet.md b/Documentation/DocuBlocks/walPropertiesGet.md index 1b0c7ab7fe..f3992a7ef9 100644 --- a/Documentation/DocuBlocks/walPropertiesGet.md +++ b/Documentation/DocuBlocks/walPropertiesGet.md @@ -1,28 +1,27 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock walPropertiesGet -/// @brief retrieves the configuration of the write-ahead log -/// `internal.wal.properties()` -/// -/// Retrieves the configuration of the write-ahead log. The result is a JSON -/// array with the following attributes: -/// - *allowOversizeEntries*: whether or not operations that are bigger than a -/// single logfile can be executed and stored -/// - *logfileSize*: the size of each write-ahead logfile -/// - *historicLogfiles*: the maximum number of historic logfiles to keep -/// - *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB -/// allocates in the background -/// - *syncInterval*: the interval for automatic synchronization of not-yet -/// synchronized write-ahead log data (in milliseconds) -/// - *throttleWait*: the maximum wait time that operations will wait before -/// they get aborted if case of write-throttling (in milliseconds) -/// - *throttleWhenPending*: the number of unprocessed garbage-collection -/// operations that, when reached, will activate write-throttling. A value of -/// *0* means that write-throttling will not be triggered. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{WalPropertiesGet} -/// require("internal").wal.properties(); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief retrieves the configuration of the write-ahead log +`internal.wal.properties()` + +Retrieves the configuration of the write-ahead log. The result is a JSON +array with the following attributes: +- *allowOversizeEntries*: whether or not operations that are bigger than a + single logfile can be executed and stored +- *logfileSize*: the size of each write-ahead logfile +- *historicLogfiles*: the maximum number of historic logfiles to keep +- *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB + allocates in the background +- *syncInterval*: the interval for automatic synchronization of not-yet + synchronized write-ahead log data (in milliseconds) +- *throttleWait*: the maximum wait time that operations will wait before + they get aborted if case of write-throttling (in milliseconds) +- *throttleWhenPending*: the number of unprocessed garbage-collection + operations that, when reached, will activate write-throttling. A value of + *0* means that write-throttling will not be triggered. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{WalPropertiesGet} + require("internal").wal.properties(); +@END_EXAMPLE_ARANGOSH_OUTPUT + diff --git a/Documentation/DocuBlocks/walPropertiesSet.md b/Documentation/DocuBlocks/walPropertiesSet.md index f90b93b5b5..5b04548ca5 100644 --- a/Documentation/DocuBlocks/walPropertiesSet.md +++ b/Documentation/DocuBlocks/walPropertiesSet.md @@ -1,31 +1,30 @@ -//////////////////////////////////////////////////////////////////////////////// -/// @startDocuBlock walPropertiesSet -/// @brief configures the write-ahead log -/// `internal.wal.properties(properties)` -/// -/// Configures the behavior of the write-ahead log. *properties* must be a JSON -/// JSON object with the following attributes: -/// - *allowOversizeEntries*: whether or not operations that are bigger than a -/// single logfile can be executed and stored -/// - *logfileSize*: the size of each write-ahead logfile -/// - *historicLogfiles*: the maximum number of historic logfiles to keep -/// - *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB -/// allocates in the background -/// - *throttleWait*: the maximum wait time that operations will wait before -/// they get aborted if case of write-throttling (in milliseconds) -/// - *throttleWhenPending*: the number of unprocessed garbage-collection -/// operations that, when reached, will activate write-throttling. A value of -/// *0* means that write-throttling will not be triggered. -/// -/// Specifying any of the above attributes is optional. Not specified attributes -/// will be ignored and the configuration for them will not be modified. -/// -/// @EXAMPLES -/// -/// @EXAMPLE_ARANGOSH_OUTPUT{WalPropertiesSet} -/// | require("internal").wal.properties({ -/// | allowOverSizeEntries: true, -/// logfileSize: 32 * 1024 * 1024 }); -/// @END_EXAMPLE_ARANGOSH_OUTPUT -/// @endDocuBlock -//////////////////////////////////////////////////////////////////////////////// \ No newline at end of file + + +@brief configures the write-ahead log +`internal.wal.properties(properties)` + +Configures the behavior of the write-ahead log. *properties* must be a JSON +JSON object with the following attributes: +- *allowOversizeEntries*: whether or not operations that are bigger than a + single logfile can be executed and stored +- *logfileSize*: the size of each write-ahead logfile +- *historicLogfiles*: the maximum number of historic logfiles to keep +- *reserveLogfiles*: the maximum number of reserve logfiles that ArangoDB + allocates in the background +- *throttleWait*: the maximum wait time that operations will wait before + they get aborted if case of write-throttling (in milliseconds) +- *throttleWhenPending*: the number of unprocessed garbage-collection + operations that, when reached, will activate write-throttling. A value of + *0* means that write-throttling will not be triggered. + +Specifying any of the above attributes is optional. Not specified attributes +will be ignored and the configuration for them will not be modified. + +@EXAMPLES + +@EXAMPLE_ARANGOSH_OUTPUT{WalPropertiesSet} +| require("internal").wal.properties({ +| allowOverSizeEntries: true, + logfileSize: 32 * 1024 * 1024 }); +@END_EXAMPLE_ARANGOSH_OUTPUT +