diff --git a/Documentation/Books/Users/Aql/GraphOperations.mdpp b/Documentation/Books/Users/Aql/GraphOperations.mdpp index 2f5586c81b..ebca8db510 100644 --- a/Documentation/Books/Users/Aql/GraphOperations.mdpp +++ b/Documentation/Books/Users/Aql/GraphOperations.mdpp @@ -28,81 +28,101 @@ This section describes various AQL functions which can be used to receive inform !SUBSECTION GRAPH_EDGES + @startDocuBlock JSF_ahuacatl_general_graph_edges !SUBSECTION GRAPH_VERTICES + @startDocuBlock JSF_ahuacatl_general_graph_vertices !SUBSECTION GRAPH_NEIGHBORS + @startDocuBlock JSF_ahuacatl_general_graph_neighbors !SUBSECTION GRAPH_COMMON_NEIGHBORS + @startDocuBlock JSF_ahuacatl_general_graph_common_neighbors !SUBSECTION GRAPH_COMMON_PROPERTIES + @startDocuBlock JSF_ahuacatl_general_graph_common_properties !SUBSECTION Shortest Paths, distances and traversals. + This section describes AQL functions, that calculate pathes from a subset of vertices in a graph to another subset of vertices. !SUBSECTION GRAPH_PATHS + @startDocuBlock JSF_ahuacatl_general_graph_paths !SUBSECTION GRAPH_SHORTEST_PATH + @startDocuBlock JSF_ahuacatl_general_graph_shortest_paths !SUBSECTION GRAPH_TRAVERSAL + @startDocuBlock JSF_ahuacatl_general_graph_traversal !SUBSECTION GRAPH_TRAVERSAL_TREE + @startDocuBlock JSF_ahuacatl_general_graph_traversal_tree !SUBSECTION GRAPH_DISTANCE_TO + @startDocuBlock JSF_ahuacatl_general_graph_distance !SUBSECTION Graph measurements. + This section describes AQL functions to calculate various graph related measurements as defined in the mathematical graph theory. !SUBSECTION GRAPH_ABSOLUTE_ECCENTRICITY + @startDocuBlock JSF_ahuacatl_general_graph_absolute_eccentricity !SUBSECTION GRAPH_ECCENTRICITY + @startDocuBlock JSF_ahuacatl_general_graph_eccentricity !SUBSECTION GRAPH_ABSOLUTE_CLOSENESS + @startDocuBlock JSF_ahuacatl_general_graph_absolute_closeness !SUBSECTION GRAPH_CLOSENESS + @startDocuBlock JSF_ahuacatl_general_graph_closeness !SUBSECTION GRAPH_ABSOLUTE_BETWEENNESS + @startDocuBlock JSF_ahuacatl_general_graph_absolute_betweenness !SUBSECTION GRAPH_BETWEENNESS + @startDocuBlock JSF_ahuacatl_general_graph_betweenness !SUBSECTION GRAPH_RADIUS + @startDocuBlock JSF_ahuacatl_general_graph_radius !SUBSECTION GRAPH_DIAMETER + @startDocuBlock JSF_ahuacatl_general_graph_diameter diff --git a/Documentation/Books/Users/ConfigureArango/README.mdpp b/Documentation/Books/Users/ConfigureArango/README.mdpp index 685807ecb0..0b2c8f4de3 100644 --- a/Documentation/Books/Users/ConfigureArango/README.mdpp +++ b/Documentation/Books/Users/ConfigureArango/README.mdpp @@ -2,5 +2,5 @@ !SUBSECTION Configuration Files Options can be specified on the command line or in configuration files. If a -string *@VARIABLE@* occurs in the value, it is replaced by the corresponding +string *Variable* occurs in the value, it is replaced by the corresponding environment variable. diff --git a/Documentation/Books/Users/HttpAqlQuery/README.mdpp b/Documentation/Books/Users/HttpAqlQuery/README.mdpp index 46f527ac90..987a1888d9 100644 --- a/Documentation/Books/Users/HttpAqlQuery/README.mdpp +++ b/Documentation/Books/Users/HttpAqlQuery/README.mdpp @@ -7,208 +7,9 @@ valid AQL query. Both functionalities do not actually execute the supplied AQL query, but only inspect it and return meta information about it. -`POST /_api/explain`*(explains a query)* -!SUBSECTION Body parameters + +@startDocuBlock JSF_post_api_explain -`body (json,required)` - -The query string needs to be passed in the attribute query of a JSON object as the body of the POST request. If the query references any bind variables, these must also be passed in the attribute bindVars. -Description - -To explain how an AQL query would be executed on the server, the query string can be sent to the server via an HTTP POST request. The server will then validate the query and create an execution plan for it, but will not execute it. - -The execution plan that is returned by the server can be used to estimate the probable performance of an AQL query. Though the actual performance will depend on many different factors, the execution plan normally can give some good hint on the amount of work the server needs to do in order to actually run the query. - -The top-level statements will appear in the result in the same order in which they have been used in the original query. Each result element has at most the following attributes: - -* id: the row number of the top-level statement, starting at 1 -* type: the type of the top-level statement (e.g. for, return ...) -* loopLevel: the nesting level of the top-level statement, starting at 1 Depending on the type of top-level statement, there might be other attributes providing additional information, for example, if and which indexed will be used. Many top-level statements will provide an expression attribute that contains data about the expression they operate on. This is true for FOR, FILTER, SORT, COLLECT, and RETURN statements. The expression attribute has the following sub-attributes: -* type: the type of the expression. Some possible values are: -* collection: an iteration over documents from a collection. The value attribute will then contain the collection name. The extra attribute will contain information about if and which index is used when accessing the documents from the collection. If no index is used, the accessType sub-attribute of the extra attribute will have the value all, otherwise it will be index. -* list: a list of dynamic values. The value attribute will contain the list elements. -* const list: a list of constant values. The value attribute will contain the list elements. -* reference: a reference to another variable. The value attribute will contain the name of the variable that is referenced. - -Please note that the structure of the explain result data might change in future versions of ArangoDB without further notice and without maintaining backwards compatibility. - -!SUBSECTION Return codes - -`HTTP 200` - -If the query is valid, the server will respond with HTTP 200 and return a list of the individual query execution steps in the "plan" attribute of the response. - -`HTTP 400` - -The server will respond with HTTP 400 in case of a malformed request, or if the query contains a parse error. The body of the response will contain the error details embedded in a JSON object. Omitting bind variables if the query references any will result also result in an HTTP 400 error. - -`HTTP 404` - -The server will respond with HTTP 404 in case a non-existing collection is accessed in the query. - -*Examples* - -Valid query: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/explain -{ "query" : "FOR p IN products FILTER p.id == @id LIMIT 2 RETURN p.name", "bindVars": { "id" : 3 } } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "plan" : [ - { - "id" : 1, - "loopLevel" : 1, - "type" : "for", - "resultVariable" : "p", - "limit" : true, - "expression" : { - "type" : "collection", - "value" : "products", - "extra" : { - "accessType" : "all" - } - } - }, - { - "id" : 2, - "loopLevel" : 1, - "type" : "filter", - "expression" : { - "type" : "expression", - "value" : "p.id == 3" - } - }, - { - "id" : 3, - "loopLevel" : 1, - "type" : "return", - "expression" : { - "type" : "expression", - "value" : "p.name" - } - } - ], - "error" : false, - "code" : 200 -} -``` - -Invalid query: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/explain -{ "query" : "FOR p IN products FILTER p.id == @id LIMIT 2 RETURN p.n" } - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 400, - "errorNum" : 1551, - "errorMessage" : "no value specified for declared bind parameter 'id'" -} -``` - -The data returned in the plan attribute of the result contains one element per AQL top-level statement (i.e. FOR, RETURN, FILTER etc.). If the query optimizer removed some unnecessary statements, the result might also contain less elements than there were top-level statements in the AQL query. The following example shows a query with a non-sensible filter condition that the optimizer has removed so that there are less top-level statements: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/explain -{ "query" : "FOR i IN [ 1, 2, 3 ] FILTER 1 == 2 RETURN i" } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "plan" : [ - { - "id" : 1, - "loopLevel" : 0, - "type" : "return (empty)", - "expression" : { - "type" : "const list", - "value" : "[ ]" - } - } - ], - "error" : false, - "code" : 200 -} -``` - -`POST /_api/query`*(parses a query)* - -!SUBSECTION Body parameters - -`query (json,required)` - -!SUBSECTION Description - -To validate a query string without executing it, the query string can be passed to the server via an HTTP POST request. - -These query string needs to be passed in the attribute query of a JSON object as the body of the POST request. - -!SUBSECTION Return codes - -`HTTP 200` - -If the query is valid, the server will respond with HTTP 200 and return the names of the bind parameters it found in the query (if any) in the "bindVars" attribute of the response. - -`HTTP 400` - -The server will respond with HTTP 400 in case of a malformed request, or if the query contains a parse error. The body of the response will contain the error details embedded in a JSON object. - -*Examples* - -Valid query: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/query -{ "query" : "FOR p IN products FILTER p.name == @name LIMIT 2 RETURN p.n" } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "bindVars" : [ - "name" - ], - "collections" : [ - "products" - ], - "error" : false, - "code" : 200 -} -``` - -Invalid query: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/query -{ "query" : "FOR p IN products FILTER p.name = @name LIMIT 2 RETURN p.n" } - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 400, - "errorNum" : 1501, - "errorMessage" : "syntax error, unexpected assignment near '= @name LIMIT 2 RETURN p.n' at positio..." -} -``` - - - \ No newline at end of file + +@startDocuBlock JSF_post_api_query \ No newline at end of file diff --git a/Documentation/Books/Users/HttpAqlQueryCursor/AccessingCursors.mdpp b/Documentation/Books/Users/HttpAqlQueryCursor/AccessingCursors.mdpp index 88fd099107..da8aeb8cd8 100644 --- a/Documentation/Books/Users/HttpAqlQueryCursor/AccessingCursors.mdpp +++ b/Documentation/Books/Users/HttpAqlQueryCursor/AccessingCursors.mdpp @@ -1,438 +1,13 @@ !CHAPTER Accessing Cursors via HTTP -`POST /_api/cursor`*(creates a cursor)* + +@startDocuBlock JSF_post_api_cursor -!SUBSECTION Body parameters + +@startDocuBlock JSF_post_api_query -`query (json,required)` + +@startDocuBlock JSF_post_api_cursor_identifier -A JSON object describing the query and query parameters. -!SUBSECTION Description - -The query details include the query string plus optional query options and bind parameters. These values need to be passed in a JSON representation in the body of the POST request. -The following attributes can be used inside the JSON object: - -* query: contains the query string to be executed (mandatory) -* count: boolean flag that indicates whether the number of documents in the result set should be returned in the "count" attribute of the result (optional). Calculating the "count" attribute might in the future have a performance impact for some queries so this option is turned off by default, and "count" is only returned when requested. -* batchSize: maximum number of result documents to be transferred from the server to the client in one roundtrip (optional). If this attribute is not set, a server-controlled default value will be used. -* bindVars: key/value list of bind parameters (optional). -* options: key/value list of extra options for the query (optional). - -The following options are supported at the moment: - -* fullCount: if set to true and the query contains a LIMIT clause, then the result will contain an extra attribute extra with a sub-attribute fullCount. This sub-attribute will contain the number of documents in the result before the last LIMIT in the query was applied. It can be used to count the number of documents that match certain filter criteria, but only return a subset of them, in one go. It is thus similar to MySQL's SQL_CALC_FOUND_ROWS hint. Note that setting the option will disable a few LIMIT optimizations and may lead to more documents being processed, and thus make queries run longer. Note that the fullCount sub-attribute will only be present in the result if the query has a LIMIT clause and the LIMIT clause is actually used in the query. - -If the result set can be created by the server, the server will respond with HTTP 201. The body of the response will contain a JSON object with the result set. - -The returned JSON object has the following properties: - -* error: boolean flag to indicate that an error occurred (false in this case) -* code: the HTTP status code -* result: an array of result documents (might be empty if query has no results) -* hasMore: a boolean indicator whether there are more results available for the cursor on the server -* count: the total number of result documents available (only available if the query was executed with the count attribute set) -* id: id of temporary cursor created on the server (optional, see above) -* extra: an optional JSON object with extra information about the query result - -If the JSON representation is malformed or the query specification is missing from the request, the server will respond with HTTP 400. - -The body of the response will contain a JSON object with additional error details. The object has the following attributes: - -* error: boolean flag to indicate that an error occurred (true in this case) -* code: the HTTP status code -* errorNum: the server error number -* errorMessage: a descriptive error message - -If the query specification is complete, the server will process the query. If an error occurs during query processing, the server will respond with HTTP 400. Again, the body of the response will contain details about the error. - -A list of query errors can be found Error codes and meanings here. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the result set can be created by the server. - -`HTTP 400` - -is returned if the JSON representation is malformed or the query specification is missing from the request. - -`HTTP 404` - -The server will respond with HTTP 404 in case a non-existing collection is accessed in the query. - -`HTTP 405` - -The server will respond with HTTP 405 if an unsupported HTTP method is used. - -*Examples* - -Executes a query and extract the result in a single go: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/cursor -{"query":"FOR p IN products LIMIT 2 RETURN p","count":true,"batchSize":2} - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/44950497", - "_rev" : "44950497", - "_key" : "44950497", - "hello1" : "world1" - }, - { - "_id" : "products/45278177", - "_rev" : "45278177", - "_key" : "45278177", - "hello2" : "world1" - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -Executes a query and extracts part of the result: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/cursor -{"query":"FOR p IN products LIMIT 5 RETURN p","count":true,"batchSize":2} - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/46130145", - "_rev" : "46130145", - "_key" : "46130145", - "hello2" : "world1" - }, - { - "_id" : "products/45802465", - "_rev" : "45802465", - "_key" : "45802465", - "hello1" : "world1" - } - ], - "hasMore" : true, - "id" : "47309793", - "count" : 5, - "error" : false, - "code" : 201 -} -``` - -Using a query option: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/cursor -{"query":"FOR i IN 1..1000 FILTER i > 500 LIMIT 10 RETURN i","count":true,"options":{"fullCount":true}} - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - 501, - 502, - 503, - 504, - 505, - 506, - 507, - 508, - 509, - 510 - ], - "hasMore" : false, - "count" : 10, - "extra" : { - "fullCount" : 500 - }, - "error" : false, - "code" : 201 -} -``` - -Bad queries: - -Missing body: - -``` -unix> curl -X POST --dump - http://localhost:8529/_api/cursor - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 400, - "errorNum" : 1502, - "errorMessage" : "query is empty" -} -``` - -Unknown collection: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/cursor -{"query":"FOR u IN unknowncoll LIMIT 2 RETURN u","count":true,"batchSize":2} - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 404, - "errorNum" : 1203, - "errorMessage" : "cannot execute query: collection not found: 'unknowncoll'" -} -``` - -`POST /_api/query`*(parses a query)* - -!SUBSECTION Body parameters - -`query (json,required)` - -!SUBSECTION Description - -To validate a query string without executing it, the query string can be passed to the server via an HTTP POST request. - -These query string needs to be passed in the attribute query of a JSON object as the body of the POST request. - -!SUBSECTION Return codes - -`HTTP 200` - -If the query is valid, the server will respond with HTTP 200 and return the names of the bind parameters it found in the query (if any) in the "bindVars" attribute of the response. - -`HTTP 400` - -The server will respond with HTTP 400 in case of a malformed request, or if the query contains a parse error. The body of the response will contain the error details embedded in a JSON object. - -*Examples* - -Valid query: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/query -{ "query" : "FOR p IN products FILTER p.name == @name LIMIT 2 RETURN p.n" } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "bindVars" : [ - "name" - ], - "collections" : [ - "products" - ], - "error" : false, - "code" : 200 -} -``` - -Invalid query: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/query -{ "query" : "FOR p IN products FILTER p.name = @name LIMIT 2 RETURN p.n" } - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 400, - "errorNum" : 1501, - "errorMessage" : "syntax error, unexpected assignment near '= @name LIMIT 2 RETURN p.n' at positio..." -} -``` - -`PUT /_api/cursor/cursor-identifier`*(reads next batch from a cursor)* - -!SUBSECTION URL parameters - -`cursor-identifier (string,required)` - -The name of the cursor - -!SUBSECTION Description - -If the cursor is still alive, returns an object with the following attributes. - -* id: the cursor-identifier -* result: a list of documents for the current batch -* hasMore: false if this was the last batch -* count: if present the total number of elements - -*Note*: Even if hasMore returns true, the next call might still return no documents. If, however, hasMore is false, then the cursor is exhausted. Once the hasMore attribute has a value of false, the client can stop. - -!SUBSECTION Return codes - -`HTTP 200` - -The server will respond with HTTP 200 in case of success. - -`HTTP 400` - -If the cursor identifier is ommitted, the server will respond with HTTP 404. - -`HTTP 404` - -If no cursor with the specified identifier can be found, the server will respond with HTTP 404. - -*Examples* - -Valid request for next batch: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/cursor -{"query":"FOR p IN products LIMIT 5 RETURN p","count":true,"batchSize":2} - -unix> curl -X PUT --dump - http://localhost:8529/_api/cursor/49275873 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/48096225", - "_rev" : "48096225", - "_key" : "48096225", - "hello2" : "world1" - }, - { - "_id" : "products/47768545", - "_rev" : "47768545", - "_key" : "47768545", - "hello1" : "world1" - } - ], - "hasMore" : true, - "id" : "49275873", - "count" : 5, - "error" : false, - "code" : 200 -} -``` - -Missing identifier - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/cursor - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 400, - "errorNum" : 400, - "errorMessage" : "bad parameter" -} -``` - -Unknown identifier - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/cursor/123123 - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 404, - "errorNum" : 1600, - "errorMessage" : "cursor not found" -} -``` - -`DELETE /_api/cursor/cursor-identifier`*(deletes a cursor)* - -!SUBSECTION URL parameters - -`cursor-identifier (string,required)` - -The name of the cursor - -!SUBSECTION Description - -Deletes the cursor and frees the resources associated with it. -The cursor will automatically be destroyed on the server when the client has retrieved all documents from it. The client can also explicitly destroy the cursor at any earlier time using an HTTP DELETE request. The cursor id must be included as part of the URL. - -*Note*: The server will also destroy abandoned cursors automatically after a certain server-controlled timeout to avoid resource leakage. - -!SUBSECTION Return codes - -`HTTP 202` - -is returned if the server is aware of the cursor. - -`HTTP 404` - -is returned if the server is not aware of the cursor. It is also returned if a cursor is used after it has been destroyed. - -*Examples* - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/cursor -{"query":"FOR p IN products LIMIT 5 RETURN p","count":true,"batchSize":2} - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/49996769", - "_rev" : "49996769", - "_key" : "49996769", - "hello2" : "world1" - }, - { - "_id" : "products/50652129", - "_rev" : "50652129", - "_key" : "50652129", - "hello4" : "world1" - } - ], - "hasMore" : true, - "id" : "51176417", - "count" : 5, - "error" : false, - "code" : 201 -} - -unix> curl -X DELETE --dump - http://localhost:8529/_api/cursor/51176417 -``` - - - \ No newline at end of file + +@startDocuBlock JSF_post_api_cursor_delete \ No newline at end of file diff --git a/Documentation/Books/Users/HttpAqlQueryCursor/QueryResults.mdpp b/Documentation/Books/Users/HttpAqlQueryCursor/QueryResults.mdpp index c6e92f6b05..d47198297c 100644 --- a/Documentation/Books/Users/HttpAqlQueryCursor/QueryResults.mdpp +++ b/Documentation/Books/Users/HttpAqlQueryCursor/QueryResults.mdpp @@ -20,7 +20,7 @@ retrieved the complete result set by checking the *hasMore* attribute of the result set. If it is set to *false*, then the client has fetched the complete result set from the server. In this case no server side cursor will be created. -``` +```js > curl --data @- -X POST --dump - http://localhost:8529/_api/cursor { "query" : "FOR u IN users LIMIT 2 RETURN u", "count" : true, "batchSize" : 2 } @@ -49,12 +49,6 @@ content-type: application/json } ``` - - !SUBSECTION Using a Cursor If the result set contains more documents than should be transferred in a single @@ -65,11 +59,11 @@ in the *id* attribute of the response object. Furthermore, the *hasMore* attribute of the response object will be set to *true*. This is an indication for the client that there are additional results to fetch from the server. -*Examples* +*Examples*: Create and extract first batch: -``` +```js > curl --data @- -X POST --dump - http://localhost:8529/_api/cursor { "query" : "FOR u IN users LIMIT 5 RETURN u", "count" : true, "batchSize" : 2 } @@ -101,7 +95,7 @@ content-type: application/json Extract next batch, still have more: -``` +```js > curl -X PUT --dump - http://localhost:8529/_api/cursor/26011191 HTTP/1.1 200 OK @@ -132,7 +126,7 @@ content-type: application/json Extract next batch, done: -``` +```js > curl -X PUT --dump - http://localhost:8529/_api/cursor/26011191 HTTP/1.1 200 OK @@ -156,7 +150,7 @@ content-type: application/json Do not do this: -``` +``` js > curl -X PUT --dump - http://localhost:8529/_api/cursor/26011191 HTTP/1.1 404 Not Found @@ -168,24 +162,4 @@ content-type: application/json "error": true, "code": 404 } -``` - - \ No newline at end of file +``` \ No newline at end of file diff --git a/Documentation/Books/Users/HttpAqlUserFunctions/README.mdpp b/Documentation/Books/Users/HttpAqlUserFunctions/README.mdpp index 14bd7aa7a9..f0ae5cad67 100644 --- a/Documentation/Books/Users/HttpAqlUserFunctions/README.mdpp +++ b/Documentation/Books/Users/HttpAqlUserFunctions/README.mdpp @@ -16,183 +16,11 @@ All user functions managed through this interface will be stored in the system collection *_aqlfunctions*. Documents in this collection should not be accessed directly, but only via the dedicated interfaces. -`POST /_api/aqlfunction`*(creates or replaces an AQL user function)* + +@startDocuBlock JSF_post_api_aqlfunction -!SUBSECTION Body parameters + +@startDocuBlock JSF_delete_api_aqlfunction -`body (json,required)` - -the body with name and code of the aql user function. - -!SUBSECTION Description - -The following data need to be passed in a JSON representation in the body of the POST request: - -* name: the fully qualified name of the user functions. -* code: a string representation of the function body. -* isDeterministic: an optional boolean value to indicate that the function results are fully deterministic (function return value solely depends on the input value and return value is the same for repeated calls with same input). The isDeterministic attribute is currently not used but may be used later for optimisations. - -In case of success, the returned JSON object has the following properties: - -* error: boolean flag to indicate that an error occurred (false in this case) -* code: the HTTP status code - -The body of the response will contain a JSON object with additional error details. The object has the following attributes: - -* error: boolean flag to indicate that an error occurred (true in this case) -* code: the HTTP status code -* errorNum: the server error number -* errorMessage: a descriptive error message - -!SUBSECTION Return codes - -`HTTP 200` - -If the function already existed and was replaced by the call, the server will respond with HTTP 200. - -`HTTP 201` - -If the function can be registered by the server, the server will respond with HTTP 201. - -`HTTP 400` - -If the JSON representation is malformed or mandatory data is missing from the request, the server will respond with HTTP 400. -Examples - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/aqlfunction -{ "name" : "myfunctions::temperature::celsiustofahrenheit", "code" : "function (celsius) { return celsius * 1.8 + 32; }" } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "error" : false, - "code" : 201 -} -``` - -`DELETE /_api/aqlfunction/{name}`*(remove an existing AQL user function)* - -!SUBSECTION URL parameters - -`name (string,required)` - -the name of the AQL user function. - - -!SUBSECTION Query parameters - -`group (string,optional)` - -If set to true, then the function name provided in name is treated as a namespace prefix, and all functions in the specified namespace will be deleted. If set to false, the function name provided in name must be fully qualified, including any namespaces. - -!SUBSECTION Description - -Removes an existing AQL user function, identified by name. - -In case of success, the returned JSON object has the following properties: - -* error: boolean flag to indicate that an error occurred (false in this case) -* code: the HTTP status code - -The body of the response will contain a JSON object with additional error details. The object has the following attributes: - -* error: boolean flag to indicate that an error occurred (true in this case) -* code: the HTTP status code -* errorNum: the server error number -* errorMessage: a descriptive error message - -!SUBSECTION Return codes - -`HTTP 200` - -If the function can be removed by the server, the server will respond with HTTP 200. - -`HTTP 400` - -If the user function name is malformed, the server will respond with HTTP 400. - -`HTTP 404` - -If the specified user user function does not exist, the server will respond with HTTP 404. - -*Examples* - -Deletes a function: - -``` -unix> curl -X DELETE --dump - http://localhost:8529/_api/aqlfunction/square::x::y - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "error" : false, - "code" : 200 -} -``` - -function not found: - -unix> curl -X DELETE --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 404, - "errorNum" : 1582, - "errorMessage" : "user function '%s()' not found" -} -``` - -`GET /_api/aqlfunction`*(returns registered AQL user functions)* - -!SUBSECTION Query parameters - -`namespace (string,optional)` - -Returns all registered AQL user functions from namespace namespace. - -!SUBSECTION Description - -Returns all registered AQL user functions. -The call will return a JSON list with all user functions found. Each user function will at least have the following attributes: - -* name: The fully qualified name of the user function -* code: A string representation of the function body - -!SUBSECTION Return codes - -`HTTP 200` - -if success HTTP 200 is returned. - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/aqlfunction - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -[ ] -``` - - - - - \ No newline at end of file + +@startDocuBlock JSF_get_api_aqlfunction diff --git a/Documentation/Books/Users/HttpCollection/Address.mdpp b/Documentation/Books/Users/HttpCollection/Address.mdpp deleted file mode 100644 index cecc0eb7ab..0000000000 --- a/Documentation/Books/Users/HttpCollection/Address.mdpp +++ /dev/null @@ -1,17 +0,0 @@ -!CHAPTER Address of a Collection - -All collections in ArangoDB have an unique identifier and a unique -name. ArangoDB internally uses the collection's unique identifier to -look up collections. This identifier however is managed by ArangoDB -and the user has no control over it. In order to allow users use their -own names, each collection also has a unique name, which is specified -by the user. To access a collection from the user perspective, the -collection name should be used, i.e.: - - http://server:port/_api/collection/collection-name - -For example: Assume that the collection identifier is *7254820* and -the collection name is *demo*, then the URL of that collection is: - - http://localhost:8529/_api/collection/demo - diff --git a/Documentation/Books/Users/HttpCollection/Creating.mdpp b/Documentation/Books/Users/HttpCollection/Creating.mdpp index 96eacae139..750dbaa6fc 100644 --- a/Documentation/Books/Users/HttpCollection/Creating.mdpp +++ b/Documentation/Books/Users/HttpCollection/Creating.mdpp @@ -1,201 +1,11 @@ !CHAPTER Creating and Deleting Collections -`POST /_api/collection`*(creates a collection)* -!SUBSECTION Body parameters + +@startDocuBlock JSF_post_api_collection -`body (json,required)` + +@startDocuBlock JSF_delete_api_collection -the body with name and options for a collection. - -!SUBSECTION Description - -Creates an new collection with a given name. The request must contain an object with the following attributes. - -* name: The name of the collection. -* waitForSync (optional, default: false): If true then the data is synchronised to disk before returning from a create or update of a document. -* doCompact (optional, default is true): whether or not the collection will be compacted. -* 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 synchronisation to disk and does not calculate any CRC checksums for datafiles (as there are no datafiles). - -This option should threrefore be used for cache-type collections only, and not for data that cannot be re-created otherwise. - -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. -* type (optional, default is 2): the type of the collection to create. The following values for type are valid: -* 2: document collection -* 3: edges collection -* 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 of 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. - -*Examples* - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/collection -{"name":"testCollectionBasics"} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -location: /_db/_system/_api/collection/testCollectionBasics - -{ - "id" : "21816289", - "name" : "testCollectionBasics", - "waitForSync" : false, - "isVolatile" : false, - "isSystem" : false, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} - -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/collection -{"name":"testCollectionEdges","type":3} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -location: /_db/_system/_api/collection/testCollectionEdges - -{ - "id" : "21881825", - "name" : "testCollectionEdges", - "waitForSync" : false, - "isVolatile" : false, - "isSystem" : false, - "status" : 3, - "type" : 3, - "error" : false, - "code" : 200 -} - -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/collection -{"name":"testCollectionUsers","keyOptions":{"type":"autoincrement","increment":5,"allowUserKeys":true}} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -location: /_db/_system/_api/collection/testCollectionUsers - -{ - "id" : "21947361", - "name" : "testCollectionUsers", - "waitForSync" : false, - "isVolatile" : false, - "isSystem" : false, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`DELETE /_api/collection/{collection-name}`*(deletes a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection to delete. - -!SUBSECTION Description - -Deletes a collection identified by collection-name. - -If the collection was successfully deleted then, an object is returned with the following attributes: - -* error: false -* id: The identifier of the deleted collection. - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Using an identifier: - -``` -unix> curl -X DELETE --dump - http://localhost:8529/_api/collection/44491745 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "44491745", - "error" : false, - "code" : 200 -} -``` - -Using a name: - -``` -unix> curl -X DELETE --dump - http://localhost:8529/_api/collection/products1 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "44557281", - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/collection/{collection-name}/truncate`*(truncates a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Description - -Removes all documents from the collection, but leaves the indexes intact. - -*Examples* - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/collection/43705313/truncate - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "43705313", - "name" : "products", - "isSystem" : false, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - - - \ No newline at end of file + +@startDocuBlock JSF_put_api_collection_truncate diff --git a/Documentation/Books/Users/HttpCollection/Getting.mdpp b/Documentation/Books/Users/HttpCollection/Getting.mdpp index e7ea837028..4be260d1a9 100644 --- a/Documentation/Books/Users/HttpCollection/Getting.mdpp +++ b/Documentation/Books/Users/HttpCollection/Getting.mdpp @@ -1,660 +1,22 @@ !CHAPTER Getting Information about a Collection -!SUBSECTION URL parameters + +@startDocuBlock JSA_get_api_collection_name -`collection-name (string,required)` + +@startDocuBlock JSA_get_api_collection_properties -The name of the collection. + +@startDocuBlock JSA_get_api_collection_count -!SUBSECTION Description + +@startDocuBlock JSA_get_api_collection_figures -The result is an object describing the collection with the following attributes: + +@startDocuBlock JSA_get_api_collection_revision -* id: The identifier of the collection. -* name: The name of the collection. -* status: The status of the collection as number. -* 1: new born collection -* 2: unloaded -* 3: loaded -* 4: in the process of being unloaded -* 5: deleted + +@startDocuBlock JSA_get_api_collection_checksum -Every other status indicates a corrupted collection. - -* type: The type of the collection as number. -* 2: document collection (normal case) -* 3: edges collection - -!SUBSECTION Return codes - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -`GET /_api/collection/{collection-name}/properties`*(reads the properties of a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Description - -In addition to the above, the result will always contain the waitForSync, doCompact, journalSize, and isVolatile attributes. This is achieved by forcing a load of the underlying collection. - -* waitForSync: If true then creating or changing a document will wait until the data has been synchronised to disk. -* doCompact: Whether or not the collection will be compacted. -* journalSize: The maximal size setting for journals / datafiles. -* isVolatile: If true then the collection data will be kept in memory only and ArangoDB will not write or sync the data to disk. - -In a cluster setup, the result will also contain the following attributes: - -* numberOfShards: the number of shards of the collection. -* shardKeys: contains the names of document attributes that are used to determine the target shard for documents. - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Using an identifier: - -``` -unix> curl --dump - http://localhost:8529/_api/collection/22012897/properties - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -location: /_db/_system/_api/collection/products/properties - -{ - "id" : "22012897", - "name" : "products", - "isSystem" : false, - "doCompact" : true, - "isVolatile" : false, - "journalSize" : 1048576, - "keyOptions" : { - "type" : "traditional", - "allowUserKeys" : true - }, - "waitForSync" : true, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -Using a name: - -``` -unix> curl --dump - http://localhost:8529/_api/collection/products/properties - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -location: /_db/_system/_api/collection/products/properties - -{ - "id" : "22078433", - "name" : "products", - "isSystem" : false, - "doCompact" : true, - "isVolatile" : false, - "journalSize" : 1048576, - "keyOptions" : { - "type" : "traditional", - "allowUserKeys" : true - }, - "waitForSync" : true, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`GET /_api/collection/{collection-name}/count`*(returns the number of documents in a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Description - -In addition to the above, the result also contains the number of documents. Note that this will always load the collection into memory. -count: The number of documents inside the collection. - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Using an identifier and requesting the number of documents: - -``` -unix> curl --dump - http://localhost:8529/_api/collection/22143969/count - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -location: /_db/_system/_api/collection/products/count - -{ - "id" : "22143969", - "name" : "products", - "isSystem" : false, - "doCompact" : true, - "isVolatile" : false, - "journalSize" : 1048576, - "keyOptions" : { - "type" : "traditional", - "allowUserKeys" : true - }, - "waitForSync" : true, - "count" : 100, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`GET /_api/collection/{collection-name}/figures`*(returns the stats for a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Description - -In addition to the above, the result also contains the number of documents and additional statistical information about the collection. Note that this will always load the collection into memory. - -* count: The number of documents currently present in the collection. -* figures.alive.count: The number of currently active documents. -* figures.alive.size: The total size in bytes used by all active documents. -* figures.dead.count: The number of dead documents. This includes document versions that have been deleted or replaced by a newer version. -* figures.dead.size: The total size in bytes used by all dead documents. -* figures.dead.deletion: The total number of deletion markers in the collection. -* figures.datafiles.count: The number of current datafiles. -* figures.datafiles.fileSize: The total filesize of all datafiles. -* figures.journals.count: The number of journal files. -* figures.journals.fileSize: The total filesize of all journal files. -* figures.compactors.count: The number of compactor files. -* figures.compactors.fileSize: The total filesize of all compactor files. -* figures.shapefiles.count: The number of shape files. -* figures.shapefiles.fileSize: The total filesize of all shape files. -* figures.shapes.count: The total number of shapes in the collection (this includes shapes that are not in use anymore) -* figures.attributes.count: The total number of attributes in the collection (this includes attributes that are not in use anymore) -* figures.attributes.size: The total size used by all attribute names in the collection (this includes attributes that are not in use anymore) -* figures.indexes.count: The total number of indexes defined for the collection (this includes internal indexes such as the primary index) -* figures.indexes.size: The total memory allocated by the indexes in bytes -* journalSize: The maximal size of the journal in bytes. - -*Note*: 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. - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Using an identifier and requesting the figures of the collection: - -``` -unix> curl --dump - http://localhost:8529/_api/collection/42132449/figures - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -location: /_db/_system/_api/collection/products/figures - -{ - "id" : "42132449", - "name" : "products", - "isSystem" : false, - "doCompact" : true, - "isVolatile" : false, - "journalSize" : 1048576, - "keyOptions" : { - "type" : "traditional", - "allowUserKeys" : true - }, - "waitForSync" : true, - "count" : 0, - "figures" : { - "alive" : { - "count" : 0, - "size" : 0 - }, - "dead" : { - "count" : 0, - "size" : 0, - "deletion" : 0 - }, - "datafiles" : { - "count" : 0, - "fileSize" : 0 - }, - "journals" : { - "count" : 0, - "fileSize" : 0 - }, - "compactors" : { - "count" : 0, - "fileSize" : 0 - }, - "shapefiles" : { - "count" : 0, - "fileSize" : 0 - }, - "shapes" : { - "count" : 0, - "size" : 0 - }, - "attributes" : { - "count" : 0, - "size" : 0 - }, - "indexes" : { - "count" : 1, - "size" : 88 - } - }, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`GET /_api/collection/{collection-name}/revision`*(return a collection revision id)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Description - -In addition to the above, the result will also contain the collection's revision id. The revision id is a server-generated string that clients can use to check whether data in a collection has changed since the last revision check. - -revision: The collection revision id as a string. - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Retrieving the revision of a collection - -``` -unix> curl --dump - http://localhost:8529/_api/collection/42329057/revision - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "42329057", - "name" : "products", - "isSystem" : false, - "status" : 3, - "type" : 2, - "revision" : "0", - "error" : false, - "code" : 200 -} -``` - -`GET /_api/collection/{collection-name}/checksum`*(returns a checksum for the collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Query parameters - -`withRevisions (boolean,optional)` - -Whether or not to include document revision ids in the checksum calculation. - -`withData (boolean,optional)` - -Whether or not to include document body data in the checksum calculation. - -!SUBSECTION Description - -Will calculate a checksum of the meta-data (keys and optionally revision ids) and optionally the document data in the collection. -The checksum can be used to compare if two collections on different ArangoDB instances contain the same contents. The current revision of the collection is returned too so one can make sure the checksums are calculated for the same state of data. - -By default, the checksum will only be calculated on the _key system attribute of the documents contained in the collection. For edge collections, the system attributes _from and _to will also be included in the calculation. - -By setting the optional URL parameter withRevisions to true, then revision ids (_rev system attributes) are included in the checksumming. - -By providing the optional URL parameter withData with a value of true, the user-defined document attributes will be included in the calculation too. Note that including user-defined attributes will make the checksumming slower. - -The response is a JSON object with the following attributes: - -* checksum: The calculated checksum as a number. -* revision: The collection revision id as a string. -*Note*: this method is not available in a cluster. - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Retrieving the checksum of a collection: - -``` -unix> curl --dump - http://localhost:8529/_api/collection/42460129/checksum - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "42460129", - "name" : "products", - "isSystem" : false, - "status" : 3, - "type" : 2, - "checksum" : 347093004, - "revision" : "42787809", - "error" : false, - "code" : 200 -} -``` - -Retrieving the checksum of a collection including the collection data, but not the revisions: - -``` -unix> curl --dump - http://localhost:8529/_api/collection/42984417/checksum?withRevisions=false&withData=true - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "42984417", - "name" : "products", - "isSystem" : false, - "status" : 3, - "type" : 2, - "checksum" : 3774865365, - "revision" : "43312097", - "error" : false, - "code" : 200 -} -``` - -`GET /_api/collection`*(reads all collections)* - -!SUBSECTION Query parameters - -`excludeSystem (boolean,optional)` - -Whether or not system collections should be excluded from the result. - -!SUBSECTION Description - -Returns an object with an attribute collections containing a list of all collection descriptions. The same information is also available in the names as hash map with the collection names as keys. -By providing the optional URL parameter excludeSystem with a value of true, all system collections will be excluded from the response. - -*Examples* - -Return information about all collections: - -``` -unix> curl --dump - http://localhost:8529/_api/collection - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "collections" : [ - { - "id" : "1565665", - "name" : "_cluster_kickstarter_plans", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "3466209", - "name" : "_aqlfunctions", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "1434593", - "name" : "_modules", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "19063777", - "name" : "demo", - "isSystem" : false, - "status" : 3, - "type" : 2 - }, - { - "id" : "3662817", - "name" : "_configuration", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "19915745", - "name" : "animals", - "isSystem" : false, - "status" : 3, - "type" : 2 - }, - { - "id" : "3531745", - "name" : "_trx", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "1500129", - "name" : "_routing", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "3072993", - "name" : "_aal", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "1369057", - "name" : "_graphs", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "3597281", - "name" : "_replication", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - { - "id" : "189409", - "name" : "_users", - "isSystem" : true, - "status" : 3, - "type" : 2 - } - ], - "names" : { - "_cluster_kickstarter_plans" : { - "id" : "1565665", - "name" : "_cluster_kickstarter_plans", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "_aqlfunctions" : { - "id" : "3466209", - "name" : "_aqlfunctions", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "_modules" : { - "id" : "1434593", - "name" : "_modules", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "demo" : { - "id" : "19063777", - "name" : "demo", - "isSystem" : false, - "status" : 3, - "type" : 2 - }, - "_configuration" : { - "id" : "3662817", - "name" : "_configuration", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "animals" : { - "id" : "19915745", - "name" : "animals", - "isSystem" : false, - "status" : 3, - "type" : 2 - }, - "_trx" : { - "id" : "3531745", - "name" : "_trx", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "_routing" : { - "id" : "1500129", - "name" : "_routing", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "_aal" : { - "id" : "3072993", - "name" : "_aal", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "_graphs" : { - "id" : "1369057", - "name" : "_graphs", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "_replication" : { - "id" : "3597281", - "name" : "_replication", - "isSystem" : true, - "status" : 3, - "type" : 2 - }, - "_users" : { - "id" : "189409", - "name" : "_users", - "isSystem" : true, - "status" : 3, - "type" : 2 - } - }, - "error" : false, - "code" : 200 -} -``` - - \ No newline at end of file + +@startDocuBlock JSF_get_api_collections \ No newline at end of file diff --git a/Documentation/Books/Users/HttpCollection/Modifying.mdpp b/Documentation/Books/Users/HttpCollection/Modifying.mdpp index e0e72ab3de..45333a72f0 100644 --- a/Documentation/Books/Users/HttpCollection/Modifying.mdpp +++ b/Documentation/Books/Users/HttpCollection/Modifying.mdpp @@ -1,285 +1,16 @@ !CHAPTER Modifying a Collection -`PUT /_api/collection/{collection-name}/load`*(loads a collection)* + +@startDocuBlock JSF_put_api_collection_load -!SUBSECTION URL parameters + +@startDocuBlock JSF_put_api_collection_unload -`collection-name (string,required)` + +@startDocuBlock JSF_put_api_collection_properties -The name of the collection. + +@startDocuBlock JSF_put_api_collection_rename -!SUBSECTION Description - -Loads a collection into memory. Returns the collection on success. -The request might optionally contain the following attribute: - -* count: If set, this controls whether the return value should include the number of documents in the collection. Setting count to false may speed up loading a collection. The default value for count is true. - -On success an object with the following attributes is returned: - -* id: The identifier of the collection. -* name: The name of the collection. -* count: The number of documents inside the collection. This is only returned if the count input parameters is set to true or has not been specified. -* status: The status of the collection as number. -* type: The collection type. Valid types are: -* 2: document collection -* 3: edges collection - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/collection/43508705/load - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "43508705", - "name" : "products", - "isSystem" : false, - "count" : 0, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/collection/{collection-name}/unload`*(unloads a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -!SUBSECTION Description - -Removes a collection from memory. This call does not delete any documents. You can use the collection afterwards; in which case it will be loaded into memory, again. On success an object with the following attributes is returned: - -* id: The identifier of the collection. -* name: The name of the collection. -* status: The status of the collection as number. -* type: The collection type. Valid types are: -* 2: document collection -* 3: edges collection - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection-name is missing, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/collection/43639777/unload - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "43639777", - "name" : "products", - "isSystem" : false, - "status" : 2, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/collection/{collection-name}/properties`*(changes the properties of a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Description - -Changes the properties of a collection. Expects an object with the attribute(s) -waitForSync: If true then creating or changing a document will wait until the data has been synchronised to disk. -journalSize: Size (in bytes) for new journal files that are created for the collection. -If returns an object with the attributes - -* id: The identifier of the collection. -* name: The name of the collection. -* waitForSync: The new value. -* journalSize: The new value. -* status: The status of the collection as number. -* type: The collection type. Valid types are: -* 2: document collection -* 3: edges collection -*Note*: some other collection properties, such as type, isVolatile, numberOfShards or shardKeys cannot be changed once a collection is created. - -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/collection/43836385/properties -{"waitForSync":true} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "43836385", - "name" : "products", - "isSystem" : false, - "doCompact" : true, - "isVolatile" : false, - "journalSize" : 1048576, - "keyOptions" : { - "type" : "traditional", - "allowUserKeys" : true - }, - "waitForSync" : true, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/collection/{collection-name}/rename`*(renames a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection to rename. - -!SUBSECTION Description - -Renames a collection. Expects an object with the attribute(s) - -* name: The new name. - -If returns an object with the attributes - -* id: The identifier of the collection. -* name: The new name of the collection. -* status: The status of the collection as number. -* type: The collection type. Valid types are: -* 2: document collection -* 3: edges collection - -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/collection/43901921/rename -{"name":"newname"} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "43901921", - "name" : "newname", - "isSystem" : false, - "status" : 3, - "type" : 2, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/collection/{collection-name}/rotate`*(rotates the journal of a collection)* - -!SUBSECTION URL parameters - -`collection-name (string,required)` - -The name of the collection. - -!SUBSECTION Description - -Rotates the journal of a collection. The current journal of the collection will be closed and made a read-only datafile. The purpose of the rotate method is to make the data in the file available for compaction (compaction is only performed for read-only datafiles, and not for journals). -Saving new data in the collection subsequently will create a new journal file automatically if there is no current journal. - -If returns an object with the attributes - -* result: will be true if rotation succeeded - -*Note*: this method is not available in a cluster. - -!SUBSECTION Return codes - -`HTTP 400` - -If the collection currently has no journal, HTTP 500 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Rotating a journal: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/collection/43967457/rotate -{} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : true, - "error" : false, - "code" : 200 -} -``` - -Rotating without a journal: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/collection/44426209/rotate -{} - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 400, - "errorNum" : 1105, - "errorMessage" : "could not rotate journal: no journal" -} -````` - - \ No newline at end of file + +@startDocuBlock JSF_put_api_collection_rotate diff --git a/Documentation/Books/Users/HttpCollection/README.mdpp b/Documentation/Books/Users/HttpCollection/README.mdpp index 606c192049..be102d1265 100644 --- a/Documentation/Books/Users/HttpCollection/README.mdpp +++ b/Documentation/Books/Users/HttpCollection/README.mdpp @@ -55,6 +55,7 @@ collection is created. The default start value is 0 and the default increment is 1, meaning the key values it will create by default are: 1, 2, 3, 4, 5, ... + When creating a collection with the auto increment key generator and an increment of 5, the generated keys would be: 1, 6, 11, 16, 21, ... @@ -62,3 +63,21 @@ When creating a collection with the auto increment key generator and an incremen The basic operations (create, read, update, delete) for documents are mapped to the standard HTTP methods (*POST*, *GET*, *PUT*, *DELETE*). +!SECTION Address of a Collection + +All collections in ArangoDB have an unique identifier and a unique +name. ArangoDB internally uses the collection's unique identifier to +look up collections. This identifier however is managed by ArangoDB +and the user has no control over it. In order to allow users use their +own names, each collection also has a unique name, which is specified +by the user. To access a collection from the user perspective, the +collection name should be used, i.e.: + + http://server:port/_api/collection/collection-name + +For example: Assume that the collection identifier is *7254820* and +the collection name is *demo*, then the URL of that collection is: + + http://localhost:8529/_api/collection/demo + + diff --git a/Documentation/Books/Users/HttpDatabase/DatabaseEndpoint.mdpp b/Documentation/Books/Users/HttpDatabase/DatabaseEndpoint.mdpp index 15c72f271b..16adeaecc7 100644 --- a/Documentation/Books/Users/HttpDatabase/DatabaseEndpoint.mdpp +++ b/Documentation/Books/Users/HttpDatabase/DatabaseEndpoint.mdpp @@ -8,7 +8,7 @@ regular authentication procedure. If the endpoint is restricted to a list of spe ArangoDB will check if the requested database is in the list. If not, the request will be turned down instantly. If yes, then ArangoDB will continue with the regular authentication procedure. -If the request URI was *http://localhost:8529/_db/mydb/...*, then the request to *mydb* will be +If the request URI was *http:// localhost:8529/_db/mydb/...*, then the request to *mydb* will be allowed (or disallowed) in the following situations: ``` diff --git a/Documentation/Books/Users/HttpDatabase/DatabaseManagement.mdpp b/Documentation/Books/Users/HttpDatabase/DatabaseManagement.mdpp index 1d9a462b0a..f8253d6439 100644 --- a/Documentation/Books/Users/HttpDatabase/DatabaseManagement.mdpp +++ b/Documentation/Books/Users/HttpDatabase/DatabaseManagement.mdpp @@ -10,3 +10,19 @@ databases. Please note that all database management operations can only be accessed via the default database (*_system*) and none of the other databases. +!SECTION Managing Databases using HTTP + + +@startDocuBlock JSF_get_api_database_current + + +@startDocuBlock JSF_get_api_database_user + + +@startDocuBlock JSF_get_api_database_list + + +@startDocuBlock JSF_get_api_database_new + + +@startDocuBlock JSF_get_api_database_delete \ No newline at end of file diff --git a/Documentation/Books/Users/HttpDatabase/ManagingDatabasesUsingHttp.mdpp b/Documentation/Books/Users/HttpDatabase/ManagingDatabasesUsingHttp.mdpp deleted file mode 100644 index ab3225645b..0000000000 --- a/Documentation/Books/Users/HttpDatabase/ManagingDatabasesUsingHttp.mdpp +++ /dev/null @@ -1,267 +0,0 @@ -!CHAPTER Managing Databases using HTTP - -`GET /_api/database/current`*(retrieves information about the current database)* - -!SUBSECTION Description - -Retrieves information about the current database -The response is a JSON object with the following attributes: - -* name: the name of the current database -* id: the id of the current database -* path: the filesystem path of the current database -* isSystem: whether or not the current database is the _system database - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the information was retrieved successfully. - -`HTTP 400` - -is returned if the request is invalid. - -`HTTP 404` - -is returned if the database could not be found. - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/database/current - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : { - "name" : "_system", - "id" : "123873", - "path" : "/tmp/vocdir.1653/databases/database-123873", - "isSystem" : true - }, - "error" : false, - "code" : 200 -} -``` - -`GET /_api/database/user`*(retrieves a list of all databases the current user can access)* - -!SUBSECTION Description - -Retrieves the list of all databases the current user can access without specifying a different username or password. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the list of database was compiled successfully. - -`HTTP 400` - -is returned if the request is invalid. - - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/database/user - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : [ - "_system" - ], - "error" : false, - "code" : 200 -} -``` - -`GET /_api/database`*(retrieves a list of all existing databases)* - -!SUBSECTION Description - -Retrieves the list of all existing databases -Note: retrieving the list of databases is only possible from within the _system database. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the list of database was compiled successfully. - -`HTTP 400` - -is returned if the request is invalid. - -`HTTP 403` - -is returned if the request was not executed in the _system database. - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/database - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : [ - "_system" - ], - "error" : false, - "code" : 200 -} -``` - -`POST /_api/database`*(creates a new database)* - -!SUBSECTION Body parameters - -`body (json,required)` - -The body with the name of the database. - -!SUBSECTION Description - -Creates a new database -The request body must be a JSON object with the attribute name. name must contain a valid [database name](../NamingConventions/DatabaseNames.md). - -The request body can optionally contain an attribute users, which then must be a list of user objects to initially create for the new database. 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 users is not specified or does not contain any users, a default user root will be created with an empty string password. This ensures that the new database will be accessible after it is created. - -The response is a JSON object with the attribute result set to true. - -*Note*: creating a new database is only possible from within the _system database. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the database was created successfully. - -`HTTP 400` - -is returned if the request parameters are invalid or if a database with the specified name already exists. - -`HTTP 403` - -is returned if the request was not executed in the _system database. - -`HTTP 409` - -is returned if a database with the specified name already exists. - -*Examples* - -Creating a database named example. - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database -{"name":"example"} - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : true, - "error" : false, - "code" : 201 -} -``` - -Creating a database named mydb with two users. - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/database -{"name":"mydb","users":[{"username":"admin","passwd":"secret","active":true},{"username":"tester","passwd":"test001","active":false}]} - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : true, - "error" : false, - "code" : 201 -} -``` - -`DELETE /_api/database/database-name`*(drops an existing database)* - -!SUBSECTION URL parameters - -`database-name (string,required)` - -The name of the database - -!SUBSECTION Description - -Deletes the database along with all data stored in it. -Note: dropping a database is only possible from within the _system database. The _system database itself cannot be dropped. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the database was dropped successfully. - -`HTTP 400` - -is returned if the request is malformed. - -`HTTP 403` - -is returned if the request was not executed in the _system database. - -`HTTP 404` - -is returned if the database could not be found. - -*Examples* - -``` -unix> curl -X DELETE --dump - http://localhost:8529/_api/database/example - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : true, - "error" : false, - "code" : 200 -} -``` - - - \ No newline at end of file diff --git a/Documentation/Books/Users/HttpDatabase/NotesOnDatabases.mdpp b/Documentation/Books/Users/HttpDatabase/NotesOnDatabases.mdpp index 00ab589bba..9dcf471ff5 100644 --- a/Documentation/Books/Users/HttpDatabase/NotesOnDatabases.mdpp +++ b/Documentation/Books/Users/HttpDatabase/NotesOnDatabases.mdpp @@ -10,7 +10,7 @@ in. A new database will only provide access to the system applications shipped with ArangoDB (that is the web interface at the moment) and no other Foxx applications until they are explicitly installed for the particular database. -**Database** +!SUBSECTION Database ArangoDB can handle multiple databases in the same server instance. Databases can be used to logically group and separate data. An ArangoDB database consists of collections and dedicated database-specific worker processes. A database contains its own collections (which cannot be accessed from other databases), Foxx applications and replication loggers and appliers. Each ArangoDB database contains its own system collections (e.g. _users, _replication, ...). @@ -19,12 +19,12 @@ There will always be at least one database in ArangoDB. This is the default data When ArangoDB is accessed via its HTTP REST API, the database name is read from the first part of the request URI path (e.g. /_db/_system/...). If the request URI does not contain a database name, the database name is automatically determined by the algorithm described in Database-to-Endpoint Mapping . -**Database Name** +!SUBSECTION Database Name A single ArangoDB instance can handle multiple databases in parallel. When multiple databases are used, each database must be given an unique name. This name is used to uniquely identify a database. The default database in ArangoDB is named _system. The database name is a string consisting of only letters, digits and the _ (underscore) and - (dash) characters. User-defined database names must always start with a letter. Database names are case-sensitive. -**Database Organization** +!SUBSECTION Database Organization A single ArangoDB instance can handle multiple databases in parallel. By default, there will be at least one database which is named _system. Databases are physically stored in separate sub-directories underneath the database directory, which itself resides in the instance's data directory. @@ -57,12 +57,3 @@ apps/ # the instance's application directory / # sub-directory for another database # sub-directory for a single application ```` - - - - -@copydoc GlossaryDatabase - -@copydoc GlossaryDatabaseName - -@copydoc GlossaryDatabaseOrganization diff --git a/Documentation/Books/Users/HttpDocument/AddressAndEtag.mdpp b/Documentation/Books/Users/HttpDocument/AddressAndEtag.mdpp index b7f996e04a..e258f3bfea 100644 --- a/Documentation/Books/Users/HttpDocument/AddressAndEtag.mdpp +++ b/Documentation/Books/Users/HttpDocument/AddressAndEtag.mdpp @@ -21,7 +21,7 @@ Example: http://localhost:8529/_db/mydb/_api/document/demo/362549736 -Note that the following examples use the short URL format for brevity. +**Note**: The following examples use the short URL format for brevity. Each document also has a document revision or etag with is returned in the "ETag" HTTP header when requesting a document. diff --git a/Documentation/Books/Users/HttpDocument/README.mdpp b/Documentation/Books/Users/HttpDocument/README.mdpp index 3bb4e8cefc..6a872c1298 100644 --- a/Documentation/Books/Users/HttpDocument/README.mdpp +++ b/Documentation/Books/Users/HttpDocument/README.mdpp @@ -8,7 +8,7 @@ Documents in ArangoDB are JSON objects. These objects can be nested (to any dept An example document: -*** +```js { "_id" : "myusers/2345678", "_key" : "3456789", @@ -25,7 +25,7 @@ An example document: "programming" ] } -*** +``` All documents contain special attributes: the document handle in *_id*, the document's unique key in *_key* and and the etag aka document revision in @@ -33,11 +33,11 @@ document's unique key in *_key* and and the etag aka document revision in creating a document. *_id* and *_key* values are immutable once the document has been created. The *_rev* value is maintained by ArangoDB autonomously. -*Document Handle* +!SUBSECTION Document Handle A document handle uniquely identifies a document in the database. It is a string and consists of the collection's name and the document key (_key attribute) separated by /. -*Document Key* +!SUBSECTION Document Key A document key uniquely identifies a document in a given collection. It can and should be used by clients when specific documents are searched. Document keys are stored in the _key attribute of documents. The key values are automatically indexed by ArangoDB in a collection's primary index. Thus looking up a document by its key is regularly a fast operation. The _key value of a document is immutable once the document has been created. By default, ArangoDB will auto-generate a document key if no _key attribute is specified, and use the user-specified _key otherwise. @@ -46,14 +46,14 @@ This behavior can be changed on a per-collection level by creating collections w Using keyOptions it is possible to disallow user-specified keys completely, or to force a specific regime for auto-generating the _key values. -*Document Revision* +!SUBSECTION Document Revision As ArangoDB supports MVCC, documents can exist in more than one revision. The document revision is the MVCC token used to identify a particular revision of a document. It is a string value currently containing an integer number and is unique within the list of document revisions for a single document. Document revisions can be used to conditionally update, replace or delete documents in the database. In order to find a particular revision of a document, you need the document handle and the document revision. ArangoDB currently uses 64bit unsigned integer values to maintain document revisions internally. When returning document revisions to clients, ArangoDB will put them into a string to ensure the revision id is not clipped by clients that do not support big integers. Clients should treat the revision id returned by ArangoDB as an opaque string when they store or use it locally. This will allow ArangoDB to change the format of revision ids later if this should be required. Clients can use revisions ids to perform simple equality/non-equality comparisons (e.g. to check whether a document has changed or not), but they should not use revision ids to perform greater/less than comparisons with them to check if a document revision is older than one another, even if this might work for some cases. -Note: Revision ids have been returned as integers up to including ArangoDB 1.1 +**Note**: Revision ids have been returned as integers up to including ArangoDB 1.1 -*Document Etag* +!SUBSECTION Document Etag The document revision enclosed in double quotes. The revision is returned by several HTTP API methods in the Etag HTTP header. diff --git a/Documentation/Books/Users/HttpDocument/WorkingWithDocuments.mdpp b/Documentation/Books/Users/HttpDocument/WorkingWithDocuments.mdpp index 4c6e92d386..7794428d88 100644 --- a/Documentation/Books/Users/HttpDocument/WorkingWithDocuments.mdpp +++ b/Documentation/Books/Users/HttpDocument/WorkingWithDocuments.mdpp @@ -1,845 +1,22 @@ !CHAPTER Working with Documents using REST -`GET /_api/document/document-handle`*(reads a document)* + +@startDocuBlock REST_DOCUMENT_READ -!SUBSECTION URL parameters + +@startDocuBlock REST_DOCUMENT_CREATE -`document-handle (string,required)` + +@startDocuBlock REST_DOCUMENT_REPLACE -The handle of the document. + +@startDocuBlock REST_DOCUMENT_UPDATE -!SUBSECTION HTTP header parameters + +@startDocuBlock REST_DOCUMENT_DELETE -`If-None-Match (string,optional)` + +@startDocuBlock REST_DOCUMENT_READ_HEAD -If the "If-None-Match" header is given, then it must contain exactly one etag. The document is returned, if it has a different revision than the given etag. Otherwise an *HTTP 304* is returned. - -`If-Match (string,optional)` - -If the "If-Match" header is given, then it must contain exactly one etag. The document is returned, if it has the same revision ad the given etag. Otherwise a *HTTP 412* is returned. As an alternative you can supply the etag in an attribute rev in the URL. - -!SUBSECTION Description - -Returns the document identified by *document-handle*. The returned document contains two special attributes: _id containing the document handle and _rev containing the revision. - -!SUBSECTION codes - -`HTTP 200` - -is returned if the document was found - -`HTTP 304` - -is returned if the "If-None-Match" header is given and the document has the same version - -`HTTP 404` - -is returned if the document or collection was not found - -`HTTP 412` - -is returned if a "If-Match" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned. - -*Examples* - -Use a document handle: - -``` -unix> curl --dump - http://localhost:8529/_api/document/products/272950241 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -etag: "272950241" - -{ - "hello" : "world", - "_id" : "products/272950241", - "_rev" : "272950241", - "_key" : "272950241" -} -``` - -Use a document handle and an etag: - -``` -unix> curl --header 'If-None-Match: "273474529"' --dump - http://localhost:8529/_api/document/products/273474529 -``` - -Unknown document handle: - -``` -unix> curl --dump - http://localhost:8529/_api/document/products/unknownhandle - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "errorMessage" : "document /_api/document/products/unknownhandle not found", - "code" : 404, - "errorNum" : 1202 -} -``` - -`POST /_api/document`*(creates a document)* - -!SUBSECTION Body parameters - -`document (json,required)` - -A JSON representation of the document. - -!SUBSECTION Query parameters - -`collection (string,required)` - -The collection name. - -`createCollection (boolean,optional)` - -If this parameter has a value of true or yes, then the collection is created if it does not yet exist. Other values will be ignored so the collection must be present for the operation to succeed. -*Note*: this flag is not supported in a cluster. Using it will result in an error. - -`waitForSync (boolean,optional)` - -Wait until document has been synced to disk. - -!SUBSECTION Description - -Creates a new document in the collection named collection. A JSON representation of the document must be passed as the body of the POST request. -If the document was created successfully, then the "Location" header contains the path to the newly created document. The "ETag" header field contains the revision of the document. - -The body of the response contains a JSON object with the following attributes: - -* _id contains the document handle of the newly created document -* _key contains the document key -* _rev contains the document revision - -If the collection parameter waitForSync is false, then the call returns as soon as the document has been accepted. It will not wait until the document has been synced to disk. - -Optionally, the URL parameter waitForSync 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 URL parameter can be used to force synchronization of just this 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 URL parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true. - -!SUBSECTION codes - -`HTTP 201` - -is returned if the document was created successfully and waitForSync was true. - -`HTTP 202` - -is returned if the document was created successfully and waitForSync was false. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a document. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Create a document given a collection named products. Note that the revision identifier might or might not by equal to the auto-generated key. - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products -{ "Hello": "World" } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 -etag: "271115233" -location: /_db/_system/_api/document/products/271115233 - -{ - "error" : false, - "_id" : "products/271115233", - "_rev" : "271115233", - "_key" : "271115233" -} -``` - -Create a document in a collection named products with a collection-level waitForSync value of false. - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products -{ "Hello": "World" } - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "271573985" -location: /_db/_system/_api/document/products/271573985 - -{ - "error" : false, - "_id" : "products/271573985", - "_rev" : "271573985", - "_key" : "271573985" -} -``` - -Create a document in a collection with a collection-level waitForSync value of false, but using the waitForSync URL parameter. - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products&waitForSync=true -{ "Hello": "World" } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 -etag: "272032737" -location: /_db/_system/_api/document/products/272032737 - -{ - "error" : false, - "_id" : "products/272032737", - "_rev" : "272032737", - "_key" : "272032737" -} -``` - -Create a document in a new, named collection - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products&createCollection=true -{ "Hello": "World" } - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "272491489" -location: /_db/_system/_api/document/products/272491489 - -{ - "error" : false, - "_id" : "products/272491489", - "_rev" : "272491489", - "_key" : "272491489" -} -``` - -Unknown collection name: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products -{ "Hello": "World" } - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "errorMessage" : "collection 'products' not found", - "code" : 404, - "errorNum" : 1203 -} -``` - -Illegal document: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/document?collection=products -{ 1: "World" } - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "errorMessage" : "expecting attribute name", - "code" : 400, - "errorNum" : 600 -} -````` - -`PUT /_api/document/document-handle`*(replaces a document)* - -!SUBSECTION Body parameters - -`document (json,required)` - -A JSON representation of the new document. - -!SUBSECTION URL parameters - -`document-handle (string,required)` - -The handle of the document. - -!SUBSECTION Query parameters - -`waitForSync (boolean,optional)` - -Wait until document has been synced to disk. - -`rev (string,optional)` - -You can conditionally replace a document based on a target revision id by using the rev URL parameter. - -`policy (string,optional)` - -To control the update behavior in case there is a revision mismatch, you can use the policy parameter (see below). - -!SUBSECTION HTTP header parameters - -`If-Match (string,optional)` - -You can conditionally replace a document based on a target revision id by using the if-match HTTP header. - -!SUBSECTION Description - -Completely updates (i.e. replaces) the document identified by document-handle. If the document exists and can be updated, then a HTTP 201 is returned and the "ETag" header field contains the new revision of the document. -If the new document passed in the body of the request contains the document-handle in the attribute _id and the revision in _rev, these attributes will be ignored. Only the URI and the "ETag" header are relevant in order to avoid confusion when using proxies. - -Optionally, the URL parameter waitForSync 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 URL 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 URL parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true. - -The body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the updated document, the attribute _rev contains the new document revision. - -If the document does not exist, then a HTTP 404 is returned and the body of the response contains an error document. - -There are two ways for specifying the targeted document revision id for conditional replacements (i.e. replacements that will only be executed if the revision id found in the database matches the document revision id specified in the request): - -* specifying the target revision in the rev URL query parameter -* specifying the target revision in the if-match HTTP header -* Specifying a target revision is optional, however, if done, only one of the described mechanisms must be used (either the rev URL parameter or the if-match HTTP header). Regardless which mechanism is used, the parameter needs to contain the target document revision id as returned in the _rev attribute of a document or by an HTTP etag header. - -For example, to conditionally replace a document based on a specific revision id, you can use the following request: - -`PUT /_api/document/document-handle?rev=etag` - -If a target revision id is provided in the request (e.g. via the etag value in the rev URL query parameter above), ArangoDB will check that the revision id of the document found in the database is equal to the target revision id provided in the request. If there is a mismatch between the revision id, then by default a HTTP 412 conflict is returned and no replacement is performed. - -The conditional update behavior can be overridden with the policy URL query parameter: - -`PUT /_api/document/document-handle?policy=policy` - -If policy is set to error, then the behavior is as before: replacements will fail if the revision id found in the database does not match the target revision id specified in the request. - -If policy is set to last, then the replacement will succeed, even if the revision id found in the database does not match the target revision id specified in the request. You can use the last policy to force replacements. - -!SUBSECTION codes - -`HTTP 201` - -is returned if the document was replaced successfully and waitForSync was true. - -`HTTP 202` - -is returned if the document was replaced successfully and waitForSync was false. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a document. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection or the document was not found - -`HTTP 412` - -is returned if a "If-Match" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned. - -*Examples* - -Using document handle: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/275768289 -{"Hello": "you"} - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "276095969" -location: /_db/_system/_api/document/products/275768289 - -{ - "error" : false, - "_id" : "products/275768289", - "_rev" : "276095969", - "_key" : "275768289" -} -``` - -Unknown document handle: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/276554721 -{} - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "errorMessage" : "document /_api/document/products/276554721 not found", - "code" : 404, - "errorNum" : 1202 -} -``` - -Produce a revision conflict: - -``` -unix> curl -X PUT --header 'If-Match: "277668833"' --data-binary @- --dump - http://localhost:8529/_api/document/products/277341153 -{"other":"content"} - -HTTP/1.1 412 Precondition Failed -content-type: application/json; charset=utf-8 -etag: "277341153" - -{ - "error" : true, - "code" : 412, - "errorNum" : 1200, - "errorMessage" : "precondition failed", - "_id" : "products/277341153", - "_rev" : "277341153", - "_key" : "277341153" -} -``` - -Last write wins: - -``` -unix> curl -X PUT --header 'If-Match: "278651873"' --data-binary @- --dump - http://localhost:8529/_api/document/products/278324193?policy=last -{} - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "278914017" -location: /_db/_system/_api/document/products/278324193 - -{ - "error" : false, - "_id" : "products/278324193", - "_rev" : "278914017", - "_key" : "278324193" -} -``` - -Alternative to header field: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/document/products/279372769?rev=279700449 -{"other":"content"} - -HTTP/1.1 412 Precondition Failed -content-type: application/json; charset=utf-8 -etag: "279372769" - -{ - "error" : true, - "code" : 412, - "errorNum" : 1200, - "errorMessage" : "precondition failed", - "_id" : "products/279372769", - "_rev" : "279372769", - "_key" : "279372769" -} -``` - -`PATCH /_api/document/document-handle`*(patches a document)* - -!SUBSECTION Body parameters - -`document (json,required)` - -A JSON representation of the document update. - -!SUBSECTION URL parameters - -`document-handle (string,required)` - -The handle of the document. - -!SUBSECTION Query parameters - -`keepNull (boolean,optional)` - -If the intention is to delete existing attributes with the patch command, the URL query parameter keepNull can be used with a value of false. This will modify the behavior of the patch command to remove any attributes from the existing document that are contained in the patch document with an attribute value of null. - -`waitForSync (boolean,optional)` - -Wait until document has been synced to disk. - -`rev (string,optional)` - -You can conditionally patch a document based on a target revision id by using the rev URL parameter. - -`policy (string,optional)` - -To control the update behavior in case there is a revision mismatch, you can use the policy parameter. - -!SUBSECTION HTTP header parameters - -`If-Match (string,optional)` - -You can conditionally patch a document based on a target revision id by using the if-match HTTP header. - -!SUBSECTION Description - -Partially updates the document identified by document-handle. The body of the request must contain a JSON document with the attributes to patch (the patch document). All attributes from the patch document will be added to the existing document if they do not yet exist, and overwritten in the existing document if they do exist there. -Setting an attribute value to null in the patch document will cause a value of null be saved for the attribute by default. - -Optionally, the URL parameter waitForSync 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 URL 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 URL parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true. - -The body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the updated document, the attribute _rev contains the new document revision. - -If the document does not exist, then a HTTP 404 is returned and the body of the response contains an error document. - -You can conditionally update a document based on a target revision id by using either the rev URL parameter or the if-match HTTP header. To control the update behavior in case there is a revision mismatch, you can use the policy parameter. This is the same as when replacing documents (see replacing documents for details). - -!SUBSECTION codes - -`HTTP 201` - -is returned if the document was created successfully and waitForSync was true. - -`HTTP 202` - -is returned if the document was created successfully and waitForSync was false. -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a document. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection or the document was not found - -`HTTP 412` - -is returned if a "If-Match" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned. - -*Examples* - -patches an existing document with new content. - -``` -unix> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/280355809 -{"hello":"world"} - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "280683489" -location: /_db/_system/_api/document/products/280355809 - -{ - "error" : false, - "_id" : "products/280355809", - "_rev" : "280683489", - "_key" : "280355809" -} - -unix> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/280355809 -{"numbers":{"one":1,"two":2,"three":3,"empty":null}} - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "281273313" -location: /_db/_system/_api/document/products/280355809 - -{ - "error" : false, - "_id" : "products/280355809", - "_rev" : "281273313", - "_key" : "280355809" -} - -unix> curl --dump - http://localhost:8529/_api/document/products/280355809 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -etag: "281273313" - -{ - "one" : "world", - "hello" : "world", - "numbers" : { - "empty" : null, - "one" : 1, - "two" : 2, - "three" : 3 - }, - "_id" : "products/280355809", - "_rev" : "281273313", - "_key" : "280355809" -} - -unix> curl -X PATCH --data-binary @- --dump - http://localhost:8529/_api/document/products/280355809?keepNull=false -{"hello":null,"numbers":{"four":4}} - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "281732065" -location: /_db/_system/_api/document/products/280355809 - -{ - "error" : false, - "_id" : "products/280355809", - "_rev" : "281732065", - "_key" : "280355809" -} - -unix> curl --dump - http://localhost:8529/_api/document/products/280355809 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -etag: "281732065" - -{ - "one" : "world", - "numbers" : { - "empty" : null, - "one" : 1, - "two" : 2, - "three" : 3, - "four" : 4 - }, - "_id" : "products/280355809", - "_rev" : "281732065", - "_key" : "280355809" -} -``` - -modifies a document, coordinator case in a cluster - -`DELETE /_api/document/document-handle`*(deletes a document)* - -!SUBSECTION URL parameters - -`document-handle (string,required)` - -Deletes the document identified by document-handle. - -!SUBSECTION Query parameters - -`rev (string,optional)` - -You can conditionally delete a document based on a target revision id by using the rev URL parameter. - -`policy (string,optional)` - -To control the update behavior in case there is a revision mismatch, you can use the policy parameter. This is the same as when replacing documents (see replacing documents for more details). - -`waitForSync (boolean,optional)` - -Wait until document has been synced to disk. - -!SUBSECTION HTTP header parameters - -`If-Match (string,optional)` - -You can conditionally delete a document based on a target revision id by using the if-match HTTP header. - -!SUBSECTION Description - -The body of the response contains a JSON object with the information about the handle and the revision. The attribute _id contains the known document-handle of the deleted document, the attribute _rev contains the document revision. -If the waitForSync parameter is not specified or set to false, then the collection's default waitForSync behavior is applied. The waitForSync URL parameter cannot be used to disable synchronization for collections that have a default waitForSync value of true. - -!SUBSECTION codes - -`HTTP 200` - -is returned if the document was deleted successfully and waitForSync was true. - -`HTTP 202` - -is returned if the document was deleted successfully and waitForSync was false. - -`HTTP 404` - -is returned if the collection or the document was not found. The response body contains an error document in this case. - -`HTTP 412` - -is returned if a "If-Match" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the _rev attribute. Additionally, the attributes _id and _key will be returned. - -*Examples* - -Using document handle: - -``` -unix> curl -X DELETE --dump - http://localhost:8529/_api/document/products/282256353 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "error" : false, - "_id" : "products/282256353", - "_rev" : "282256353", - "_key" : "282256353" -} -```` - -Unknown document handle: - -``` -unix> curl -X DELETE --dump - http://localhost:8529/_api/document/products/282911713 - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "errorMessage" : "document /_api/document/products/282911713 not found", - "code" : 404, - "errorNum" : 1202 -} -```` - -Revision conflict: - -``` -unix> curl -X DELETE --header 'If-Match: "284484577"' --dump - http://localhost:8529/_api/document/products/284156897 - -HTTP/1.1 412 Precondition Failed -content-type: application/json; charset=utf-8 -etag: "284156897" - -{ - "error" : true, - "code" : 412, - "errorNum" : 1200, - "errorMessage" : "precondition failed", - "_id" : "products/284156897", - "_rev" : "284156897", - "_key" : "284156897" -} -``` - -`HEAD /_api/document/document-handle`*(reads a document header)* - -!SUBSECTION URL parameters - -`document-handle (string,required)` - -The handle of the document. - -!SUBSECTION Query parameters - -`rev (string,optional)` - -You can conditionally fetch a document based on a target revision id by using the rev URL parameter. - -!SUBSECTION HTTP header parameters - -`If-None-Match (string,optional)` - -If the "If-None-Match" header is given, then it must contain exactly one etag. If the current document revision is different to the specified etag, an HTTP 200 response is returned. If the current document revision is identical to the specified etag, then an HTTP 304 is returned. - -`If-Match (string,optional)` - -You can conditionally fetch a document based on a target revision id by using the if-match HTTP header. - -!SUBSECTION Description - -Like GET, but only returns the header fields and not the body. You can use this call to get the current revision of a document or check if the document was deleted. - -!SUBSECTION codes - -`HTTP 200` - -is returned if the document was found - -`HTTP 304` - -is returned if the "If-None-Match" header is given and the document has same version - -`HTTP 404` - -is returned if the document or collection was not found - -`HTTP 412` - -is returned if a "If-Match" header or rev is given and the found document has a different version. The response will also contain the found document's current revision in the etag header. - -*Examples* - -``` -unix> curl -X HEAD --dump - http://localhost:8529/_api/document/products/275244001 -``` - -`GET /_api/document`*(reads all documents from collection)* - -!SUBSECTION Query parameters - -`collection (string,required)` - -The name of the collection. - -!SUBSECTION Description - -Returns a list of all URI for all documents from the collection identified by collection. - -!SUBSECTION codes - -`HTTP 200` - -All went good. - -`HTTP 404` - -The collection does not exist. - -*Examples* - -Returns a all ids. - -``` -unix> curl --dump - http://localhost:8529/_api/document/?collection=products - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "documents" : [ - "/_api/document/products/274392033", - "/_api/document/products/274719713", - "/_api/document/products/274064353" - ] -} -``` - -Collection does not exist. - -``` -unix> curl --dump - http://localhost:8529/_api/document/?collection=doesnotexist - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "errorMessage" : "collection 'doesnotexist' not found", - "code" : 404, - "errorNum" : 1203 -} -``` - - \ No newline at end of file + +@startDocuBlock REST_DOCUMENT_READ_ALL \ No newline at end of file diff --git a/Documentation/Books/Users/HttpEdge/AddressAndEtag.mdpp b/Documentation/Books/Users/HttpEdge/AddressAndEtag.mdpp index 255db3792d..40a812139b 100644 --- a/Documentation/Books/Users/HttpEdge/AddressAndEtag.mdpp +++ b/Documentation/Books/Users/HttpEdge/AddressAndEtag.mdpp @@ -21,9 +21,9 @@ the following URL schema: http://server:port/_db//_api/edge/ -Example: +*Example*: http://localhost:8529/_db/mydb/_api/edge/demo/362549736 -Note that the following examples use the short URL format for brevity. +**Note**: that the following examples use the short URL format for brevity. diff --git a/Documentation/Books/Users/HttpEdge/README.mdpp b/Documentation/Books/Users/HttpEdge/README.mdpp index 98e389c307..13dccb7ff1 100644 --- a/Documentation/Books/Users/HttpEdge/README.mdpp +++ b/Documentation/Books/Users/HttpEdge/README.mdpp @@ -10,7 +10,8 @@ A graph data model always consists of two collections: the relations between the nodes in the graphs are stored in an "edges collection", the nodes in the graph are stored in documents in regular collections. -Example: +*Example*: + - the "edge" collection stores the information that a company's reception is sub-unit to the services unit and the services unit is sub-unit to the CEO. You would express this relationship with the *to* and *_to* attributes diff --git a/Documentation/Books/Users/HttpEdge/WorkingWithEdges.mdpp b/Documentation/Books/Users/HttpEdge/WorkingWithEdges.mdpp index f378a6a446..5b7d212241 100644 --- a/Documentation/Books/Users/HttpEdge/WorkingWithEdges.mdpp +++ b/Documentation/Books/Users/HttpEdge/WorkingWithEdges.mdpp @@ -1,291 +1,32 @@ !CHAPTER Working with Edges using REST -`GET /_api/edge`*(reads an edge)* - -*GET /_api/edge/document-handle* +!SUBSECTION Read edge +`GET /_api/edge` See [HTTP Interface for Documents](../HttpDocuments/README.md) for details. -`POST /_api/edge`*(creates an edge)* + +@startDocuBlock API_EDGE_CREATE -!SUBSECTION Body parameters - -`edge-document (json,required)` - -A JSON representation of the edge document must be passed as the body of the POST request. This JSON object may contain the edge's document key in the _key attribute if needed. -Query parameters - -`collection (string,required)` - -Creates a new edge in the collection identified by collection name. - -`createCollection (boolean,optional)` - -If this parameter has a value of true or yes, then the collection is created if it does not yet exist. Other values will be ignored so the collection must be present for the operation to succeed. -*Note*: this flag is not supported in a cluster. Using it will result in an error. - -`waitForSync (boolean,optional)` - -Wait until the edge document has been synced to disk. - -`from (string,required)` - -The document handle of the start point must be passed in from handle. - -`to (string,required)` - -The document handle of the end point must be passed in to handle. - -!SUBSECTION Description - -Creates a new edge document in the collection named collection. A JSON representation of the document must be passed as the body of the POST request. -The from and to handles are immutable once the edge has been created. - -In all other respects the method works like POST /document, see HTTP Interface for Documents for details. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the edge was created successfully and waitForSync was true. - -`HTTP 202` - -is returned if the edge was created successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of an edge, or if the collection specified is not an edge collection. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Create an edge and read it back: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/edge/?collection=edges&from=vertices/1&to=vertices/2 -{"name":"Emil"} - -HTTP/1.1 202 Accepted -content-type: application/json; charset=utf-8 -etag: "287040481" -location: /_db/_system/_api/document/edges/287040481 - -{ - "error" : false, - "_id" : "edges/287040481", - "_rev" : "287040481", - "_key" : "287040481" -} - -unix> curl --dump - http://localhost:8529/_api/edge/edges/287040481 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 -etag: "287040481" - -{ - "name" : "Emil", - "_id" : "edges/287040481", - "_rev" : "287040481", - "_key" : "287040481", - "_from" : "vertices/1", - "_to" : "vertices/2" -} -``` - -`PUT /_api/edge`*(updates an edge)* - -`PUT /_api/edge/document-handle` +!SUBSECTION Update edge +`PUT /_api/edge` See [HTTP Interface for Documents](../HttpDocuments/README.md) for details. - -`PATCH /_api/edge`*(partially updates an edge)* - -*PATCH /_api/edge/document-handle* +!SUBSECTION Partially Update Edge +`PATCH /_api/edge` See [HTTP Interface for Documents](../HttpDocuments/README.md) for details. - -`DELETE /_api/edge`*(deletes an edge)* - -`DELETE /_api/edge/document-handle` +!SUBSECTION Delete edge +`DELETE /_api/edge` See [HTTP Interface for Documents](../HttpDocuments/README.md) for details. - -`HEAD /_api/edge`*(reads an edge header)* - -`HEAD /_api/edge/document-handle` +!SUBSECTION Read edge header +`HEAD /_api/edge` See [HTTP Interface for Documents](../HttpDocuments/README.md) for details. - -`GET /_api/edges/{collection-id}`*(reads in- or outbound edges)* - -!SUBSECTION URL parameters - -`collection-id (string,required)` - -The id of the collection. - -!SUBSECTION Query parameters - -`vertex (string,required)` - -The id of the start vertex. - -`direction (string,optional)` - -Selects in or out direction for edges. If not set, any edges are returned. - -!SUBSECTION Description - -Returns the list of edges starting or ending in the vertex identified by vertex-handle. - -*Examples* - -Any direction - -``` -unix> curl --dump - http://localhost:8529/_api/edges/edges?vertex=vertices/1 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "edges" : [ - { - "_id" : "edges/6", - "_rev" : "92660705", - "_key" : "6", - "_from" : "vertices/2", - "_to" : "vertices/1", - "$label" : "v2 -> v1" - }, - { - "_id" : "edges/7", - "_rev" : "93119457", - "_key" : "7", - "_from" : "vertices/4", - "_to" : "vertices/1", - "$label" : "v4 -> v1" - }, - { - "_id" : "edges/5", - "_rev" : "92201953", - "_key" : "5", - "_from" : "vertices/1", - "_to" : "vertices/3", - "$label" : "v1 -> v3" - } - ], - "error" : false, - "code" : 200 -} -``` - -In edges - -``` -unix> curl --dump - http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=in - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "edges" : [ - { - "_id" : "edges/6", - "_rev" : "97182689", - "_key" : "6", - "_from" : "vertices/2", - "_to" : "vertices/1", - "$label" : "v2 -> v1" - }, - { - "_id" : "edges/7", - "_rev" : "97641441", - "_key" : "7", - "_from" : "vertices/4", - "_to" : "vertices/1", - "$label" : "v4 -> v1" - } - ], - "error" : false, - "code" : 200 -} -``` - -Out edges - -``` -unix> curl --dump - http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=out - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "edges" : [ - { - "_id" : "edges/5", - "_rev" : "101245921", - "_key" : "5", - "_from" : "vertices/1", - "_to" : "vertices/3", - "$label" : "v1 -> v3" - } - ], - "error" : false, - "code" : 200 -} -``` - - - - + +@startDocuBlock API_EDGE_READINOUTBOUND diff --git a/Documentation/Books/Users/HttpGharial/Management.mdpp b/Documentation/Books/Users/HttpGharial/Management.mdpp index 9becf19241..78a147e742 100644 --- a/Documentation/Books/Users/HttpGharial/Management.mdpp +++ b/Documentation/Books/Users/HttpGharial/Management.mdpp @@ -70,6 +70,12 @@ Removes a graph from the collection *\_graphs*. @RESTPARAM{graph-name, string, required} The name of the graph. +@RESTQUERYPARAMS + +@RESTPARAM{dropCollections, boolean, optional} +Drop collections of this graph as well. +Collections will only be dropped if they are not used in other graphs. + @RESTRETURNCODES @RESTRETURNCODE{200} @@ -146,6 +152,12 @@ The name of the graph. @RESTPARAM{collection-name, string, required} The name of the vertex collection. +@RESTQUERYPARAMS + +@RESTPARAM{dropCollection, boolean, optional} +Drop the collection as well. +Collection will only be dropped if it is not used in other graphs. + @RESTRETURNCODES @RESTRETURNCODE{200} @@ -285,6 +297,12 @@ The name of the graph. @RESTPARAM{definition-name, string, required} The name of the edge collection used in the definition. +@RESTQUERYPARAMS + +@RESTPARAM{dropCollection, boolean, optional} +Drop the collection as well. +Collection will only be dropped if it is not used in other graphs. + @RESTRETURNCODES @RESTRETURNCODE{200} diff --git a/Documentation/Books/Users/HttpIndexes/Address.mdpp b/Documentation/Books/Users/HttpIndexes/Address.mdpp deleted file mode 100644 index 43b79f5f8a..0000000000 --- a/Documentation/Books/Users/HttpIndexes/Address.mdpp +++ /dev/null @@ -1,11 +0,0 @@ -!CHAPTER Address of an Index - -All indexes in ArangoDB have an unique handle. This index handle identifies an -index and is managed by ArangoDB. All indexes are found under the URI - - http://server:port/_api/index/index-handle - -For example: Assume that the index handle is *demo/63563528* then the URL of -that index is: - - http://localhost:8529/_api/index/demo/63563528 diff --git a/Documentation/Books/Users/HttpIndexes/Cap.mdpp b/Documentation/Books/Users/HttpIndexes/Cap.mdpp index c403769d74..6125e09e47 100644 --- a/Documentation/Books/Users/HttpIndexes/Cap.mdpp +++ b/Documentation/Books/Users/HttpIndexes/Cap.mdpp @@ -1,125 +1,4 @@ !CHAPTER Working with Cap Constraints -`POST /_api/index`*(creates a cap constraint)* - -!SUBSECTION Query parameters - -`collection (string,required)` - -The collection name. - -!SUBSECTION Body parameters - -`cap-constraint (json,required)` - -!SUBSECTION Description - -Creates a cap constraint for the collection collection-name, if it does not already exist. Expects an object containing the index details. - -* type: must be equal to "cap". -* size: The maximal number of documents for the collection. If specified, the value must be greater than zero. -* byteSize: The maximal size of the active document data in the collection (in bytes). If specified, the value must be at least 16384. -*Note* that the cap constraint does not index particular attributes of the documents in a collection, but limits the number of documents in the collection to a maximum value. The cap constraint thus does not support attribute names specified in the fields attribute nor uniqueness of any kind via the unique attribute. - -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. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index already exists, then an HTTP 200 is returned. - -`HTTP 201` - -If the index does not already exist and could be created, then an HTTP 201 is returned. - -`HTTP 400` - -If either size or byteSize contain invalid values, then an HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Creating a cap constraint - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/index?collection=products -{"type":"cap","size":10} - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "id" : "products/169927649", - "type" : "cap", - "unique" : false, - "size" : 10, - "byteSize" : 0, - "isNewlyCreated" : true, - "error" : false, - "code" : 201 -} -``` - - - \ No newline at end of file + +@startDocuBlock JSF_post_api_index_cap diff --git a/Documentation/Books/Users/HttpIndexes/Fulltext.mdpp b/Documentation/Books/Users/HttpIndexes/Fulltext.mdpp index d3ce58b164..722c50f9d5 100644 --- a/Documentation/Books/Users/HttpIndexes/Fulltext.mdpp +++ b/Documentation/Books/Users/HttpIndexes/Fulltext.mdpp @@ -2,131 +2,8 @@ If a fulltext index exists, then /_api/simple/fulltext will use this index to execute the specified fulltext query. -`POST /_api/index`*(creates a fulltext index)* + +@startDocuBlock JSF_post_api_index_fulltext -!SUBSECTION Query parameters - -`collection-name (string,required)` - -The collection name. - -!SUBSECTION Body parameters - -`index-details (json,required)` - -!SUBSECTION Description - -Creates a fulltext index for the collection collection-name, if it does not already exist. The call expects an object containing the index details. - -* type: must be equal to "fulltext". -* fields: A list of attribute names. Currently, the list is limited to exactly one attribute, so the value of fields should look like this for example: [ "text" ]. -* minLength: Minimum character length of words to index. Will default to a server-defined value if unspecified. It is thus recommended to set this value explicitly when creating the index. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index already exists, then a HTTP 200 is returned. - -`HTTP 201` - -If the index does not already exist and could be created, then a HTTP 201 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Creating a fulltext index: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/index?collection=products -{ "type" : "fulltext", "fields" : [ "text" ] } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "id" : "products/172155873", - "type" : "fulltext", - "unique" : false, - "minLength" : 2, - "fields" : [ - "text" - ], - "isNewlyCreated" : true, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/fulltext`*(executes a fulltext index query)* - -!SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -!SUBSECTION Description - -This will find all documents from the collection that match the fulltext query specified in query. - -In order to use the fulltext operator, a fulltext index must be defined for the collection and the specified attribute. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* attribute: The attribute that contains the texts. -* query: The fulltext query. -* skip: The number of documents to skip in the query (optional). -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional) -* index: The identifier of the fulltext-index to use. - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/fulltext -{ "collection": "products", "attribute" : "text", "query" : "word" } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/190571489", - "_rev" : "190571489", - "_key" : "190571489", - "text" : "this text contains word" - }, - { - "_id" : "products/190768097", - "_rev" : "190768097", - "_key" : "190768097", - "text" : "this text also has a word" - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` \ No newline at end of file + +@startDocuBlock JSA_put_api_simple_fulltext \ No newline at end of file diff --git a/Documentation/Books/Users/HttpIndexes/Geo.mdpp b/Documentation/Books/Users/HttpIndexes/Geo.mdpp index e248824c54..0217ef0c6f 100644 --- a/Documentation/Books/Users/HttpIndexes/Geo.mdpp +++ b/Documentation/Books/Users/HttpIndexes/Geo.mdpp @@ -1,363 +1,10 @@ !CHAPTER Working with Geo Indexes -`POST /_api/index`*(creates a geo-spatial index)* + +@startDocuBlock JSF_post_api_index_geo -!SUBSECTION Query parameters + +@startDocuBlock JSA_put_api_simple_near -`collection (string,required)` - -The collection name. - -!SUBSECTION Body parameters - -`index-details (json,required)` - -!SUBSECTION Description - -Creates a geo-spatial index in the collection collection-name, if it does not already exist. Expects an object containing the index details. - -* type: must be equal to "geo". -* fields: A list with one or two attribute paths. - -If it is a list with one attribute path location, then a geo-spatial index on all documents is created using location as path to the coordinates. The value of the attribute must be a list with at least two double values. The list must contain the latitude (first value) and the longitude (second value). All documents, which do not have the attribute path or with value that are not suitable, are ignored. - -If it is a list with two attribute paths latitude and longitude, then a geo-spatial index on all documents is created using latitude and longitude as paths the latitude and the longitude. The value of the attribute latitude and of the attribute longitude must a double. All documents, which do not have the attribute paths or which values are not suitable, are ignored. - -* geoJson: If a geo-spatial index on a location is constructed and geoJson is true, then the order within the list is longitude followed by latitude. This corresponds to the format described in http://geojson.org/geojson-spec.html#positions -* constraint: If constraint is true, then a geo-spatial constraint is created. The constraint is a non-unique variant of the index. Note that it is also possible to set the unique attribute instead of the constraint attribute. -* ignoreNull: If a geo-spatial constraint is created and ignoreNull is true, then documents with a null in location or at least one null in latitude or longitude are ignored. - -*Note*: unique indexes on non-shard keys are not supported in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index already exists, then a HTTP 200 is returned. - -`HTTP 201` - -If the index does not already exist and could be created, then a HTTP 201 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Creating a geo index with a location attribute: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/index?collection=products -{ "type": "geo", "fields" : [ "b" ] } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "id" : "products/170255329", - "type" : "geo1", - "unique" : false, - "geoJson" : false, - "constraint" : false, - "ignoreNull" : false, - "fields" : [ - "b" - ], - "isNewlyCreated" : true, - "error" : false, - "code" : 201 -} -``` - -Creating a geo index with latitude and longitude attributes: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/index?collection=products -{ "type": "geo", "fields" : [ "e", "f" ] } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "id" : "products/170648545", - "type" : "geo2", - "unique" : false, - "constraint" : false, - "ignoreNull" : false, - "fields" : [ - "e", - "f" - ], - "isNewlyCreated" : true, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/near`*(executes a near query)* - -!SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -!SUBSECTION Description - -The default will find at most 100 documents near the given coordinate. The returned list is sorted according to the distance, with the nearest document being first in the list. If there are near documents of equal distance, documents are chosen randomly from this set until the limit is reached. - -In order to use the near operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the geo field to select a particular index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* latitude: The latitude of the coordinate. -* longitude: The longitude of the coordinate. -* distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional) -* geo: If given, the identifier of the geo-index to use. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Without distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 2 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/180478945", - "_rev" : "180478945", - "_key" : "180478945", - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/180085729", - "_rev" : "180085729", - "_key" : "180085729", - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -With distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 3, "distance" : "distance" } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/182969313", - "_rev" : "182969313", - "_key" : "182969313", - "distance" : 222.38985328911744, - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - }, - { - "_id" : "products/183362529", - "_rev" : "183362529", - "_key" : "183362529", - "distance" : 222.38985328911744, - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/182772705", - "_rev" : "182772705", - "_key" : "182772705", - "distance" : 444.779706578235, - "name" : "Name/-0.004/", - "loc" : [ - -0.004, - 0 - ] - } - ], - "hasMore" : false, - "count" : 3, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/within`*(executes a within query)* - -!SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -!SUBSECTION Description - -This will find all documents within a given radius around the coordinate (latitude, longitude). The returned list is sorted by distance. - -In order to use the within operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the geo field to select a particular index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* latitude: The latitude of the coordinate. -* longitude: The longitude of the coordinate. -* radius: The maximal radius (in meters). -* distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional) -* geo: If given, the identifier of the geo-index to use. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Without distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 2, "radius" : 500 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/186246113", - "_rev" : "186246113", - "_key" : "186246113", - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/185852897", - "_rev" : "185852897", - "_key" : "185852897", - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -With distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 3, "distance" : "distance", "radius" : 300 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/188736481", - "_rev" : "188736481", - "_key" : "188736481", - "distance" : 222.38985328911744, - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - }, - { - "_id" : "products/189129697", - "_rev" : "189129697", - "_key" : "189129697", - "distance" : 222.38985328911744, - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/188539873", - "_rev" : "188539873", - "_key" : "188539873", - "distance" : 444.779706578235, - "name" : "Name/-0.004/", - "loc" : [ - -0.004, - 0 - ] - } - ], - "hasMore" : false, - "count" : 3, - "error" : false, - "code" : 201 -} -``` \ No newline at end of file + +@startDocuBlock JSA_put_api_simple_within \ No newline at end of file diff --git a/Documentation/Books/Users/HttpIndexes/Hash.mdpp b/Documentation/Books/Users/HttpIndexes/Hash.mdpp index df9624f89f..b158834fef 100644 --- a/Documentation/Books/Users/HttpIndexes/Hash.mdpp +++ b/Documentation/Books/Users/HttpIndexes/Hash.mdpp @@ -1,328 +1,12 @@ - !CHAPTER Working with Hash Indexes If a suitable hash index exists, then */_api/simple/by-example* will use this index to execute a query-by-example. -`POST /_api/index`*(creates a hash index)* + +@startDocuBlock JSF_post_api_index_hash -!SUBSECTION Query parameters + +@startDocuBlock JSA_put_api_simple_by_example -`collection-name (string,required)` - -The collection name. - -!SUBSECTION Body parameters - -`index-details (json,required)` - -!SUBSECTION Description - -Creates a hash index for the collection collection-name, if it does not already exist. The call expects an object containing the index details. - -* type: must be equal to "hash". -* fields: A list of attribute paths. -* unique: If true, then create a unique index. - -*Note*: unique indexes on non-shard keys are not supported in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index already exists, then a HTTP 200 is returned. - -`HTTP 201` - -If the index does not already exist and could be created, then a HTTP 201 is returned. - -`HTTP 400` - -If the collection already contains documents and you try to create a unique hash index in such a way that there are documents violating the uniqueness, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Creating an unique constraint: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/index?collection=products -{ "type": "hash", "unique" : true, "fields" : [ "a", "b" ] } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "id" : "products/171041761", - "type" : "hash", - "unique" : true, - "fields" : [ - "a", - "b" - ], - "isNewlyCreated" : true, - "error" : false, - "code" : 201 -} -``` - -Creating a hash index: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/index?collection=products -{ "type": "hash", "unique" : false, "fields" : [ "a", "b" ] } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "id" : "products/171434977", - "type" : "hash", - "unique" : false, - "fields" : [ - "a", - "b" - ], - "isNewlyCreated" : true, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/by-example`*(executes simple query by-example)* - -!SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -!SUBSECTION Description - -This will find all documents matching a given example. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* example: The example document. -* skip: The number of documents to skip in the query (optional). -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Matching an attribute: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/by-example -{ "collection": "products", "example" : { "i" : 1 } } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/192013281", - "_rev" : "192013281", - "_key" : "192013281", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - }, - { - "_id" : "products/192340961", - "_rev" : "192340961", - "_key" : "192340961", - "i" : 1, - "a" : { - "j" : 1 - } - }, - { - "_id" : "products/192603105", - "_rev" : "192603105", - "_key" : "192603105", - "i" : 1 - }, - { - "_id" : "products/192799713", - "_rev" : "192799713", - "_key" : "192799713", - "i" : 1, - "a" : { - "k" : 2, - "j" : 2 - } - } - ], - "hasMore" : false, - "count" : 4, - "error" : false, - "code" : 201 -} -``` - -Matching an attribute which is a sub-document: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/by-example -{ "collection": "products", "example" : { "a.j" : 1 } } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/194307041", - "_rev" : "194307041", - "_key" : "194307041", - "i" : 1, - "a" : { - "j" : 1 - } - }, - { - "_id" : "products/193979361", - "_rev" : "193979361", - "_key" : "193979361", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -Matching an attribute within a sub-document: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/by-example -{ "collection": "products", "example" : { "a" : { "j" : 1 } } } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/196273121", - "_rev" : "196273121", - "_key" : "196273121", - "i" : 1, - "a" : { - "j" : 1 - } - } - ], - "hasMore" : false, - "count" : 1, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/first-example`*(returns a document matching an example)* - -!SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -!SUBSECTION Description - -This will return the first document matching a given example. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* example: The example document. - -Returns a result containing the document or HTTP 404 if no document matched the example. - -If more than one document in the collection matches the specified example, only one of these documents will be returned, and it is undefined which of the matching documents is returned. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned when the query was successfully executed. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -If a matching document was found: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/first-example -{ "collection": "products", "example" : { "i" : 1 } } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "document" : { - "_id" : "products/197911521", - "_rev" : "197911521", - "_key" : "197911521", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - }, - "error" : false, - "code" : 200 -} -``` - -If no document was found: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/first-example -{ "collection": "products", "example" : { "l" : 1 } } - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 404, - "errorNum" : 404, - "errorMessage" : "no match" -} -``` \ No newline at end of file + +@startDocuBlock JSA_put_api_simple_first_example diff --git a/Documentation/Books/Users/HttpIndexes/README.mdpp b/Documentation/Books/Users/HttpIndexes/README.mdpp index cd2d9fad97..0fa4e95933 100644 --- a/Documentation/Books/Users/HttpIndexes/README.mdpp +++ b/Documentation/Books/Users/HttpIndexes/README.mdpp @@ -38,3 +38,14 @@ A fulltext index can be used to find words, or prefixes of words inside document The basic operations (create, read, update, delete) for documents are mapped to the standard HTTP methods (*POST*, *GET*, *PUT*, *DELETE*). +!SECTION Address of an Index + +All indexes in ArangoDB have an unique handle. This index handle identifies an +index and is managed by ArangoDB. All indexes are found under the URI + + http://server:port/_api/index/index-handle + +For example: Assume that the index handle is *demo/63563528* then the URL of +that index is: + + http://localhost:8529/_api/index/demo/63563528 diff --git a/Documentation/Books/Users/HttpIndexes/Skiplist.mdpp b/Documentation/Books/Users/HttpIndexes/Skiplist.mdpp index d239bd947d..fa0fbcc2f5 100644 --- a/Documentation/Books/Users/HttpIndexes/Skiplist.mdpp +++ b/Documentation/Books/Users/HttpIndexes/Skiplist.mdpp @@ -2,136 +2,5 @@ If a suitable skip-list index exists, then /_api/simple/range will use this index to execute a range query. -`POST /_api/index`*(creates a skip list)* - -!SUBSECTION Query parameters - -`collection-name (string,required)` - -The collection name. - -!SUBSECTION Body parameters - -`index-details (json,required)` - -!SUBSECTION Description - -Creates a skip-list index for the collection collection-name, if it does not already exist. The call expects an object containing the index details. - -* type: must be equal to "skiplist". -* fields: A list of attribute paths. -* unique: If true, then create a unique index. - -*Note*: unique indexes on non-shard keys are not supported in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index already exists, then a HTTP 200 is returned. - -`HTTP 201` - -If the index does not already exist and could be created, then a HTTP 201 is returned. - -`HTTP 400` - -If the collection already contains documents and you try to create a unique skip-list index in such a way that there are documents violating the uniqueness, then a HTTP 400 is returned. - -`HTTP 404` - -If the collection-name is unknown, then a HTTP 404 is returned. - -*Examples* - -Creating a skiplist: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/index?collection=products -{ "type": "skiplist", "unique" : false, "fields" : [ "a", "b" ] } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "id" : "products/171828193", - "type" : "skiplist", - "unique" : false, - "fields" : [ - "a", - "b" - ], - "isNewlyCreated" : true, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/range`*(executes simple range query)* - -!SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -!SUBSECTION Description - -This will find all documents within a given range. In order to execute a range query, a skip-list index on the queried attribute must be present. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* attribute: The attribute path to check. -* left: The lower bound. -* right: The upper bound. -* closed: If true, use interval including left and right, otherwise exclude right, but include left. -* skip: The number of documents to skip in the query (optional). -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -!SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/range -{ "collection": "products", "attribute" : "i", "left" : 2, "right" : 4 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/208069601", - "_rev" : "208069601", - "_key" : "208069601", - "i" : 2 - }, - { - "_id" : "products/208266209", - "_rev" : "208266209", - "_key" : "208266209", - "i" : 3 - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` + +@startDocuBlock JSF_post_api_index_skiplist \ No newline at end of file diff --git a/Documentation/Books/Users/HttpIndexes/WorkingWith.mdpp b/Documentation/Books/Users/HttpIndexes/WorkingWith.mdpp index 40b8c0c088..5144932d4d 100644 --- a/Documentation/Books/Users/HttpIndexes/WorkingWith.mdpp +++ b/Documentation/Books/Users/HttpIndexes/WorkingWith.mdpp @@ -1,201 +1,13 @@ !CHAPTER Working with Indexes using HTTP -`GET /_api/index/{index-handle}`*(reads an index)* + +@startDocuBlock JSF_get_api_reads_index -!SUBSECTION URL parameters + +@startDocuBlock JSF_post_api_index -`index-handle (string,required)` + +@startDocuBlock JSF_post_api_index_delete -The index-handle. -!SUBSECTION Description - -The result is an objects describing the index. It has at least the following attributes: - -* id: The identifier of the index. - -All other attributes are type-dependent. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index exists, then a HTTP 200 is returned. - -`HTTP 404` - -If the index does not exist, then a HTTP 404 is returned. - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/index/products/0 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "products/0", - "type" : "primary", - "unique" : true, - "fields" : [ - "_id" - ], - "error" : false, - "code" : 200 -} -``` - -`POST /_api/index`*(creates an index)* - -!SUBSECTION Query parameters - -`collection (string,required)` - -The collection name. - -!SUBSECTION Body parameters - -`index-details (json,required)` - -!SUBSECTION Description - -Creates a new index in the collection collection. Expects an object containing the index details. - -The type of the index to be created must specified in the type attribute of the index details. Depending on the index type, additional other attributes may need to specified in the request in order to create the index. - -See Working with Cap Constraints , Working with Geo Indexes , Working with Hash Indexes , Working with Fulltext Indexes , and Working with Skiplist Indexes for details. - -Most indexes (a notable exception being the cap constraint) require the list of attributes to be indexed in the fields attribute of the index details. Depending on the index type, a single attribute or multiple attributes may be indexed. - -Indexing system attributes such as _id, _key, _from, and _to is not supported by any index type. Manually creating an index that relies on any of these attributes is unsupported. - -Some indexes can be created as unique or non-unique variants. Uniqueness can be controlled for most indexes by specifying the unique in the index details. Setting it to true will create a unique index. Setting it to false or omitting the unique attribute will create a non-unique index. - -*Note* that the following index types do not support uniqueness, and using the unique attribute with these types may lead to an error: - -* cap constraints -* fulltext indexes -* bitarray indexes - -Note also that unique indexes on non-shard keys are not supported in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index already exists, then an HTTP 200 is returned. - -`HTTP 201` - -If the index does not already exist and could be created, then an HTTP 201 is returned. - -`HTTP 400` - -If an invalid index description is posted or attributes are used that the target index will not support, then an HTTP 400 is returned. - -`HTTP 404` - -If collection is unknown, then an HTTP 404 is returned. - -`DELETE /_api/index/{index-handle}`*(deletes an index)* - -!SUBSECTION Query parameters - -`index-handle (string,required)` - -The index handle. - -!SUBSECTION Description - -Deletes an index with index-handle. - -!SUBSECTION Return codes - -`HTTP 200` - -If the index could be deleted, then an HTTP 200 is returned. - -`HTTP 404` - -If the index-handle is unknown, then an HTTP 404 is returned. - -*Examples* - -``` -unix> curl -X DELETE --dump - http://localhost:8529/_api/index/products/172942305 - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "id" : "products/172942305", - "error" : false, - "code" : 200 -} -``` - -`GET /_api/index`*(reads all indexes of a collection)* - -!SUBSECTION Query parameters - -`collection (string,required)` - -The collection name. - -!SUBSECTION Description - -Returns an object with an attribute indexes containing a list of all index descriptions for the given collection. The same information is also available in the identifiers as hash map with the index handle as keys. - -*Examples* - -Return information about all indexes: - -``` -unix> curl --dump - http://localhost:8529/_api/index?collection=products - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "indexes" : [ - { - "id" : "products/0", - "type" : "primary", - "unique" : true, - "fields" : [ - "_id" - ] - } - ], - "identifiers" : { - "products/0" : { - "id" : "products/0", - "type" : "primary", - "unique" : true, - "fields" : [ - "_id" - ] - } - }, - "error" : false, - "code" : 200 -} -``` - - - \ No newline at end of file + +@startDocuBlock JSF_get_api_index \ No newline at end of file diff --git a/Documentation/Books/Users/HttpReplications/OtherReplication.mdpp b/Documentation/Books/Users/HttpReplications/OtherReplication.mdpp index b13fb57413..428d468338 100644 --- a/Documentation/Books/Users/HttpReplications/OtherReplication.mdpp +++ b/Documentation/Books/Users/HttpReplications/OtherReplication.mdpp @@ -1,41 +1,4 @@ !CHAPTER Other Replication Commands -get the server's id - -`GET /_api/replication/server-id`*(returns the servers id)* - -!SUBSECTION Description - -Returns the servers id. The id is also returned by other replication API methods, and this method is an easy means of determining a server's id. -The body of the response is a JSON hash with the attribute serverId. The server id is returned as a string. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/replication/server-id - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "serverId" : "18804023088184" -} -``` - + +@startDocuBlock JSF_put_api_replication_serverID diff --git a/Documentation/Books/Users/HttpReplications/ReplicationApplier.mdpp b/Documentation/Books/Users/HttpReplications/ReplicationApplier.mdpp index 47d2587946..22ca0581b5 100644 --- a/Documentation/Books/Users/HttpReplications/ReplicationApplier.mdpp +++ b/Documentation/Books/Users/HttpReplications/ReplicationApplier.mdpp @@ -3,404 +3,17 @@ The applier commands allow to remotely start, stop, and query the state and configuration of an ArangoDB database's replication applier. -`GET /_api/replication/applier-config`*(returns the configuration of the replication applier)* + +@startDocuBlock JSF_put_api_replication_applier -!SUBSECTION Description + +@startDocuBlock JSF_put_api_replication_applier_adjust -Returns the configuration of the replication applier. -The body of the response is a JSON hash with the configuration. The following attributes may be present in the configuration: + +@startDocuBlock JSF_put_api_replication_applier_start -* endpoint: the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). -* database: the name of the database to connect to (e.g. "_system"). -* username: an optional ArangoDB username to use when connecting to the endpoint. -* password: the password to use when connecting to the endpoint. -* maxConnectRetries: the maximum number of connection attempts the applier will make in a row. If the applier cannot establish a connection to the endpoint in this number of attempts, it will stop itself. -* connectTimeout: the timeout (in seconds) when attempting to connect to the endpoint. This value is used for each connection attempt. -* requestTimeout: the timeout (in seconds) for individual requests to the endpoint. -* chunkSize: the requested maximum size for log transfer packets that is used when the endpoint is contacted. -* autoStart: whether or not to auto-start the replication applier on (next and following) server starts -* adaptivePolling: whether or not the replication applier will use adaptive polling. + +@startDocuBlock JSF_put_api_replication_applier_stop -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/replication/applier-config - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "requestTimeout" : 300, - "connectTimeout" : 10, - "maxConnectRetries" : 100, - "sslProtocol" : 0, - "chunkSize" : 0, - "autoStart" : false, - "adaptivePolling" : true -} -``` -set the configuration of the replication applier - -`PUT /_api/replication/applier-config`*(adjusts the configuration of the replication applier)* - -!SUBSECTION Body parameters - -`configuration (json,required)` - -A JSON representation of the configuration. - -!SUBSECTION Description - -Sets the configuration of the replication applier. The configuration can only be changed while the applier is not running. The updated configuration will be saved immediately but only become active with the next start of the applier. -The body of the request must be JSON hash with the configuration. The following attributes are allowed for the configuration: - -* endpoint: the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). The endpoint must be specified. -* database: the name of the database on the endpoint. If not specified, defaults to the current local database name. -* username: an optional ArangoDB username to use when connecting to the endpoint. -* password: the password to use when connecting to the endpoint. -* maxConnectRetries: the maximum number of connection attempts the applier will make in a row. If the applier cannot establish a connection to the endpoint in this number of attempts, it will stop itself. -* connectTimeout: the timeout (in seconds) when attempting to connect to the endpoint. This value is used for each connection attempt. -* requestTimeout: the timeout (in seconds) for individual requests to the endpoint. -* chunkSize: the requested maximum size for log transfer packets that is used when the endpoint is contacted. -* autoStart: whether or not to auto-start the replication applier on (next and following) server starts -* adaptivePolling: if set to true, the replication applier will fall to sleep for an increasingly long period in case the logger server at the endpoint does not have any more replication events to apply. Using adaptive polling is thus useful to reduce the amount of work for both the applier and the logger server for cases when there are only infrequent changes. The downside is that when using adaptive polling, it might take longer for the replication applier to detect that there are new replication events on the logger server. - -Setting adaptivePolling to false will make the replication applier contact the logger server in a constant interval, regardless of whether the logger server provides updates frequently or seldomly. - -In case of success, the body of the response is a JSON hash with the updated configuration. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 400` - -is returned if the configuration is incomplete or malformed, or if the replication applier is currently running. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/replication/applier-config -{"endpoint":"tcp://127.0.0.1:8529","username":"replicationApplier","password":"applier1234@foxx","chunkSize":4194304,"autoStart":false,"adaptivePolling":true} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "endpoint" : "tcp://127.0.0.1:8529", - "database" : "_system", - "username" : "replicationApplier", - "requestTimeout" : 300, - "connectTimeout" : 10, - "maxConnectRetries" : 100, - "sslProtocol" : 0, - "chunkSize" : 4194304, - "autoStart" : false, - "adaptivePolling" : true -} -``` - -`PUT /_api/replication/applier-start`*(starts the replication applier)* - -!SUBSECTION Query parameters - -`from (string,optional)` - -The remote lastLogTick value from which to start applying. If not specified, the last saved tick from the previous applier run is used. If there is no previous applier state saved, the applier will start at the beginning of the logger server's log. - -!SUBSECTION Description - -Starts the replication applier. This will return immediately if the replication applier is already running. -If the replication applier is not already running, the applier configuration will be checked, and if it is complete, the applier will be started in a background thread. This means that even if the applier will encounter any errors while running, they will not be reported in the response to this method. - -To detect replication applier errors after the applier was started, use the /_api/replication/applier-state API instead. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 400` - -is returned if the replication applier is not fully configured or the configuration is invalid. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -*Examples* - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/replication/applier-start - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "state" : { - "running" : true, - "lastAppliedContinuousTick" : null, - "lastProcessedContinuousTick" : null, - "lastAvailableContinuousTick" : null, - "progress" : { - "time" : "2014-05-29T15:03:18Z", - "message" : "applier created", - "failedConnects" : 0 - }, - "totalRequests" : 0, - "totalFailedConnects" : 0, - "totalEvents" : 0, - "lastError" : { - "errorNum" : 0 - }, - "time" : "2014-05-29T15:03:53Z" - }, - "server" : { - "version" : "2.1.0", - "serverId" : "18804023088184" - }, - "endpoint" : "tcp://127.0.0.1:8529", - "database" : "_system" -} -``` - -stops the replication applier - -`PUT /_api/replication/applier-stop`*(stops the replication applier)* - -!SUBSECTION Description - -Stops the replication applier. This will return immediately if the replication applier is not running. -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -!SUBSECTION Examples - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/replication/applier-stop - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "state" : { - "running" : false, - "lastAppliedContinuousTick" : null, - "lastProcessedContinuousTick" : null, - "lastAvailableContinuousTick" : null, - "progress" : { - "time" : "2014-05-29T15:03:53Z", - "message" : "fetching master state information", - "failedConnects" : 1 - }, - "totalRequests" : 2, - "totalFailedConnects" : 2, - "totalEvents" : 0, - "lastError" : { - "time" : "2014-05-29T15:03:53Z", - "errorMessage" : "could not connect to master at tcp://127.0.0.1:8529: Could not connect to 'tcp:/...", - "errorNum" : 1412 - }, - "time" : "2014-05-29T15:03:53Z" - }, - "server" : { - "version" : "2.1.0", - "serverId" : "18804023088184" - }, - "endpoint" : "tcp://127.0.0.1:8529", - "database" : "_system" -} -``` - -returns the state of the replication applier - -`GET /_api/replication/applier-state`*(returns the state of the replication applier)* - -!SUBSECTION Description - -Returns the state of the replication applier, regardless of whether the applier is currently running or not. -The response is a JSON hash with the following attributes: - -*state*: a JSON hash with the following sub-attributes: - -*running*: whether or not the applier is active and running -lastAppliedContinuousTick: the last tick value from the continuous replication log the applier has applied. -lastProcessedContinuousTick: the last tick value from the continuous replication log the applier has processed. - -Regularly, the last applied and last processed tick values should be identical. For transactional operations, the replication applier will first process incoming log events before applying them, so the processed tick value might be higher than the applied tick value. This will be the case until the applier encounters the transaction commit log event for the transaction. - -* lastAvailableContinuousTick: the last tick value the logger server can provide. -* time: the time on the applier server. -* totalRequests: the total number of requests the applier has made to the endpoint. -* totalFailedConnects: the total number of failed connection attempts the applier has made. -* totalEvents: the total number of log events the applier has processed. -* progress: a JSON hash with details about the replication applier progress. It contains the following sub-attributes if there is progress to report: - -* message: a textual description of the progress -* time: the date and time the progress was logged -* failedConnects: the current number of failed connection attempts -* lastError: a JSON hash with details about the last error that happened on the applier. It contains the following sub-attributes if there was an error: - -* errorNum: a numerical error code -* errorMessage: a textual error description -* time: the date and time the error occurred - -In case no error has occurred, lastError will be empty. - -* server: a JSON hash with the following sub-attributes: -* version: the applier server's version -* serverId: the applier server's id -* endpoint: the endpoint the applier is connected to (if applier is active) or will connect to (if applier is currently inactive) -* database: the name of the database the applier is connected to (if applier is active) or will connect to (if applier is currently inactive) - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -*Examples* - -Fetching the state of an inactive applier: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/applier-state - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "state" : { - "running" : false, - "lastAppliedContinuousTick" : null, - "lastProcessedContinuousTick" : null, - "lastAvailableContinuousTick" : null, - "progress" : { - "time" : "2014-05-29T15:03:53Z", - "message" : "fetching master state information", - "failedConnects" : 1 - }, - "totalRequests" : 2, - "totalFailedConnects" : 2, - "totalEvents" : 0, - "lastError" : { - "time" : "2014-05-29T15:03:53Z", - "errorMessage" : "could not connect to master at tcp://127.0.0.1:8529: Could not connect to 'tcp:/...", - "errorNum" : 1412 - }, - "time" : "2014-05-29T15:03:53Z" - }, - "server" : { - "version" : "2.1.0", - "serverId" : "18804023088184" - }, - "endpoint" : "tcp://127.0.0.1:8529", - "database" : "_system" -} -``` - -Fetching the state of an active applier: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/applier-state - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "state" : { - "running" : true, - "lastAppliedContinuousTick" : null, - "lastProcessedContinuousTick" : null, - "lastAvailableContinuousTick" : null, - "progress" : { - "time" : "2014-05-29T15:03:53Z", - "message" : "fetching master state information", - "failedConnects" : 1 - }, - "totalRequests" : 2, - "totalFailedConnects" : 2, - "totalEvents" : 0, - "lastError" : { - "errorNum" : 0 - }, - "time" : "2014-05-29T15:03:53Z" - }, - "server" : { - "version" : "2.1.0", - "serverId" : "18804023088184" - }, - "endpoint" : "tcp://127.0.0.1:8529", - "database" : "_system" -} -``` - - - \ No newline at end of file + +@startDocuBlock JSF_get_api_replication_applier_state \ No newline at end of file diff --git a/Documentation/Books/Users/HttpReplications/ReplicationDump.mdpp b/Documentation/Books/Users/HttpReplications/ReplicationDump.mdpp index e96ab0081e..d22db7329b 100644 --- a/Documentation/Books/Users/HttpReplications/ReplicationDump.mdpp +++ b/Documentation/Books/Users/HttpReplications/ReplicationDump.mdpp @@ -6,474 +6,9 @@ overview of which collections are present in the database. They can use this inf to either start a full or a partial synchronization of data, e.g. to initiate a backup or the incremental data synchronization. -returns the server inventory -return the inventory (current replication and collection state) - -`GET /_api/replication/inventory`*(returns an inventory of collections and indexes)* - -!SUBSECTION Query parameters - -`includeSystem (boolean,optional)` - -Include system collections in the result. The default value is false. - -!SUBSECTION Description - -Returns the list of collections and indexes available on the server. This list can be used by replication clients to initiate an initial sync with the server. -The response will contain a JSON hash array with the collection and state attributes. - -collections is a list of collections with the following sub-attributes: - -* parameters: the collection properties -* indexes: a list of the indexes of a the collection. Primary indexes and edges indexes are not included in this list. -* tick: the system-wide tick value at the start of the dump - -The state attribute contains the current state of the replication logger. It contains the following sub-attributes: - -* running: whether or not the replication logger is currently active -* lastLogTick: the value of the last tick the replication logger has written -* time: the current time on the server - -Replication clients should note the lastLogTick value returned. They can then fetch collections' data using the dump method up to the value of lastLogTick, and query the continuous replication log for log events after this tick value. - -To create a full copy of the collections on the logger server, a replication client can execute these steps: - -call the /inventory API method. This returns the lastLogTick value and the list of collections and indexes from the logger server. -for each collection returned by /inventory, create the collection locally and call /dump to stream the collection data to the client, up to the value of lastLogTick. After that, the client can create the indexes on the collections as they were reported by /inventory. -If the clients wants to continuously stream replication log events from the logger server, the following additional steps need to be carried out: - -The client should call /logger-follow initially to fetch the first batch of replication events that were logged after the client's call to /inventory. - -The call to /logger-follow should use a from parameter with the value of the lastLogTick as reported by /inventory. The call to /logger-follow will return the x-arango-replication-lastincluded which will contain the last tick value included in the response. - -The client can then continuously call /logger-follow to incrementally fetch new replication events that occurred after the last transfer. - -Calls should use a from parameter with the value of the x-arango-replication-lastincluded header of the previous response. If there are no more replication events, the response will be empty and clients can go to sleep for a while and try again later. - -*Note*: on a coordinator, this request must have the URL parameter DBserver which must be an ID of a DBserver. The very same request is forwarded synchronously to that DBserver. It is an error if this attribute is not bound in the coordinator case. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. -Examples - -``` -unix> curl --dump - http://localhost:8529/_api/replication/inventory - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "collections" : [ - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "19915745", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "animals", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - }, - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "19063777", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "demo", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - }, - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "106750945", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "vertices1", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - }, - { - "parameters" : { - "version" : 5, - "type" : 3, - "cid" : "108061665", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "edges2", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - } - ], - "state" : { - "running" : false, - "lastLogTick" : "305390561", - "totalEvents" : 22, - "time" : "2014-05-29T15:03:52Z" - }, - "tick" : "305456097" -} -``` - -With some additional indexes: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/inventory - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "collections" : [ - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "19915745", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "animals", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - }, - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "19063777", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "demo", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - }, - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "305521633", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "IndexedCollection1", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ - { - "id" : "305783777", - "type" : "hash", - "unique" : false, - "fields" : [ - "name" - ] - }, - { - "id" : "306045921", - "type" : "skiplist", - "unique" : true, - "fields" : [ - "a", - "b" - ] - }, - { - "id" : "306176993", - "type" : "cap", - "unique" : false, - "size" : 500, - "byteSize" : 0 - } - ] - }, - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "306242529", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "IndexedCollection2", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ - { - "id" : "306504673", - "type" : "fulltext", - "unique" : false, - "minLength" : 10, - "fields" : [ - "text" - ] - }, - { - "id" : "306701281", - "type" : "skiplist", - "unique" : false, - "fields" : [ - "a" - ] - }, - { - "id" : "306832353", - "type" : "cap", - "unique" : false, - "size" : 0, - "byteSize" : 1048576 - } - ] - }, - { - "parameters" : { - "version" : 5, - "type" : 2, - "cid" : "106750945", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "vertices1", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - }, - { - "parameters" : { - "version" : 5, - "type" : 3, - "cid" : "108061665", - "deleted" : false, - "doCompact" : true, - "maximalSize" : 1048576, - "name" : "edges2", - "isVolatile" : false, - "waitForSync" : false - }, - "indexes" : [ ] - } - ], - "state" : { - "running" : false, - "lastLogTick" : "305390561", - "totalEvents" : 22, - "time" : "2014-05-29T15:03:52Z" - }, - "tick" : "306832353" -} -``` - -The dump method can be used to fetch data from a specific collection. As the results of the dump command can be huge, dump may not return all data from a collection at once. Instead, the dump command may be called repeatedly by replication clients until there is no more data to fetch. The dump command will not only return the current documents in the collection, but also document updates and deletions. - -To get to an identical state of data, replication clients should apply the individual parts of the dump results in the same order as they are served to them. - -restores the data of a collection, coordinator case - -handle a dump command for a specific collection - -dumps the data of a collection - -`GET /_api/replication/dump`*(returns the data of a collection)* - -!SUBSECTION Query parameters - -`collection (string,required)` - -The name or id of the collection to dump. - -`from (number,optional)` - -Lower bound tick value for results. - -`to (number,optional)` - -Upper bound tick value for results. - -`chunkSize (number,optional)` - -Approximate maximum size of the returned result. - -`ticks (boolean,optional)` - -Whether or not to include tick values in the dump. Default value is true. - -!SUBSECTION Description - -Returns the data from the collection for the requested range. -When the from URL parameter is not used, collection events are returned from the beginning. When the from parameter is used, the result will only contain collection entries which have higher tick values than the specified from value (note: the log entry with a tick value equal to from will be excluded). - -The to URL parameter can be used to optionally restrict the upper bound of the result to a certain tick value. If used, the result will only contain collection entries with tick values up to (including) to. - -The chunkSize URL parameter can be used to control the size of the result. It must be specified in bytes. The chunkSize value will only be honored approximately. Otherwise a too low chunkSize value could cause the server to not be able to put just one entry into the result and return it. Therefore, the chunkSize value will only be consulted after an entry has been written into the result. If the result size is then bigger than chunkSize, the server will respond with as many entries as there are in the response already. If the result size is still smaller than chunkSize, the server will try to return more data if there's more data left to return. - -If chunkSize is not specified, some server-side default value will be used. - -The Content-Type of the result is application/x-arango-dump. This is an easy-to-process format, with all entries going onto separate lines in the response body. - -Each line itself is a JSON hash, with at least the following attributes: - -* type: the type of entry. Possible values for type are: -* 2300: document insertion/update -* 2301: edge insertion/update -* 2302: document/edge deletion -* key: the key of the document/edge or the key used in the deletion operation -* rev: the revision id of the document/edge or the deletion operation -* data: the actual document/edge data for types 2300 and 2301. The full document/edge data will be returned even for updates. - -A more detailed description of the different entry types and their data structures can be found in Replication Event Types. - -*Note*: there will be no distinction between inserts and updates when calling this method. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 400` - -is returned if either the from or to values are invalid. - -`HTTP 404` - -is returned when the collection could not be found. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -!SUBSECTION Examples - -Empty collection: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/dump?collection=testCollection - -HTTP/1.1 204 No Content -content-type: application/x-arango-dump; charset=utf-8 -x-arango-replication-checkmore: false -x-arango-replication-lastincluded: 0 -``` - -Non-empty collection: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/dump?collection=testCollection - -HTTP/1.1 200 OK -content-type: application/x-arango-dump; charset=utf-8 -x-arango-replication-checkmore: false -x-arango-replication-lastincluded: 308798433 - -{"tick":"307422177","type":2300,"key":"abcdef","rev":"307356641","data":{"_key":"abcdef","_rev":"307356641","test":true,"a":"abc"}} -{"tick":"307815393","type":2300,"key":"123456","rev":"307749857","data":{"_key":"123456","_rev":"307749857","c":false,"b":1}} -{"tick":"308143073","type":2300,"key":"123456","rev":"308077537","data":{"_key":"123456","_rev":"308077537","c":false,"b":1,"d":"additional value"}} -{"tick":"308405217","type":2300,"key":"foobar","rev":"308339681","data":{"_key":"foobar","_rev":"308339681"}} -{"tick":"308601825","type":2302,"key":"foobar","rev":"308536289"} -{"tick":"308798433","type":2302,"key":"abcdef","rev":"308732897"} -``` - -The sync method can be used by replication clients to connect an ArangoDB database to a remote endpoint, fetch the remote list of collections and indexes, and collection data. It will thus create a local backup of the state of data at the remote ArangoDB database. sync works on a database level. - -sync will first fetch the list of collections and indexes from the remote endpoint. It does so by calling the inventory API of the remote database. It will then purge data in the local ArangoDB database, and after start will transfer collection data from the remote database to the local ArangoDB database. It will extract data from the remote database by calling the remote database's dump API until all data are fetched. - -As mentioned, sync will remove data from the local instance, and thus must be handled with caution. - -synchronises data from a remote endpoint - -`PUT /_api/replication/sync`*(synchronises data from a remote endpoint)* -!SUBSECTION Body parameters - -`configuration (json,required)` - -A JSON representation of the configuration. - -!SUBSECTION Description - -Starts a full data synchronisation from a remote endpoint into the local ArangoDB database. -The body of the request must be JSON hash with the configuration. The following attributes are allowed for the configuration: - -* endpoint: the endpoint to connect to (e.g. "tcp://192.168.173.13:8529"). -* database: the database name on the master (if not specified, defaults to the name of the local current database). -* username: an optional ArangoDB username to use when connecting to the endpoint. -* password: the password to use when connecting to the endpoint. -* restrictType: an optional string value for collection filtering. When specified, the allowed values are include or exclude. -* restrictCollections: an optional list of collections for use with restrictType. If restrictType is include, only the specified collections will be sychronised. If restrictType is exclude, all but the specified collections will be synchronised. - -In case of success, the body of the response is a JSON hash with the following attributes: - -* collections: a list of collections that were transferred from the endpoint -* lastLogTick: the last log tick on the endpoint at the time the transfer was started. Use this value as the from value when starting the continuous synchronisation later. -**WARNING**: calling this method will sychronise data from the collections found on the remote endpoint to the local ArangoDB database. All data in the local collections will be purged and replaced with data from the endpoint. - -Use with caution! - -*Note*: this method is not supported on a coordinator in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 400` - -is returned if the configuration is incomplete or malformed. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred during sychronisation. - -`HTTP 501` - -is returned when this operation is called on a coordinator in a cluster. - - +@startDocuBlock JSF_put_api_replication_inventory The *dump* method can be used to fetch data from a specific collection. As the results of the dump command can be huge, *dump* may not return all data from a collection @@ -484,8 +19,8 @@ current documents in the collection, but also document updates and deletions. To get to an identical state of data, replication clients should apply the individual parts of the dump results in the same order as they are served to them. -@anchor HttpReplicationDump -@copydetails triagens::arango::RestReplicationHandler::handleCommandDump + +@startDocuBlock JSF_get_api_replication_dump The *sync* method can be used by replication clients to connect an ArangoDB database to a remote endpoint, fetch the remote list of collections and indexes, and collection @@ -502,8 +37,5 @@ remote database by calling the remote database's *dump* API until all data are f As mentioned, *sync* will remove data from the local instance, and thus must be handled with caution. -@anchor HttpReplicationSync -@copydetails triagens::arango::RestReplicationHandler::handleCommandSync - - ---> \ No newline at end of file + +@startDocuBlock JSF_put_api_replication_synchronize diff --git a/Documentation/Books/Users/HttpReplications/ReplicationLogger.mdpp b/Documentation/Books/Users/HttpReplications/ReplicationLogger.mdpp index c177a1a416..295eb7496a 100644 --- a/Documentation/Books/Users/HttpReplications/ReplicationLogger.mdpp +++ b/Documentation/Books/Users/HttpReplications/ReplicationLogger.mdpp @@ -3,458 +3,20 @@ The logger commands allow starting, starting, and fetching the current state of a database's replication logger. -`GET /_api/replication/logger-config`*(returns the configuration of the replication logger)* + +@startDocuBlock JSF_get_api_replication_logger_configuration -!SUBSECTION Description + +@startDocuBlock JSF_put_api_replication_logger_configuration -Returns the configuration of the replication logger. -The body of the response is a JSON hash with the configuration. The following attributes may be present in the configuration: + +@startDocuBlock JSF_put_api_replication_logger_start -* autoStart: whether or not to automatically start the replication logger on server startup -* logRemoteChanges: whether or not externally created changes should be logged by the local logger -* maxEvents: the maximum number of log events kept by the replication logger before deleting oldest events. A value of 0 means that the number of events is not restricted. -* maxEventsSize: the maximum cumulated size of log event data kept by the replication logger before deleting oldest events. A value of 0 means that the cumulated size of events is not restricted. + +@startDocuBlock JSF_put_api_replication_logger_stop -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -*Examples* - -``` -unix> curl --dump - http://localhost:8529/_api/replication/logger-config - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "autoStart" : false, - "logRemoteChanges" : false, - "maxEvents" : 1048576, - "maxEventsSize" : 134217728 -} -``` - -set the configuration of the replication logger - -`PUT /_api/replication/logger-config`*(adjusts the configuration of the replication logger)* - -!SUBSECTION Body parameters - -`configuration (json,required)` - -A JSON representation of the configuration. - -!SUBSECTION Description - -Sets the configuration of the replication logger. -The body of the request must be JSON hash with the configuration. The following attributes are allowed for the configuration: - -* autoStart: whether or not to automatically start the replication logger on server startup -* logRemoteChanges: whether or not externally created changes should be logged by the local logger -* maxEvents: the maximum number of log events kept by the replication logger before deleting oldest events. Use a value of 0 to not restrict the number of events. -* maxEventsSize: the maximum cumulated size of log event data kept by the replication logger before deleting oldest events. Use a value of 0 to not restrict the size. - -Note that when setting both maxEvents and maxEventsSize, reaching either limitation will trigger a deletion of the "oldest" log events from the replication log. - -In case of success, the body of the response is a JSON hash with the updated configuration. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully. - -`HTTP 400` - -is returned if the configuration is incomplete or malformed. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/replication/logger-config -{"logRemoteChanges":true,"maxEvents":1048576} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "autoStart" : false, - "logRemoteChanges" : true, - "maxEvents" : 1048576, - "maxEventsSize" : 134217728 -} - -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/replication/logger-config -{"logRemoteChanges":false,"maxEvents":16384,"maxEventsSize":16777216} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "autoStart" : false, - "logRemoteChanges" : false, - "maxEvents" : 16384, - "maxEventsSize" : 16777216 -} -``` - -starts the replication logger - -`PUT /_api/replication/logger-start`*(starts the replication logger)* - -!SUBSECTION Description - -Starts the server's replication logger. Will do nothing if the replication logger is already running. -The body of the response contains a JSON object with the following attributes: - -* running: will contain true - -*Note*: this method is not supported on a coordinator in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the logger was started successfully, or was already running. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if the logger could not be started. - -`HTTP 501` - -is returned when this operation is called on a coordinator in a cluster. - -*Examples* - -Starts the replication logger. - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/replication/logger-start - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "running" : true -} -``` - -stops the replication logger - - -`PUT /_api/replication/logger-stop`*(stops the replication logger)* - -!SUBSECTION Description - -Stops the server's replication logger. Will do nothing if the replication logger is not running. -The body of the response contains a JSON object with the following attributes: - -* running: will contain false - -*Note*: this method is not supported on a coordinator in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the logger was stopped successfully, or was not running before. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if the logger could not be stopped. - -`HTTP 501` - -is returned when this operation is called on a coordinator in a cluster. - -*Examples* - -Starts the replication logger. - -``` -unix> curl -X PUT --dump - http://localhost:8529/_api/replication/logger-stop - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "running" : false -} -``` - -returns the state of the replication logger - -`GET /_api/replication/logger-state`*(returns the replication logger state)* - -!SUBSECTION Description - -Returns the current state of the server's replication logger. The state will include information about whether the logger is running and about the last logged tick value. This tick value is important for incremental fetching of data. -The state API can be called regardless of whether the logger is currently running or not. - -The body of the response contains a JSON object with the following attributes: - -* state: the current logger state as a JSON hash array with the following sub-attributes: - -* running: whether or not the logger is running -* lastLogTick: the tick value of the latest tick the logger has logged. This value can be used for incremental fetching of log data. -* totalEvents: total number of events logged since the server was started. The value is not reset between multiple stops and re-starts of the logger. -* time: the current date and time on the logger server -* server: a JSON hash with the following sub-attributes: - -* version: the logger server's version -* serverId: the logger server's id -* clients: a list of all replication clients that ever connected to the logger since it was started. This list can be used to determine approximately how much data the individual clients have already fetched from the logger server. Each entry in the list contains a time value indicating the server time the client last fetched data from the replication logger. The lastServedTick value of each client indicates the latest tick value sent to the client upon a client request to the replication logger. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the logger state could be determined successfully. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if the logger state could not be determined. - -*Examples* - -Returns the state of an inactive replication logger. - -``` -unix> curl --dump - http://localhost:8529/_api/replication/logger-state - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "state" : { - "running" : false, - "lastLogTick" : "299885537", - "totalEvents" : 2, - "time" : "2014-05-29T15:03:52Z" - }, - "server" : { - "version" : "2.1.0", - "serverId" : "18804023088184" - }, - "clients" : [ ] -} -``` - -Returns the state of an active replication logger. - -``` -unix> curl --dump - http://localhost:8529/_api/replication/logger-state - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "state" : { - "running" : true, - "lastLogTick" : "300213217", - "totalEvents" : 3, - "time" : "2014-05-29T15:03:52Z" - }, - "server" : { - "version" : "2.1.0", - "serverId" : "18804023088184" - }, - "clients" : [ ] -} -``` - -To query the latest changes logged by the replication logger, the HTTP interface also provides the logger-follow. - -This method should be used by replication clients to incrementally fetch updates from an ArangoDB database. - -forward a command in the coordinator case - -returns ranged data from the replication log - -`GET /_api/replication/logger-follow`*(returns recent log entries from the replication log)* - -!SUBSECTION Query parameters - -`from (number,optional)` - -Lower bound tick value for results. - -`to (number,optional)` - -Upper bound tick value for results. - -`chunkSize (number,optional)` - -Approximate maximum size of the returned result. - -!SUBSECTION Description - -Returns data from the server's replication log. This method can be called by replication clients after an initial synchronisation of data. The method will return all "recent" log entries from the logger server, and the clients can replay and apply these entries locally so they get to the same data state as the logger server. -Clients can call this method repeatedly to incrementally fetch all changes from the logger server. In this case, they should provide the from value so they will only get returned the log events since their last fetch. - -When the from URL parameter is not used, the logger server will return log entries starting at the beginning of its replication log. When the from parameter is used, the logger server will only return log entries which have higher tick values than the specified from value (note: the log entry with a tick value equal to from will be excluded). Use the from value when incrementally fetching log data. - -The to URL parameter can be used to optionally restrict the upper bound of the result to a certain tick value. If used, the result will contain only log events with tick values up to (including) to. In incremental fetching, there is no need to use the to parameter. It only makes sense in special situations, when only parts of the change log are required. - -The chunkSize URL parameter can be used to control the size of the result. It must be specified in bytes. The chunkSize value will only be honored approximately. Otherwise a too low chunkSize value could cause the server to not be able to put just one log entry into the result and return it. Therefore, the chunkSize value will only be consulted after a log entry has been written into the result. If the result size is then bigger than chunkSize, the server will respond with as many log entries as there are in the response already. If the result size is still smaller than chunkSize, the server will try to return more data if there's more data left to return. - -If chunkSize is not specified, some server-side default value will be used. - -The Content-Type of the result is application/x-arango-dump. This is an easy-to-process format, with all log events going onto separate lines in the response body. Each log event itself is a JSON hash, with at least the following attributes: - -* tick: the log event tick value -* type: the log event type - -Individual log events will also have additional attributes, depending on the event type. A few common attributes which are used for multiple events types are: - -* cid: id of the collection the event was for -* tid: id of the transaction the event was contained in -* key: document key -* rev: document revision id -* data: the original document data - -A more detailed description of the individual replication event types and their data structures can be found in Replication Event Types. - -The response will also contain the following HTTP headers: - -* x-arango-replication-active: whether or not the logger is active. Clients can use this flag as an indication for their polling frequency. If the logger is not active and there are no more replication events available, it might be sensible for a client to abort, or to go to sleep for a long time and try again later to check whether the logger has been activated. -* x-arango-replication-lastincluded: the tick value of the last included value in the result. In incremental log fetching, this value can be used as the from value for the following request. Note that if the result is empty, the value will be 0. This value should not be used as from value by clients in the next request (otherwise the server would return the log events from the start of the log again). -* x-arango-replication-lasttick: the last tick value the logger server has logged (not necessarily included in the result). By comparing the the last tick and last included tick values, clients have an approximate indication of how many events there are still left to fetch. -* x-arango-replication-checkmore: whether or not there already exists more log data which the client could fetch immediately. If there is more log data available, the client could call logger-follow again with an adjusted from value to fetch remaining log entries until there are no more. - -If there isn't any more log data to fetch, the client might decide to go to sleep for a while before calling the logger again. - -*Note*: this method is not supported on a coordinator in a cluster. - -!SUBSECTION Return codes - -`HTTP 200` - -is returned if the request was executed successfully, and there are log events available for the requested range. The response body will not be empty in this case. - -`HTTP 204` - -is returned if the request was executed successfully, but there are no log events available for the requested range. The response body will be empty in this case. - -`HTTP 400` - -is returned if either the from or to values are invalid. - -`HTTP 405` - -is returned when an invalid HTTP method is used. - -`HTTP 500` - -is returned if an error occurred while assembling the response. - -`HTTP 501` - -is returned when this operation is called on a coordinator in a cluster. - -*Examples* - -No log events available: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/logger-follow?from=300606433 - -HTTP/1.1 204 No Content -content-type: application/x-arango-dump; charset=utf-8 -x-arango-replication-active: true -x-arango-replication-checkmore: false -x-arango-replication-lastincluded: 0 -x-arango-replication-lasttick: 300606433 -``` - -A few log events: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/logger-follow?from=300999649 - -HTTP/1.1 200 OK -content-type: application/x-arango-dump; charset=utf-8 -x-arango-replication-active: true -x-arango-replication-checkmore: false -x-arango-replication-lastincluded: 302965729 -x-arango-replication-lasttick: 302965729 - -{"tick":"301196257","type":2000,"cid":"301065185","cname":"products","collection":{"version":5,"type":2,"cid":"301065185","deleted":false,"doCompact":true,"maximalSize":1048576,"name":"products","isVolatile":false,"waitForSync":false}} -{"tick":"301720545","type":2300,"cid":"301065185","cname":"products","key":"p1","rev":"301523937","data":{"_key":"p1","_rev":"301523937","name":"flux compensator"}} -{"tick":"302179297","type":2300,"cid":"301065185","cname":"products","key":"p2","rev":"301982689","data":{"_key":"p2","_rev":"301982689","hp":5100,"name":"hybrid hovercraft"}} -{"tick":"302506977","type":2302,"cid":"301065185","cname":"products","key":"p1","rev":"302310369","oldRev":"301523937"} -{"tick":"302834657","type":2300,"cid":"301065185","cname":"products","key":"p2","rev":"302638049","oldRev":"301982689","data":{"_key":"p2","_rev":"302638049","hp":5100,"name":"broken hovercraft"}} -{"tick":"302965729","type":2001,"cid":"301065185","cname":"products"} -``` - -More events than would fit into the response: - -``` -unix> curl --dump - http://localhost:8529/_api/replication/logger-follow?from=303358945&chunkSize=400 - -HTTP/1.1 200 OK -content-type: application/x-arango-dump; charset=utf-8 -x-arango-replication-active: true -x-arango-replication-checkmore: true -x-arango-replication-lastincluded: 304079841 -x-arango-replication-lasttick: 305325025 - -{"tick":"303555553","type":2000,"cid":"303424481","cname":"products","collection":{"version":5,"type":2,"cid":"303424481","deleted":false,"doCompact":true,"maximalSize":1048576,"name":"products","isVolatile":false,"waitForSync":false}} -{"tick":"304079841","type":2300,"cid":"303424481","cname":"products","key":"p1","rev":"303883233","data":{"_key":"p1","_rev":"303883233","name":"flux compensator"}} -``` - - - +@startDocuBlock JSF_get_api_replication_logger_return_state To query the latest changes logged by the replication logger, the HTTP interface also provides the `logger-follow`. @@ -462,6 +24,5 @@ also provides the `logger-follow`. This method should be used by replication clients to incrementally fetch updates from an ArangoDB database. -@anchor HttpReplicationLoggerFollow -@copydetails triagens::arango::RestReplicationHandler::handleCommandLoggerFollow ---> \ No newline at end of file + +@startDocuBlock JSF_get_api_replication_logger_returns diff --git a/Documentation/Books/Users/HttpSimpleQuery/README.mdpp b/Documentation/Books/Users/HttpSimpleQuery/README.mdpp index 9a45b4cee1..03cf6099fd 100644 --- a/Documentation/Books/Users/HttpSimpleQuery/README.mdpp +++ b/Documentation/Books/Users/HttpSimpleQuery/README.mdpp @@ -25,1393 +25,56 @@ id of the server-side cursor in the *id* attribute in the result. This id can be used with the cursor API to fetch any outstanding results from the server and dispose the server-side cursor afterwards. -`PUT /_api/simple/all`*(executes simple query ALL)* + +@startDocuBlock JSA_put_api_simple_all -/SUBSECTION Body parameters + +@startDocuBlock JSA_put_api_simple_by_example -`query (string,required)` + +@startDocuBlock JSA_put_api_simple_first_example -Contains the query. + +@startDocuBlock JSA_put_api_simple_by_example_hash -/SUBSECTION Description + +@startDocuBlock JSA_put_api_simple_by_example_skiplist -Returns all documents of a collections. The call expects a JSON object as body with the following attributes: + +@startDocuBlock JSA_put_api_simple_by_example_bitarray -* collection: The name of the collection to query. -* skip: The number of documents to skip in the query (optional). -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional) + +@startDocuBlock JSA_put_api_simple_by_condition_skiplist -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. + +@startDocuBlock JSA_put_api_simple_by_condition_bitarray -/SUBSECTION Return codes + +@startDocuBlock JSA_put_api_simple_any -`HTTP 201` + +@startDocuBlock JSA_put_api_simple_range -is returned if the query was executed successfully. + +@startDocuBlock JSA_put_api_simple_near -`HTTP 400` + +@startDocuBlock JSA_put_api_simple_within -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. + +@startDocuBlock JSA_put_api_simple_fulltext -`HTTP 404` + +@startDocuBlock JSA_put_api_simple_remove_by_example -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. + +@startDocuBlock JSA_put_api_simple_replace_by_example -*Examples* + +@startDocuBlock JSA_put_api_simple_update_by_example -Limit the amount of documents using limit + +@startDocuBlock JSA_put_api_simple_first -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all -{ "collection": "products", "skip": 2, "limit" : 2 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/174056417", - "_rev" : "174056417", - "_key" : "174056417", - "Hello3" : "World3" - }, - { - "_id" : "products/173401057", - "_rev" : "173401057", - "_key" : "173401057", - "Hello1" : "World1" - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -Using a batchSize value - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/all -{ "collection": "products", "batchSize" : 3 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/176284641", - "_rev" : "176284641", - "_key" : "176284641", - "Hello4" : "World4" - }, - { - "_id" : "products/175956961", - "_rev" : "175956961", - "_key" : "175956961", - "Hello3" : "World3" - }, - { - "_id" : "products/175629281", - "_rev" : "175629281", - "_key" : "175629281", - "Hello2" : "World2" - } - ], - "hasMore" : true, - "id" : "176808929", - "count" : 5, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/by-example`*(executes simple query by-example)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -/SUBSECTION Description - -This will find all documents matching a given example. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* example: The example document. -* skip: The number of documents to skip in the query (optional). -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Matching an attribute: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/by-example -{ "collection": "products", "example" : { "i" : 1 } } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/192013281", - "_rev" : "192013281", - "_key" : "192013281", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - }, - { - "_id" : "products/192340961", - "_rev" : "192340961", - "_key" : "192340961", - "i" : 1, - "a" : { - "j" : 1 - } - }, - { - "_id" : "products/192603105", - "_rev" : "192603105", - "_key" : "192603105", - "i" : 1 - }, - { - "_id" : "products/192799713", - "_rev" : "192799713", - "_key" : "192799713", - "i" : 1, - "a" : { - "k" : 2, - "j" : 2 - } - } - ], - "hasMore" : false, - "count" : 4, - "error" : false, - "code" : 201 -} -``` - -Matching an attribute which is a sub-document: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/by-example -{ "collection": "products", "example" : { "a.j" : 1 } } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/194307041", - "_rev" : "194307041", - "_key" : "194307041", - "i" : 1, - "a" : { - "j" : 1 - } - }, - { - "_id" : "products/193979361", - "_rev" : "193979361", - "_key" : "193979361", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -Matching an attribute within a sub-document: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/by-example -{ "collection": "products", "example" : { "a" : { "j" : 1 } } } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/196273121", - "_rev" : "196273121", - "_key" : "196273121", - "i" : 1, - "a" : { - "j" : 1 - } - } - ], - "hasMore" : false, - "count" : 1, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/first-example`*(returns a document matching an example)* - -/SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -/SUBSECTION Description - -This will return the first document matching a given example. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* example: The example document. - -Returns a result containing the document or HTTP 404 if no document matched the example. - -If more than one document in the collection matches the specified example, only one of these documents will be returned, and it is undefined which of the matching documents is returned. - -/SUBSECTION Return codes - -`HTTP 200` - -is returned when the query was successfully executed. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -If a matching document was found: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/first-example -{ "collection": "products", "example" : { "i" : 1 } } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "document" : { - "_id" : "products/197911521", - "_rev" : "197911521", - "_key" : "197911521", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - }, - "error" : false, - "code" : 200 -} -``` - -If no document was found: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/first-example -{ "collection": "products", "example" : { "l" : 1 } } - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 404, - "errorNum" : 404, - "errorMessage" : "no match" -} -``` - -`PUT /_api/simple/by-example-hash`*(executes query by-example using a hash index)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query specification. - -/SUBSECTION Description - -This will find all documents matching a given example, using the specified hash index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* index: The id of the index to be used for the query. The index must exist and must be of type hash. -* example: an example document. The example must contain a value for each attribute in the index. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal number of documents to return. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. The same error code is also returned if an invalid index id or type is used. - -`PUT /_api/simple/by-example-skiplist`*(executes query by-example using a skiplist index)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query specification. - -/SUBSECTION Description - -This will find all documents matching a given example, using the specified skiplist index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* index: The id of the index to be used for the query. The index must exist and must be of type skiplist. -* example: an example document. The example must contain a value for each attribute in the index. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal number of documents to return. (optional) -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. The same error code is also returned if an invalid index id or type is used. - -`PUT /_api/simple/by-example-bitarray`*(executes query by-example using a bitarray index)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query specification. - -/SUBSECTION Description - -This will find all documents matching a given example, using the specified skiplist index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* index: The id of the index to be used for the query. The index must exist and must be of type bitarray. -* example: an example document. The example must contain a value for each attribute in the index. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal number of documents to return. (optional) -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. The same error code is also returned if an invalid index id or type is used. - -`PUT /_api/simple/by-condition-skiplist`*(executes query by-condition using a skiplist index)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query specification. - -/SUBSECTION Description - -This will find all documents matching a given condition, using the specified skiplist index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* index: The id of the index to be used for the query. The index must exist and must be of type skiplist. -* condition: the condition which all returned documents shall satisfy. Conditions must be specified for all indexed attributes. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal number of documents to return. (optional) -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. The same error code is also returned if an invalid index id or type is used. - -`PUT /_api/simple/by-condition-bitarray`*(executes query by-condition using a bitarray index)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query specification. - -/SUBSECTION Description - -This will find all documents matching a given condition, using the specified skiplist index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* index: The id of the index to be used for the query. The index must exist and must be of type bitarray. -* condition: the condition which all returned documents shall satisfy. Conditions must be specified for all indexed attributes. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal number of documents to return. (optional) -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. The same error code is also returned if an invalid index id or type is used. - -`PUT /_api/simple/any`*(returns a random document from a collection)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -/SUBSECTION Description - -Returns a random document from a collection. The call expects a JSON object as body with the following attributes: - -* collection: The identifier or name of the collection to query. -Returns a JSON object with the document stored in the attribute document if the collection contains at least one document. If the collection is empty, the document attrbute contains null. - -/SUBSECTION Return codes - -`HTTP 200` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/any -{ "collection": "products" } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "document" : { - "_id" : "products/178512865", - "_rev" : "178512865", - "_key" : "178512865", - "Hello5" : "World5" - }, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/simple/range`*(executes simple range query)* - -/SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -/SUBSECTION Description - -This will find all documents within a given range. In order to execute a range query, a skip-list index on the queried attribute must be present. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* attribute: The attribute path to check. -* left: The lower bound. -* right: The upper bound. -* closed: If true, use interval including left and right, otherwise exclude right, but include left. -* skip: The number of documents to skip in the query (optional). -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/range -{ "collection": "products", "attribute" : "i", "left" : 2, "right" : 4 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/208069601", - "_rev" : "208069601", - "_key" : "208069601", - "i" : 2 - }, - { - "_id" : "products/208266209", - "_rev" : "208266209", - "_key" : "208266209", - "i" : 3 - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/near`*(executes a near query)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -/SUBSECTION Description - -The default will find at most 100 documents near the given coordinate. The returned list is sorted according to the distance, with the nearest document being first in the list. If there are near documents of equal distance, documents are chosen randomly from this set until the limit is reached. - -In order to use the near operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the geo field to select a particular index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* latitude: The latitude of the coordinate. -* longitude: The longitude of the coordinate. -* distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional) -* geo: If given, the identifier of the geo-index to use. (optional) -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Without distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 2 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/180478945", - "_rev" : "180478945", - "_key" : "180478945", - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/180085729", - "_rev" : "180085729", - "_key" : "180085729", - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -With distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 3, "distance" : "distance" } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/182969313", - "_rev" : "182969313", - "_key" : "182969313", - "distance" : 222.38985328911744, - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - }, - { - "_id" : "products/183362529", - "_rev" : "183362529", - "_key" : "183362529", - "distance" : 222.38985328911744, - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/182772705", - "_rev" : "182772705", - "_key" : "182772705", - "distance" : 444.779706578235, - "name" : "Name/-0.004/", - "loc" : [ - -0.004, - 0 - ] - } - ], - "hasMore" : false, - "count" : 3, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/within`*(executes a within query)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -/SUBSECTION Description - -This will find all documents within a given radius around the coordinate (latitude, longitude). The returned list is sorted by distance. - -In order to use the within operator, a geo index must be defined for the collection. This index also defines which attribute holds the coordinates for the document. If you have more then one geo-spatial index, you can use the geo field to select a particular index. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* latitude: The latitude of the coordinate. -* longitude: The longitude of the coordinate. -* radius: The maximal radius (in meters). -* distance: If given, the attribute key used to return the distance to the given coordinate. (optional). If specified, distances are returned in meters. -* skip: The number of documents to skip in the query. (optional) -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. The default is 100. (optional) -* geo: If given, the identifier of the geo-index to use. (optional) - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -Without distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 2, "radius" : 500 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/186246113", - "_rev" : "186246113", - "_key" : "186246113", - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/185852897", - "_rev" : "185852897", - "_key" : "185852897", - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -With distance: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/near -{ "collection": "products", "latitude" : 0, "longitude" : 0, "skip" : 1, "limit" : 3, "distance" : "distance", "radius" : 300 } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/188736481", - "_rev" : "188736481", - "_key" : "188736481", - "distance" : 222.38985328911744, - "name" : "Name/-0.002/", - "loc" : [ - -0.002, - 0 - ] - }, - { - "_id" : "products/189129697", - "_rev" : "189129697", - "_key" : "189129697", - "distance" : 222.38985328911744, - "name" : "Name/0.002/", - "loc" : [ - 0.002, - 0 - ] - }, - { - "_id" : "products/188539873", - "_rev" : "188539873", - "_key" : "188539873", - "distance" : 444.779706578235, - "name" : "Name/-0.004/", - "loc" : [ - -0.004, - 0 - ] - } - ], - "hasMore" : false, - "count" : 3, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/fulltext`*(executes a fulltext index query)* - -/SUBSECTION Body parameters - -`query (string,required)` - -Contains the query. - -/SUBSECTION Description - -This will find all documents from the collection that match the fulltext query specified in query. - -In order to use the fulltext operator, a fulltext index must be defined for the collection and the specified attribute. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to query. -* attribute: The attribute that contains the texts. -* query: The fulltext query. -* skip: The number of documents to skip in the query (optional). -* limit: The maximal amount of documents to return. The skip is applied before the limit restriction. (optional) -* index: The identifier of the fulltext-index to use. - -Returns a cursor containing the result, see HTTP Interface for AQL Query Cursors for details. - -/SUBSECTION Return codes - -`HTTP 201` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/fulltext -{ "collection": "products", "attribute" : "text", "query" : "word" } - -HTTP/1.1 201 Created -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/190571489", - "_rev" : "190571489", - "_key" : "190571489", - "text" : "this text contains word" - }, - { - "_id" : "products/190768097", - "_rev" : "190768097", - "_key" : "190768097", - "text" : "this text also has a word" - } - ], - "hasMore" : false, - "count" : 2, - "error" : false, - "code" : 201 -} -``` - -`PUT /_api/simple/remove-by-example`*(removes documents by example)* - -/SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -/SUBSECTION Description - -This will find all documents in the collection that match the specified example object. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to remove from. -* example: An example document that all collection documents are compared against. -* waitForSync: if set to true, then all removal operations will instantly be synchronised to disk. If this is not specified, then the collection's default sync behavior will be applied. -* limit: an optional value that determines how many documents to delete at most. If limit is specified but is less than the number of documents in the collection, it is undefined which of the documents will be deleted. - -*Note*: the limit attribute is not supported on sharded collections. Using it will result in an error. - -Returns the number of documents that were deleted. - -/SUBSECTION Return codes - -`HTTP 200` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/remove-by-example -{ "collection": "products", "example" : { "a" : { "j" : 1 } } } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "deleted" : 1, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/simple/replace-by-example`*(replaces documents by example)* - -/SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -/SUBSECTION Description - -This will find all documents in the collection that match the specified example object, and replace the entire document body with the new value specified. Note that document meta-attributes such as _id, _key, _from, _to etc. cannot be replaced. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to replace within. -* example: An example document that all collection documents are compared against. -* newValue: The replacement document that will get inserted in place of the "old" documents. -* waitForSync: if set to true, then all removal operations will instantly be synchronised to disk. If this is not specified, then the collection's default sync behavior will be applied. -* limit: an optional value that determines how many documents to replace at most. If limit is specified but is less than the number of documents in the collection, it is undefined which of the documents will be replaced. - -*Note*: the limit attribute is not supported on sharded collections. Using it will result in an error. - -Returns the number of documents that were replaced. - -/SUBSECTION Return codes - -`HTTP 200` - -is returned if the query was executed successfully. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/replace-by-example -{ "collection": "products", "example" : { "a" : { "j" : 1 } }, "newValue" : {"foo" : "bar"}, "limit" : 3 } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "replaced" : 1, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/simple/update-by-example`*(updates documents by example)* - -/SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -/SUBSECTION Description - -This will find all documents in the collection that match the specified example object, and partially update the document body with the new value specified. Note that document meta-attributes such as _id, _key, _from, _to etc. cannot be replaced. - -The call expects a JSON object as body with the following attributes: - -* collection: The name of the collection to update within. -* example: An example document that all collection documents are compared against. -* newValue: A document containing all the attributes to update in the found documents. -* keepNull: This 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 updated document. -* waitForSync: if set to true, then all removal operations will instantly be synchronised to disk. If this is not specified, then the collection's default sync behavior will be applied. -* limit: an optional value that determines how many documents to update at most. If limit is specified but is less than the number of documents in the collection, it is undefined which of the documents will be updated. - -*Note*: the limit attribute is not supported on sharded collections. Using it will result in an error. - -Returns the number of documents that were updated. - -/SUBSECTION Return codes - -`HTTP 200` - -is returned if the collection was updated successfully and waitForSync was true. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. - -*Examples* - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/update-by-example -{ "collection": "products", "example" : { "a" : { "j" : 1 } }, "newValue" : { "a" : { "j" : 22 } }, "limit" : 3 } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "updated" : 1, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/simple/first`*(returns the first document(s) of a collection)* - -/SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -/SUBSECTION Description - -This will return the first document(s) from the collection, in the order of insertion/update time. When the count argument is supplied, the result will be a list of documents, with the "oldest" document being first in the result list. If the count argument is not supplied, the result is the "oldest" document of the collection, or null if the collection is empty. - -The request body must be a JSON object with the following attributes: - -* collection: the name of the collection -* count: the number of documents to return at most. Specifiying count is optional. If it is not specified, it defaults to 1. - -*Note*: this method is not supported for sharded collections with more than one shard. - -/SUBSECTION Return codes - -`HTTP 200` - -is returned when the query was successfully executed. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. -*Examples* - -Retrieving the first n documents: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/first -{ "collection": "products", "count" : 2 } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/201712609", - "_rev" : "201712609", - "_key" : "201712609", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - }, - { - "_id" : "products/202040289", - "_rev" : "202040289", - "_key" : "202040289", - "i" : 1, - "a" : { - "j" : 1 - } - } - ], - "error" : false, - "code" : 200 -} -``` - -Retrieving the first document: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/first -{ "collection": "products" } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : { - "_id" : "products/203285473", - "_rev" : "203285473", - "_key" : "203285473", - "i" : 1, - "a" : { - "k" : 1, - "j" : 1 - } - }, - "error" : false, - "code" : 200 -} -``` - -`PUT /_api/simple/last`*(returns the last document(s) of a collection)* - -/SUBSECTION Body parameters - -`query (json,required)` - -Contains the query. - -/SUBSECTION Description - -This will return the last documents from the collection, in the order of insertion/update time. When the count argument is supplied, the result will be a list of documents, with the "latest" document being first in the result list. - -The request body must be a JSON object with the following attributes: - -* collection: the name of the collection -* count: the number of documents to return at most. Specifiying count is optional. If it is not specified, it defaults to 1. - -If the count argument is not supplied, the result is the "latest" document of the collection, or null if the collection is empty. - -*Note*: this method is not supported for sharded collections with more than one shard. - -/SUBSECTION Return codes - -`HTTP 200` - -is returned when the query was successfully executed. - -`HTTP 400` - -is returned if the body does not contain a valid JSON representation of a query. The response body contains an error document in this case. - -`HTTP 404` - -is returned if the collection specified by collection is unknown. The response body contains an error document in this case. -*Examples* - -Retrieving the last n documents: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/last -{ "collection": "products", "count" : 2 } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : [ - { - "_id" : "products/205644769", - "_rev" : "205644769", - "_key" : "205644769", - "i" : 1, - "a" : { - "k" : 2, - "j" : 2 - } - }, - { - "_id" : "products/205448161", - "_rev" : "205448161", - "_key" : "205448161", - "i" : 1 - } - ], - "error" : false, - "code" : 200 -} -``` - -Retrieving the first document: - -``` -unix> curl -X PUT --data-binary @- --dump - http://localhost:8529/_api/simple/last -{ "collection": "products" } - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : { - "_id" : "products/207217633", - "_rev" : "207217633", - "_key" : "207217633", - "i" : 1, - "a" : { - "k" : 2, - "j" : 2 - } - }, - "error" : false, - "code" : 200 -} -``` - - - \ No newline at end of file + +@startDocuBlock JSA_put_api_simple_last \ No newline at end of file diff --git a/Documentation/Books/Users/HttpTransaction/README.mdpp b/Documentation/Books/Users/HttpTransaction/README.mdpp index 405f385531..cb100097a3 100644 --- a/Documentation/Books/Users/HttpTransaction/README.mdpp +++ b/Documentation/Books/Users/HttpTransaction/README.mdpp @@ -18,152 +18,5 @@ rolled back. For a more detailed description of how transactions work in ArangoDB please refer to [Transactions](../Transactions/README.md). -!SECTION Executing Transactions via HTTP - -`POST /_api/transaction`*(executes a transaction)* - -!SUBSECTION Body parameters - -`body (string,required)` - -Contains the collections and action. - -!SUBSECTION Description - -The transaction description must be passed in the body of the POST request. - -The following attributes must be specified inside the JSON object: - -*collections*: contains the list of collections to be used in the transaction (mandatory). collections must be a JSON array that can have the optional sub-attributes read and write. read and write must each be either lists of collections names or strings with a single collection name. -action: the actual transaction operations to be executed, in the form of stringified Javascript code. The code will be executed on server side, with late binding. It is thus critical that the code specified in action properly sets up all the variables it needs. If the code specified in action ends with a return statement, the value returned will also be returned by the REST API in the result attribute if the transaction committed successfully. -The following optional attributes may also be specified in the request: - -*waitForSync*: an optional boolean flag that, if set, will force the transaction to write all data to disk before returning. -lockTimeout: an optional 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. -replicate: whether or not to replicate the operations from this transaction. If not specified, the default value is true. -params: optional arguments passed to action. -If the transaction is fully executed and committed on the server, HTTP 200 will be returned. Additionally, the return value of the code defined in action will be returned in the result attribute. - -For successfully committed transactions, the returned JSON object has the following properties: - -* error: boolean flag to indicate if an error occurred (false in this case) -* code: the HTTP status code -* result: the return value of the transaction - -If the transaction specification is either missing or malformed, the server will respond with HTTP 400. - -The body of the response will then contain a JSON object with additional error details. The object has the following attributes: - -* error: boolean flag to indicate that an error occurred (true in this case) -* code: the HTTP status code -* errorNum: the server error number -* errorMessage: a descriptive error message - -If a transaction fails to commit, either by an exception thrown in the action code, or by an internal error, the server will respond with an error. Any other errors will be returned with any of the return codes HTTP 400, HTTP 409, or HTTP 500. - -!SUBSECTION Return codes - -`HTTP 200` - -If the transaction is fully executed and committed on the server, HTTP 200 will be returned. - -`HTTP 400` - -If the transaction specification is either missing or malformed, the server will respond with HTTP 400. - -`HTTP 404` - -If the transaction specification contains an unknown collection, the server will respond with HTTP 404. - -`HTTP 500` - -Exceptions thrown by users will make the server respond with a return code of HTTP 500 - -*Examples* - -Executing a transaction on a single collection: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction -{"collections":{"write":"products"},"action":"function () { var db = require('internal').db; db.products.save({}); return db.products.count(); }"} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : 1, - "error" : false, - "code" : 200 -} -``` - -Executing a transaction using multiple collections: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction -{"collections":{"write":["products","materials"]},"action":"function () { var db = require('internal').db; db.products.save({}); db.materials.save({}); return 'worked!'; }"} - -HTTP/1.1 200 OK -content-type: application/json; charset=utf-8 - -{ - "result" : "worked!", - "error" : false, - "code" : 200 -} -``` - -Aborting a transaction due to an internal error: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction -{"collections":{"write":"products"},"action":"function () { var db = require('internal').db; db.products.save({ _key: 'abc'}); db.products.save({ _key: 'abc'}); }"} - -HTTP/1.1 400 Bad Request -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 400, - "errorNum" : 1210, - "errorMessage" : "unique constraint violated" -} -``` - -Aborting a transaction by explicitly throwing an exception: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction -{"collections":{"read":"products"},"action":"function () { throw 'doh!'; }"} - -HTTP/1.1 500 Internal Error -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 500, - "errorNum" : 500, - "errorMessage" : "doh!" -} -``` - -Referring to a non-existing collection: - -``` -unix> curl -X POST --data-binary @- --dump - http://localhost:8529/_api/transaction -{"collections":{"read":"products"},"action":"function () { return true; }"} - -HTTP/1.1 404 Not Found -content-type: application/json; charset=utf-8 - -{ - "error" : true, - "code" : 404, - "errorNum" : 1203, - "errorMessage" : "collection not found" -} -``` - \ No newline at end of file + +@startDocuBlock JSF_post_api_transaction diff --git a/Documentation/Books/Users/SUMMARY.md b/Documentation/Books/Users/SUMMARY.md index e361abd471..0e41c8fe5a 100644 --- a/Documentation/Books/Users/SUMMARY.md +++ b/Documentation/Books/Users/SUMMARY.md @@ -138,7 +138,6 @@ * [Databases](HttpDatabase/README.md) * [To-Endpoint](HttpDatabase/DatabaseEndpoint.md) * [Management](HttpDatabase/DatabaseManagement.md) - * [Managing (http)](HttpDatabase/ManagingDatabasesUsingHttp.md) * [Note on Databases](HttpDatabase/NotesOnDatabases.md) * [Documents](HttpDocument/README.md) * [Address and ETag](HttpDocument/AddressAndEtag.md) @@ -153,12 +152,10 @@ * [AQL User Functions Management](HttpAqlUserFunctions/README.md) * [Simple Queries](HttpSimpleQuery/README.md) * [Collections](HttpCollection/README.md) - * [Address](HttpCollection/Address.md) * [Creating](HttpCollection/Creating.md) * [Getting Information](HttpCollection/Getting.md) * [Modifying](HttpCollection/Modifying.md) * [Indexes](HttpIndexes/README.md) - * [Address of an Index](HttpIndexes/Address.md) * [Working with Indexes](HttpIndexes/WorkingWith.md) * [Cap Constraints](HttpIndexes/Cap.md) * [Hash](HttpIndexes/Hash.md) diff --git a/Documentation/Books/bot.py b/Documentation/Books/bot.py index c3b33d27bb..e0b2e5ca6b 100644 --- a/Documentation/Books/bot.py +++ b/Documentation/Books/bot.py @@ -40,18 +40,26 @@ def replaceText(text, pathOfFile, searchText): # HTTP API changing code replaced = replaced.replace("@brief","") - replaced = re.sub(r"@RESTHEADER{([\s\w\/\_-]*),([\s\w]*)}", r"###\g<2>\n `\g<1>`", replaced) + replaced = re.sub(r"@RESTHEADER{([\s\w\/\_{}-]*),([\s\w-]*)}", r"###\g<2>\n `\g<1>`", replaced) replaced = replaced.replace("@RESTDESCRIPTION","") - replaced = replaced.replace("@RESTURLPARAMS","*URL Parameters*\n") - replaced = replaced.replace("@RESTQUERYPARAMS","*Query Parameters*\n") - replaced = replaced.replace("@RESTHEADERPARAMS","*Header Parameters*\n") - replaced = replaced.replace("@RESTBODYPARAMS","*Body Parameters*\n") - replaced = replaced.replace("@RESTRETURNCODES","*Return Codes*") + replaced = replaced.replace("@RESTURLPARAMETERS","**URL Parameters**\n") + replaced = replaced.replace("@RESTURLPARAMS","**URL Parameters**\n") + replaced = replaced.replace("@RESTQUERYPARAMS","**Query Parameters**\n") + replaced = replaced.replace("@RESTQUERYPARAMETERS","**Query Parameters**\n") + replaced = replaced.replace("@RESTHEADERPARAMS","**Header Parameters**\n") + replaced = replaced.replace("@RESTHEADERPARAMETERS","**Header Parameters**\n") + replaced = replaced.replace("@RESTBODYPARAMS","**Body Parameters**\n") + replaced = replaced.replace("@RESTBODYPARAMETERS","**Body Parameters**\n") + replaced = replaced.replace("@RESTRETURNCODES","**Return Codes**\n") + replaced = replaced.replace("@RESTURLPARAM", "@RESTPARAM") + replaced = replaced.replace("@RESTHEADERPARAM", "@RESTPARAM") + replaced = replaced.replace("@RESTQUERYPARAM", "@RESTPARAM") + replaced = replaced.replace("@RESTBODYPARAM", "@RESTPARAM") replaced = re.sub(r"@RESTPARAM{([\s\w\-]*),([\s\w\_\|-]*),\s[optional]}", r"* *\g<1>* (\g<3>):", replaced) replaced = re.sub(r"@RESTPARAM{([\s\w-]*),([\s\w\_\|-]*),\s*(\w+)}", r"* *\g<1>*:", replaced) - replaced = re.sub(r"@RESTRETURNCODE{(.*)}", r"* *HTTP \g<1>*:", replaced) + replaced = re.sub(r"@RESTRETURNCODE{(.*)}", r"* *\g<1>*:", replaced) replaced = re.sub(r"@RESTBODYPARAMS{(.*)}", r"*(\g<1>)*", replaced) - replaced = replaced.replace("@EXAMPLES","*Examples*") + replaced = replaced.replace("@EXAMPLES","**Examples**") f.write(replaced) f.close() diff --git a/Documentation/Examples/api-cursor-create-for-limit-return b/Documentation/Examples/api-cursor-create-for-limit-return deleted file mode 100644 index 1c11310728..0000000000 --- a/Documentation/Examples/api-cursor-create-for-limit-return +++ /dev/null @@ -1,27 +0,0 @@ -> curl --data @- -X POST --dump - http://localhost:8529/_api/cursor -{ "query" : "FOR u IN users LIMIT 5 RETURN u", "count" : true, "batchSize" : 2 } - -HTTP/1.1 201 Created -content-type: application/json - -{ - "hasMore" : true, - "error" : false, - "id" : "26011191", - "result" : [ - { - "name" : "user1", - "_rev" : "258801191", - "_key" : "258801191", - "_id" : "users/258801191" - }, - { - "name" : "user2", - "_rev" : "258801192", - "_key" : "258801192", - "_id" : "users/258801192" - } - ], - "code" : 201, - "count" : 5 -} diff --git a/Documentation/Examples/api-cursor-create-for-limit-return-cont b/Documentation/Examples/api-cursor-create-for-limit-return-cont deleted file mode 100644 index 538d826236..0000000000 --- a/Documentation/Examples/api-cursor-create-for-limit-return-cont +++ /dev/null @@ -1,26 +0,0 @@ -> curl -X PUT --dump - http://localhost:8529/_api/cursor/26011191 - -HTTP/1.1 200 OK -content-type: application/json - -{ - "hasMore" : true, - "error" : false, - "id" : "26011191", - "result": [ - { - "name" : "user3", - "_rev" : "258801193", - "_key" : "258801193", - "_id" : "users/258801193" - }, - { - "name" : "user4", - "_rev" : "258801194", - "_key" : "258801194", - "_id" : "users/258801194" - } - ], - "code" : 200, - "count" : 5 -} diff --git a/Documentation/Examples/api-cursor-create-for-limit-return-cont2 b/Documentation/Examples/api-cursor-create-for-limit-return-cont2 deleted file mode 100644 index 8c53ae17fb..0000000000 --- a/Documentation/Examples/api-cursor-create-for-limit-return-cont2 +++ /dev/null @@ -1,19 +0,0 @@ -> curl -X PUT --dump - http://localhost:8529/_api/cursor/26011191 - -HTTP/1.1 200 OK -content-type: application/json - -{ - "hasMore" : false, - "error" : false, - "result" : [ - { - "name" : "user5", - "_rev" : "258801195", - "_key" : "258801195", - "_id" : "users/258801195" - } - ], - "code" : 200, - "count" : 5 -} diff --git a/Documentation/Examples/api-cursor-create-for-limit-return-cont3 b/Documentation/Examples/api-cursor-create-for-limit-return-cont3 deleted file mode 100644 index 8f66349c84..0000000000 --- a/Documentation/Examples/api-cursor-create-for-limit-return-cont3 +++ /dev/null @@ -1,11 +0,0 @@ -> curl -X PUT --dump - http://localhost:8529/_api/cursor/26011191 - -HTTP/1.1 404 Not Found -content-type: application/json - -{ - "errorNum": 1600, - "errorMessage": "cursor not found: disposed or unknown cursor", - "error": true, - "code": 404 -} diff --git a/Documentation/Examples/api-cursor-create-for-limit-return-single b/Documentation/Examples/api-cursor-create-for-limit-return-single deleted file mode 100644 index 70422877d5..0000000000 --- a/Documentation/Examples/api-cursor-create-for-limit-return-single +++ /dev/null @@ -1,26 +0,0 @@ -> curl --data @- -X POST --dump - http://localhost:8529/_api/cursor -{ "query" : "FOR u IN users LIMIT 2 RETURN u", "count" : true, "batchSize" : 2 } - -HTTP/1.1 201 Created -content-type: application/json - -{ - "hasMore" : false, - "error" : false, - "result" : [ - { - "name" : "user1", - "_rev" : "210304551", - "_key" : "210304551", - "_id" : "users/210304551" - }, - { - "name" : "user2", - "_rev" : "210304552", - "_key" : "210304552", - "_id" : "users/210304552" - } - ], - "code" : 201, - "count" : 2 -} diff --git a/arangod/RestHandler/RestDocumentHandler.cpp b/arangod/RestHandler/RestDocumentHandler.cpp index 4aaf151fa7..0a2c356f5f 100644 --- a/arangod/RestHandler/RestDocumentHandler.cpp +++ b/arangod/RestHandler/RestDocumentHandler.cpp @@ -96,9 +96,10 @@ HttpHandler::status_t RestDocumentHandler::execute () { // ----------------------------------------------------------------------------- //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock REST_DOCUMENT_CREATE /// @brief creates a document /// -/// @RESTHEADER{POST /_api/document,creates a document} +/// @RESTHEADER{POST /_api/document,Create document} /// /// @RESTBODYPARAM{document,json,required} /// A JSON representation of the document. @@ -109,18 +110,18 @@ HttpHandler::status_t RestDocumentHandler::execute () { /// The collection name. /// /// @RESTQUERYPARAM{createCollection,boolean,optional} -/// If this parameter has a value of `true` or `yes`, then the collection is +/// If this parameter has a value of *true* or *yes*, then the collection is /// created if it does not yet exist. Other values will be ignored so the /// collection must be present for the operation to succeed. /// -/// Note: this flag is not supported in a cluster. Using it will result in an +/// **Note**: this flag is not supported in a cluster. Using it will result in an /// error. /// /// @RESTQUERYPARAM{waitForSync,boolean,optional} /// Wait until document has been synced to disk. /// /// @RESTDESCRIPTION -/// Creates a new document in the collection named `collection`. A JSON +/// Creates a new document in the collection named *collection*. A JSON /// representation of the document must be passed as the body of the POST /// request. /// @@ -131,45 +132,45 @@ HttpHandler::status_t RestDocumentHandler::execute () { /// The body of the response contains a JSON object with the following /// attributes: /// -/// - `_id` contains the document handle of the newly created document -/// - `_key` contains the document key -/// - `_rev` contains the document revision +/// - *_id* contains the document handle of the newly created document +/// - *_key* contains the document key +/// - *_rev* contains the document revision /// -/// If the collection parameter `waitForSync` is `false`, then the call returns +/// If the collection parameter *waitForSync* is *false*, then the call returns /// as soon as the document has been accepted. It will not wait until the /// document has been synced to disk. /// -/// Optionally, the URL parameter `waitForSync` can be used to force +/// Optionally, the URL parameter *waitForSync* can be used to force /// synchronisation of the document creation operation to disk even in case that -/// the `waitForSync` flag had been disabled for the entire collection. Thus, -/// the `waitForSync` URL parameter can be used to force synchronisation of just -/// this 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` URL parameter cannot be used to disable synchronisation for -/// collections that have a default `waitForSync` value of `true`. +/// the *waitForSync* flag had been disabled for the entire collection. Thus, +/// the *waitForSync* URL parameter can be used to force synchronisation of just +/// this 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* URL parameter cannot be used to disable synchronisation for +/// collections that have a default *waitForSync* value of *true*. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{201} -/// is returned if the document was created successfully and `waitForSync` was -/// `true`. +/// is returned if the document was created successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} -/// is returned if the document was created successfully and `waitForSync` was -/// `false`. +/// is returned if the document was created successfully and *waitForSync* was +/// *false*. /// /// @RESTRETURNCODE{400} /// is returned if the body does not contain a valid JSON representation of a /// document. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// /// @EXAMPLES /// -/// Create a document given a collection named `products`. Note that the +/// Create a document given a collection named *products*. Note that the /// revision identifier might or might not by equal to the auto-generated /// key. /// @@ -188,8 +189,8 @@ HttpHandler::status_t RestDocumentHandler::execute () { /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN /// -/// Create a document in a collection named `products` with a collection-level -/// `waitForSync` value of `false`. +/// Create a document in a collection named *products* with a collection-level +/// *waitForSync* value of *false*. /// /// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostAccept1} /// var cn = "products"; @@ -206,8 +207,8 @@ HttpHandler::status_t RestDocumentHandler::execute () { /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN /// -/// Create a document in a collection with a collection-level `waitForSync` -/// value of `false`, but using the `waitForSync` URL parameter. +/// Create a document in a collection with a collection-level *waitForSync* +/// value of *false*, but using the *waitForSync* URL parameter. /// /// @EXAMPLE_ARANGOSH_RUN{RestDocumentHandlerPostWait1} /// var cn = "products"; @@ -271,6 +272,7 @@ HttpHandler::status_t RestDocumentHandler::execute () { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestDocumentHandler::createDocument () { @@ -424,9 +426,10 @@ bool RestDocumentHandler::readDocument () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock REST_DOCUMENT_READ /// @brief reads a single document /// -/// @RESTHEADER{GET /_api/document/`document-handle`,reads a document} +/// @RESTHEADER{GET /_api/document/document-handle,Read document} /// /// @RESTURLPARAMETERS /// @@ -438,18 +441,18 @@ bool RestDocumentHandler::readDocument () { /// @RESTHEADERPARAM{If-None-Match,string,optional} /// If the "If-None-Match" header is given, then it must contain exactly one /// etag. The document is returned, if it has a different revision than the -/// given etag. Otherwise an `HTTP 304` is returned. +/// given etag. Otherwise an *HTTP 304* is returned. /// /// @RESTHEADERPARAM{If-Match,string,optional} /// If the "If-Match" header is given, then it must contain exactly one /// etag. The document is returned, if it has the same revision ad the -/// given etag. Otherwise a `HTTP 412` is returned. As an alternative -/// you can supply the etag in an attribute `rev` in the URL. +/// given etag. Otherwise a *HTTP 412* is returned. As an alternative +/// you can supply the etag in an attribute *rev* in the URL. /// /// @RESTDESCRIPTION -/// Returns the document identified by `document-handle`. The returned -/// document contains two special attributes: `_id` containing the document -/// handle and `_rev` containing the revision. +/// Returns the document identified by *document-handle*. The returned +/// document contains two special attributes: *_id* containing the document +/// handle and *_rev* containing the revision. /// /// @RESTRETURNCODES /// @@ -464,10 +467,10 @@ bool RestDocumentHandler::readDocument () { /// is returned if the document or collection was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. /// /// @EXAMPLES /// @@ -515,6 +518,7 @@ bool RestDocumentHandler::readDocument () { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestDocumentHandler::readSingleDocument (bool generateBody) { @@ -662,9 +666,10 @@ bool RestDocumentHandler::getDocumentCoordinator ( } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock REST_DOCUMENT_READ_ALL /// @brief reads all documents from collection /// -/// @RESTHEADER{GET /_api/document,reads all documents from collection} +/// @RESTHEADER{GET /_api/document,Read all documents} /// /// @RESTQUERYPARAMETERS /// @@ -673,7 +678,7 @@ bool RestDocumentHandler::getDocumentCoordinator ( /// /// @RESTDESCRIPTION /// Returns a list of all URI for all documents from the collection identified -/// by `collection`. +/// by *collection*. /// /// @RESTRETURNCODES /// @@ -717,7 +722,7 @@ bool RestDocumentHandler::getDocumentCoordinator ( /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN -/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestDocumentHandler::readAllDocuments () { @@ -821,9 +826,10 @@ bool RestDocumentHandler::getAllDocumentsCoordinator ( } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock REST_DOCUMENT_READ_HEAD /// @brief reads a single document head /// -/// @RESTHEADER{HEAD /_api/document/`document-handle`,reads a document header} +/// @RESTHEADER{HEAD /_api/document/document-handle,Read document header} /// /// @RESTURLPARAMETERS /// @@ -834,22 +840,22 @@ bool RestDocumentHandler::getAllDocumentsCoordinator ( /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally fetch a document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-None-Match,string,optional} /// If the "If-None-Match" header is given, then it must contain exactly one /// etag. If the current document revision is different to the specified etag, -/// an `HTTP 200` response is returned. If the current document revision is -/// identical to the specified etag, then an `HTTP 304` is returned. +/// an *HTTP 200* response is returned. If the current document revision is +/// identical to the specified etag, then an *HTTP 304* is returned. /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally fetch a document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION -/// Like `GET`, but only returns the header fields and not the body. You +/// Like *GET*, but only returns the header fields and not the body. You /// can use this call to get the current revision of a document or check if /// the document was deleted. /// @@ -861,14 +867,14 @@ bool RestDocumentHandler::getAllDocumentsCoordinator ( /// @RESTRETURNCODE{304} /// is returned if the "If-None-Match" header is given and the document has /// same version -/// +///* /// @RESTRETURNCODE{404} /// is returned if the document or collection was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `etag` header. +/// document's current revision in the *etag* header. /// /// @EXAMPLES /// @@ -884,6 +890,8 @@ bool RestDocumentHandler::getAllDocumentsCoordinator ( /// /// assert(response.code === 200); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestDocumentHandler::checkDocument () { @@ -900,9 +908,10 @@ bool RestDocumentHandler::checkDocument () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock REST_DOCUMENT_REPLACE /// @brief replaces a document /// -/// @RESTHEADER{PUT /_api/document/`document-handle`,replaces a document} +/// @RESTHEADER{PUT /_api/document/document-handle,Replace document} /// /// @RESTBODYPARAM{document,json,required} /// A JSON representation of the new document. @@ -919,94 +928,94 @@ bool RestDocumentHandler::checkDocument () { /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally replace a document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTQUERYPARAM{policy,string,optional} /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter (see below). +/// can use the *policy* parameter (see below). /// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally replace a document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION -/// Completely updates (i.e. replaces) the document identified by `document-handle`. -/// If the document exists and can be updated, then a `HTTP 201` is returned +/// Completely updates (i.e. replaces) the document identified by *document-handle*. +/// If the document exists and can be updated, then a *HTTP 201* is returned /// and the "ETag" header field contains the new revision of the document. /// /// If the new document passed in the body of the request contains the -/// `document-handle` in the attribute `_id` and the revision in `_rev`, +/// *document-handle* in the attribute *_id* and the revision in *_rev*, /// these attributes will be ignored. Only the URI and the "ETag" header are /// relevant in order to avoid confusion when using proxies. /// -/// Optionally, the URL parameter `waitForSync` can be used to force +/// Optionally, the URL parameter *waitForSync* can be used to force /// synchronisation of the document replacement operation to disk even in case -/// that the `waitForSync` flag had been disabled for the entire collection. -/// Thus, the `waitForSync` URL parameter can be used to force synchronisation -/// 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` URL parameter cannot be used to disable -/// synchronisation for collections that have a default `waitForSync` value -/// of `true`. +/// that the *waitForSync* flag had been disabled for the entire collection. +/// Thus, the *waitForSync* URL parameter can be used to force synchronisation +/// 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* URL parameter cannot be used to disable +/// synchronisation for collections that have a default *waitForSync* value +/// of *true*. /// /// The body of the response contains a JSON object with the information about -/// the handle and the revision. The attribute `_id` contains the known -/// `document-handle` of the updated document, the attribute `_rev` +/// the handle and the revision. The attribute *_id* contains the known +/// *document-handle* of the updated document, the attribute *_rev* /// contains the new document revision. /// -/// If the document does not exist, then a `HTTP 404` is returned and the +/// If the document does not exist, then a *HTTP 404* is returned and the /// body of the response contains an error document. /// /// There are two ways for specifying the targeted document revision id for /// conditional replacements (i.e. replacements that will only be executed if /// the revision id found in the database matches the document revision id specified /// in the request): -/// - specifying the target revision in the `rev` URL query parameter -/// - specifying the target revision in the `if-match` HTTP header +/// - specifying the target revision in the *rev* URL query parameter +/// - specifying the target revision in the *if-match* HTTP header /// /// Specifying a target revision is optional, however, if done, only one of the -/// described mechanisms must be used (either the `rev` URL parameter or the -/// `if-match` HTTP header). +/// described mechanisms must be used (either the *rev* URL parameter or the +/// *if-match* HTTP header). /// Regardless which mechanism is used, the parameter needs to contain the target -/// document revision id as returned in the `_rev` attribute of a document or -/// by an HTTP `etag` header. +/// document revision id as returned in the *_rev* attribute of a document or +/// by an HTTP *etag* header. /// /// For example, to conditionally replace a document based on a specific revision /// id, you can use the following request: /// -/// - PUT /_api/document/`document-handle`?rev=`etag` +/// `PUT /_api/document/document-handle?rev=etag` /// -/// If a target revision id is provided in the request (e.g. via the `etag` value -/// in the `rev` URL query parameter above), ArangoDB will check that +/// If a target revision id is provided in the request (e.g. via the *etag* value +/// in the *rev* URL query parameter above), ArangoDB will check that /// the revision id of the document found in the database is equal to the target /// revision id provided in the request. If there is a mismatch between the revision -/// id, then by default a `HTTP 412` conflict is returned and no replacement is +/// id, then by default a *HTTP 412* conflict is returned and no replacement is /// performed. /// -/// The conditional update behavior can be overriden with the `policy` URL query parameter: +/// The conditional update behavior can be overriden with the *policy* URL query parameter: /// -/// - PUT /_api/document/`document-handle`?policy=`policy` +/// `PUT /_api/document/document-handle?policy=policy` /// -/// If `policy` is set to `error`, then the behavior is as before: replacements +/// If *policy* is set to *error*, then the behavior is as before: replacements /// will fail if the revision id found in the database does not match the target /// revision id specified in the request. /// -/// If `policy` is set to `last`, then the replacement will succeed, even if the +/// If *policy* is set to *last*, then the replacement will succeed, even if the /// revision id found in the database does not match the target revision id specified -/// in the request. You can use the `last` `policy` to force replacements. +/// in the request. You can use the *last* *policy* to force replacements. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{201} -/// is returned if the document was replaced successfully and `waitForSync` was -/// `true`. +/// is returned if the document was replaced successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} -/// is returned if the document was replaced successfully and `waitForSync` was -/// `false`. +/// is returned if the document was replaced successfully and *waitForSync* was +/// *false*. /// /// @RESTRETURNCODE{400} /// is returned if the body does not contain a valid JSON representation of a @@ -1016,10 +1025,10 @@ bool RestDocumentHandler::checkDocument () { /// is returned if the collection or the document was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. /// /// @EXAMPLES /// @@ -1112,6 +1121,7 @@ bool RestDocumentHandler::checkDocument () { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestDocumentHandler::replaceDocument () { @@ -1119,9 +1129,10 @@ bool RestDocumentHandler::replaceDocument () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock REST_DOCUMENT_UPDATE /// @brief updates a document /// -/// @RESTHEADER{PATCH /_api/document/`document-handle`,patches a document} +/// @RESTHEADER{PATCH /_api/document/document-handle, Patch document} /// /// @RESTBODYPARAM{document,json,required} /// A JSON representation of the document update. @@ -1135,72 +1146,72 @@ bool RestDocumentHandler::replaceDocument () { /// /// @RESTQUERYPARAM{keepNull,boolean,optional} /// If the intention is to delete existing attributes with the patch command, -/// the URL query parameter `keepNull` can be used with a value of `false`. +/// the URL query parameter *keepNull* can be used with a value of *false*. /// This will modify the behavior of the patch command to remove any attributes /// from the existing document that are contained in the patch document with an -/// attribute value of `null`. +/// attribute value of *null*. /// /// @RESTQUERYPARAM{waitForSync,boolean,optional} /// Wait until document has been synced to disk. /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally patch a document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTQUERYPARAM{policy,string,optional} /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter. +/// can use the *policy* parameter. /// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally patch a document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION -/// Partially updates the document identified by `document-handle`. +/// Partially updates the document identified by *document-handle*. /// The body of the request must contain a JSON document with the attributes /// to patch (the patch document). All attributes from the patch document will /// be added to the existing document if they do not yet exist, and overwritten /// in the existing document if they do exist there. /// -/// Setting an attribute value to `null` in the patch document will cause a -/// value of `null` be saved for the attribute by default. +/// Setting an attribute value to *null* in the patch document will cause a +/// value of *null* be saved for the attribute by default. /// -/// Optionally, the URL parameter `waitForSync` can be used to force +/// Optionally, the URL parameter *waitForSync* can be used to force /// synchronisation of the document update operation to disk even in case -/// that the `waitForSync` flag had been disabled for the entire collection. -/// Thus, the `waitForSync` URL parameter can be used to force synchronisation -/// 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` URL parameter cannot be used to disable -/// synchronisation for collections that have a default `waitForSync` value -/// of `true`. +/// that the *waitForSync* flag had been disabled for the entire collection. +/// Thus, the *waitForSync* URL parameter can be used to force synchronisation +/// 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* URL parameter cannot be used to disable +/// synchronisation for collections that have a default *waitForSync* value +/// of *true*. /// /// The body of the response contains a JSON object with the information about -/// the handle and the revision. The attribute `_id` contains the known -/// `document-handle` of the updated document, the attribute `_rev` +/// the handle and the revision. The attribute *_id* contains the known +/// *document-handle* of the updated document, the attribute *_rev* /// contains the new document revision. /// -/// If the document does not exist, then a `HTTP 404` is returned and the +/// If the document does not exist, then a *HTTP 404* is returned and the /// body of the response contains an error document. /// /// You can conditionally update a document based on a target revision id by -/// using either the `rev` URL parameter or the `if-match` HTTP header. +/// using either the *rev* URL parameter or the *if-match* HTTP header. /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter. This is the same as when replacing +/// can use the *policy* parameter. This is the same as when replacing /// documents (see replacing documents for details). /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{201} -/// is returned if the document was created successfully and `waitForSync` was -/// `true`. +/// is returned if the document was created successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} -/// is returned if the document was created successfully and `waitForSync` was -/// `false`. +/// is returned if the document was created successfully and *waitForSync* was +/// *false*. /// /// @RESTRETURNCODE{400} /// is returned if the body does not contain a valid JSON representation of a @@ -1210,10 +1221,10 @@ bool RestDocumentHandler::replaceDocument () { /// is returned if the collection or the document was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. /// /// @EXAMPLES /// @@ -1245,6 +1256,7 @@ bool RestDocumentHandler::replaceDocument () { /// assert(response5.code === 200); /// logJsonResponse(response5); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestDocumentHandler::updateDocument () { @@ -1526,24 +1538,25 @@ bool RestDocumentHandler::modifyDocumentCoordinator ( } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock REST_DOCUMENT_DELETE /// @brief deletes a document /// -/// @RESTHEADER{DELETE /_api/document/`document-handle`,deletes a document} +/// @RESTHEADER{DELETE /_api/document/document-handle, Deletes document} /// /// @RESTURLPARAMETERS /// /// @RESTURLPARAM{document-handle,string,required} -/// Deletes the document identified by `document-handle`. +/// Deletes the document identified by *document-handle*. /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally delete a document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTQUERYPARAM{policy,string,optional} /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter. This is the same as when replacing +/// can use the *policy* parameter. This is the same as when replacing /// documents (see replacing documents for more details). /// /// @RESTQUERYPARAM{waitForSync,boolean,optional} @@ -1553,39 +1566,39 @@ bool RestDocumentHandler::modifyDocumentCoordinator ( /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally delete a document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION /// The body of the response contains a JSON object with the information about -/// the handle and the revision. The attribute `_id` contains the known -/// `document-handle` of the deleted document, the attribute `_rev` +/// the handle and the revision. The attribute *_id* contains the known +/// *document-handle* of the deleted document, the attribute *_rev* /// contains the document revision. /// -/// If the `waitForSync` parameter is not specified or set to -/// `false`, then the collection's default `waitForSync` behavior is -/// applied. The `waitForSync` URL parameter cannot be used to disable -/// synchronisation for collections that have a default `waitForSync` value -/// of `true`. +/// If the *waitForSync* parameter is not specified or set to +/// *false*, then the collection's default *waitForSync* behavior is +/// applied. The *waitForSync* URL parameter cannot be used to disable +/// synchronisation for collections that have a default *waitForSync* value +/// of *true*. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// is returned if the document was deleted successfully and `waitForSync` was -/// `true`. +/// is returned if the document was deleted successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} -/// is returned if the document was deleted successfully and `waitForSync` was -/// `false`. +/// is returned if the document was deleted successfully and *waitForSync* was +/// *false*. /// /// @RESTRETURNCODE{404} /// is returned if the collection or the document was not found. /// The response body contains an error document in this case. /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. /// /// @EXAMPLES /// @@ -1642,6 +1655,7 @@ bool RestDocumentHandler::modifyDocumentCoordinator ( /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestDocumentHandler::deleteDocument () { diff --git a/arangod/RestHandler/RestEdgeHandler.cpp b/arangod/RestHandler/RestEdgeHandler.cpp index bedc2982e3..e2643d77a4 100644 --- a/arangod/RestHandler/RestEdgeHandler.cpp +++ b/arangod/RestHandler/RestEdgeHandler.cpp @@ -70,52 +70,52 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request) // ----------------------------------------------------------------------------- //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_CREATE /// @brief creates an edge /// -/// @RESTHEADER{POST /_api/edge,creates an edge} +/// @RESTHEADER{POST /_api/edge,Create edge} /// /// @RESTBODYPARAM{edge-document,json,required} /// A JSON representation of the edge document must be passed as the body of /// the POST request. This JSON object may contain the edge's document key in -/// the `_key` attribute if needed. +/// the *_key* attribute if needed. /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{collection,string,required} -/// Creates a new edge in the collection identified by `collection` name. +/// Creates a new edge in the collection identified by *collection* name. /// /// @RESTQUERYPARAM{createCollection,boolean,optional} -/// If this parameter has a value of `true` or `yes`, then the collection is +/// If this parameter has a value of *true* or *yes*, then the collection is /// created if it does not yet exist. Other values will be ignored so the /// collection must be present for the operation to succeed. /// -/// Note: this flag is not supported in a cluster. Using it will result in an +/// **Note**: This flag is not supported in a cluster. Using it will result in an /// error. /// /// @RESTQUERYPARAM{waitForSync,boolean,optional} /// Wait until the edge document has been synced to disk. /// /// @RESTQUERYPARAM{from,string,required} -/// The document handle of the start point must be passed in `from` handle. +/// The document handle of the start point must be passed in *from* handle. /// /// @RESTQUERYPARAM{to,string,required} -/// The document handle of the end point must be passed in `to` handle. +/// The document handle of the end point must be passed in *to* handle. /// /// @RESTDESCRIPTION -/// Creates a new edge document in the collection named `collection`. A JSON +/// Creates a new edge document in the collection named *collection*. A JSON /// representation of the document must be passed as the body of the POST /// request. /// -/// The `from` and `to` handles are immutable once the edge has been created. +/// The *from* and *to* handles are immutable once the edge has been created. /// -/// In all other respects the method works like `POST /document`, see -/// @ref RestDocument for details. +/// In all other respects the method works like *POST /document*. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{201} -/// is returned if the edge was created successfully and `waitForSync` was -/// `true`. +/// is returned if the edge was created successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} /// is returned if the edge was created successfully. @@ -126,7 +126,7 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request) /// The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// /// @EXAMPLES @@ -156,6 +156,7 @@ RestEdgeHandler::RestEdgeHandler (HttpRequest* request) /// db._drop("vertices"); /// db._graphs.remove("graph"); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// bool RestEdgeHandler::createDocument () { @@ -256,7 +257,7 @@ bool RestEdgeHandler::createDocument () { string wrongPart; // Note that in a DBserver in a cluster, the following call will - // actually parse the first part of `from` as a cluster-wide + // actually parse the first part of *from* as a cluster-wide // collection name, exactly as it is needed here! res = parseDocumentId(trx.resolver(), from, edge._fromCid, edge._fromKey); @@ -265,7 +266,7 @@ bool RestEdgeHandler::createDocument () { } else { // Note that in a DBserver in a cluster, the following call will - // actually parse the first part of `from` as a cluster-wide + // actually parse the first part of *from* as a cluster-wide // collection name, exactly as it is needed here! res = parseDocumentId(trx.resolver(), to, edge._toCid, edge._toKey); @@ -349,9 +350,10 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_READ /// @brief reads a single edge /// -/// @RESTHEADER{GET /_api/edge/`document-handle`,reads an edge} +/// @RESTHEADER{GET /_api/edge/document-handle, Read edge} /// /// @RESTURLPARAMETERS /// @@ -363,23 +365,23 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// @RESTHEADERPARAM{If-None-Match,string,optional} /// If the "If-None-Match" header is given, then it must contain exactly one /// etag. The edge is returned if it has a different revision than the -/// given etag. Otherwise an `HTTP 304` is returned. +/// given etag. Otherwise an *HTTP 304* is returned. /// /// @RESTHEADERPARAM{If-Match,string,optional} /// If the "If-Match" header is given, then it must contain exactly one /// etag. The edge is returned if it has the same revision ad the -/// given etag. Otherwise a `HTTP 412` is returned. As an alternative -/// you can supply the etag in an attribute `rev` in the URL. +/// given etag. Otherwise a *HTTP 412* is returned. As an alternative +/// you can supply the etag in an attribute *rev* in the URL. /// /// @RESTDESCRIPTION -/// Returns the edge identified by `document-handle`. The returned +/// Returns the edge identified by *document-handle*. The returned /// edge contains a few special attributes: /// -/// - `_id` contains the document handle +/// - *_id* contains the document handle /// -/// - `_rev` contains the revision +/// - *_rev* contains the revision /// -/// - `_from` and `to` contain the document handles of the connected +/// - *_from* and *to* contain the document handles of the connected /// vertex documents /// /// @RESTRETURNCODES @@ -395,16 +397,18 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// is returned if the edge or collection was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_READ_ALL /// @brief reads all edges from collection /// -/// @RESTHEADER{GET /_api/edge,reads all edges from collection} +/// @RESTHEADER{GET /_api/edge, Read all edges from collection} /// /// @RESTQUERYPARAMETERS /// @@ -413,7 +417,7 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// /// @RESTDESCRIPTION /// Returns a list of all URI for all edges from the collection identified -/// by `collection`. +/// by *collection*. /// /// @RESTRETURNCODES /// @@ -422,12 +426,14 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// /// @RESTRETURNCODE{404} /// The collection does not exist. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_READ_HEAD /// @brief reads a single edge head /// -/// @RESTHEADER{HEAD /_api/edge/`document-handle`,reads an edge header} +/// @RESTHEADER{HEAD /_api/edge/document-handle, Read edge header} /// /// @RESTURLPARAMETERS /// @@ -438,16 +444,16 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally fetch an edge document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally fetch an edge document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION -/// Like `GET`, but only returns the header fields and not the body. You +/// Like *GET*, but only returns the header fields and not the body. You /// can use this call to get the current revision of an edge document or check if /// it was deleted. /// @@ -464,15 +470,17 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// is returned if the edge document or collection was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `etag` header. +/// document's current revision in the *etag* header. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_REPLACE /// @brief replaces an edge /// -/// @RESTHEADER{PUT /_api/edge/`document-handle`,replaces an edge} +/// @RESTHEADER{PUT /_api/edge/document-handle,replaces an edge} /// /// @RESTBODYPARAM{edge,json,required} /// A JSON representation of the new edge data. @@ -489,95 +497,96 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally replace an edge document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTQUERYPARAM{policy,string,optional} /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter (see below). +/// can use the *policy* parameter (see below). /// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally replace an edge document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION -/// Completely updates (i.e. replaces) the edge document identified by `document-handle`. -/// If the edge document exists and can be updated, then a `HTTP 201` is returned +/// Completely updates (i.e. replaces) the edge document identified by *document-handle*. +/// If the edge document exists and can be updated, then a *HTTP 201* is returned /// and the "ETag" header field contains the new revision of the edge document. /// /// If the new edge document passed in the body of the request contains the -/// `document-handle` in the attribute `_id` and the revision in `_rev`, +/// *document-handle* in the attribute *_id* and the revision in *_rev*, /// these attributes will be ignored. Only the URI and the "ETag" header are -/// relevant in order to avoid confusion when using proxies. Note that the attributes -/// `_from` and `_to` of an edge are immutable and cannot be updated either. +/// relevant in order to avoid confusion when using proxies. +/// **Note**: The attributes +/// *_from* and *_to* of an edge are immutable and cannot be updated either. /// -/// Optionally, the URL parameter `waitForSync` can be used to force +/// Optionally, the URL parameter *waitForSync* can be used to force /// synchronisation of the edge document replacement operation to disk even in case -/// that the `waitForSync` flag had been disabled for the entire collection. -/// Thus, the `waitForSync` URL parameter can be used to force synchronisation -/// 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` URL parameter cannot be used to disable -/// synchronisation for collections that have a default `waitForSync` value -/// of `true`. +/// that the *waitForSync* flag had been disabled for the entire collection. +/// Thus, the *waitForSync* URL parameter can be used to force synchronisation +/// 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* URL parameter cannot be used to disable +/// synchronisation for collections that have a default *waitForSync* value +/// of *true*. /// /// The body of the response contains a JSON object with the information about -/// the handle and the revision. The attribute `_id` contains the known -/// `document-handle` of the updated edge document, the attribute `_rev` +/// the handle and the revision. The attribute *_id* contains the known +/// *document-handle* of the updated edge document, the attribute *_rev* /// contains the new revision of the edge document. /// -/// If the edge document does not exist, then a `HTTP 404` is returned and the +/// If the edge document does not exist, then a *HTTP 404* is returned and the /// body of the response contains an error document. /// /// There are two ways for specifying the targeted revision id for /// conditional replacements (i.e. replacements that will only be executed if /// the revision id found in the database matches the revision id specified /// in the request): -/// - specifying the target revision in the `rev` URL query parameter -/// - specifying the target revision in the `if-match` HTTP header +/// - specifying the target revision in the *rev* URL query parameter +/// - specifying the target revision in the *if-match* HTTP header /// /// Specifying a target revision is optional, however, if done, only one of the -/// described mechanisms must be used (either the `rev` URL parameter or the -/// `if-match` HTTP header). +/// described mechanisms must be used (either the *rev* URL parameter or the +/// *if-match* HTTP header). /// Regardless which mechanism is used, the parameter needs to contain the target -/// revision id as returned in the `_rev` attribute of an edge document or -/// by an HTTP `etag` header. +/// revision id as returned in the *_rev* attribute of an edge document or +/// by an HTTP *etag* header. /// /// For example, to conditionally replace an edge document based on a specific revision /// id, you can use the following request: /// -/// - PUT /_api/document/`document-handle`?rev=`etag` +/// - PUT /_api/document/*document-handle*?rev=*etag* /// -/// If a target revision id is provided in the request (e.g. via the `etag` value -/// in the `rev` URL query parameter above), ArangoDB will check that +/// If a target revision id is provided in the request (e.g. via the *etag* value +/// in the *rev* URL query parameter above), ArangoDB will check that /// the revision id of the edge document found in the database is equal to the target /// revision id provided in the request. If there is a mismatch between the revision -/// id, then by default a `HTTP 412` conflict is returned and no replacement is +/// id, then by default a *HTTP 412* conflict is returned and no replacement is /// performed. /// -/// The conditional update behavior can be overriden with the `policy` URL query parameter: +/// The conditional update behavior can be overriden with the *policy* URL query parameter: /// -/// - PUT /_api/document/`document-handle`?policy=`policy` +/// - PUT /_api/document/*document-handle*?policy=*policy* /// -/// If `policy` is set to `error`, then the behavior is as before: replacements +/// If *policy* is set to *error*, then the behavior is as before: replacements /// will fail if the revision id found in the database does not match the target /// revision id specified in the request. /// -/// If `policy` is set to `last`, then the replacement will succeed, even if the +/// If *policy* is set to *last*, then the replacement will succeed, even if the /// revision id found in the database does not match the target revision id specified -/// in the request. You can use the `last` `policy` to force replacements. +/// in the request. You can use the *last* *policy* to force replacements. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{201} -/// is returned if the edge document was replaced successfully and `waitForSync` was -/// `true`. +/// is returned if the edge document was replaced successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} -/// is returned if the edge document was replaced successfully and `waitForSync` was -/// `false`. +/// is returned if the edge document was replaced successfully and *waitForSync* was +/// *false*. /// /// @RESTRETURNCODE{400} /// is returned if the body does not contain a valid JSON representation of an edge @@ -588,16 +597,18 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// is returned if the collection or the edge document was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_UPDATES /// @brief updates an edge /// -/// @RESTHEADER{PATCH /_api/edge/`document-handle`,patches an edge} +/// @RESTHEADER{PATCH /_api/edge/document-handle, Patches edge} /// /// @RESTBODYPARAM{document,json,required} /// A JSON representation of the edge update. @@ -611,75 +622,75 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// /// @RESTQUERYPARAM{keepNull,boolean,optional} /// If the intention is to delete existing attributes with the patch command, -/// the URL query parameter `keepNull` can be used with a value of `false`. +/// the URL query parameter *keepNull* can be used with a value of *false*. /// This will modify the behavior of the patch command to remove any attributes /// from the existing edge document that are contained in the patch document with an -/// attribute value of `null`. +/// attribute value of *null*. /// /// @RESTQUERYPARAM{waitForSync,boolean,optional} /// Wait until edge document has been synced to disk. /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally patch an edge document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTQUERYPARAM{policy,string,optional} /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter. +/// can use the *policy* parameter. /// /// @RESTHEADERPARAMETERS /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally patch an edge document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION -/// Partially updates the edge document identified by `document-handle`. +/// Partially updates the edge document identified by *document-handle*. /// The body of the request must contain a JSON document with the attributes /// to patch (the patch document). All attributes from the patch document will /// be added to the existing edge document if they do not yet exist, and overwritten /// in the existing edge document if they do exist there. /// -/// Setting an attribute value to `null` in the patch document will cause a -/// value of `null` be saved for the attribute by default. +/// Setting an attribute value to *null* in the patch document will cause a +/// value of *null* be saved for the attribute by default. /// -/// Note that internal attributes such as `_key`, `_from` and `_to` are immutable +/// **Note**: Internal attributes such as *_key*, *_from* and *_to* are immutable /// once set and cannot be updated. /// -/// Optionally, the URL parameter `waitForSync` can be used to force +/// Optionally, the URL parameter *waitForSync* can be used to force /// synchronisation of the edge document update operation to disk even in case -/// that the `waitForSync` flag had been disabled for the entire collection. -/// Thus, the `waitForSync` URL parameter can be used to force synchronisation -/// 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` URL parameter cannot be used to disable -/// synchronisation for collections that have a default `waitForSync` value -/// of `true`. +/// that the *waitForSync* flag had been disabled for the entire collection. +/// Thus, the *waitForSync* URL parameter can be used to force synchronisation +/// 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* URL parameter cannot be used to disable +/// synchronisation for collections that have a default *waitForSync* value +/// of *true*. /// /// The body of the response contains a JSON object with the information about -/// the handle and the revision. The attribute `_id` contains the known -/// `document-handle` of the updated edge document, the attribute `_rev` +/// the handle and the revision. The attribute *_id* contains the known +/// *document-handle* of the updated edge document, the attribute *_rev* /// contains the new edge document revision. /// -/// If the edge document does not exist, then a `HTTP 404` is returned and the +/// If the edge document does not exist, then a *HTTP 404* is returned and the /// body of the response contains an error document. /// /// You can conditionally update an edge document based on a target revision id by -/// using either the `rev` URL parameter or the `if-match` HTTP header. +/// using either the *rev* URL parameter or the *if-match* HTTP header. /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter. This is the same as when replacing +/// can use the *policy* parameter. This is the same as when replacing /// edge documents (see replacing documents for details). /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{201} -/// is returned if the document was patched successfully and `waitForSync` was -/// `true`. +/// is returned if the document was patched successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} -/// is returned if the document was patched successfully and `waitForSync` was -/// `false`. +/// is returned if the document was patched successfully and *waitForSync* was +/// *false*. /// /// @RESTRETURNCODE{400} /// is returned if the body does not contain a valid JSON representation or when @@ -690,31 +701,33 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// is returned if the collection or the edge document was not found /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_DELETE /// @brief deletes an edge /// -/// @RESTHEADER{DELETE /_api/edge/`document-handle`,deletes an edge} +/// @RESTHEADER{DELETE /_api/edge/document-handle, Deletes edge} /// /// @RESTURLPARAMETERS /// /// @RESTURLPARAM{document-handle,string,required} -/// Deletes the edge document identified by `document-handle`. +/// Deletes the edge document identified by *document-handle*. /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{rev,string,optional} /// You can conditionally delete an edge document based on a target revision id by -/// using the `rev` URL parameter. +/// using the *rev* URL parameter. /// /// @RESTQUERYPARAM{policy,string,optional} /// To control the update behavior in case there is a revision mismatch, you -/// can use the `policy` parameter. This is the same as when replacing edge +/// can use the *policy* parameter. This is the same as when replacing edge /// documents (see replacing edge documents for more details). /// /// @RESTQUERYPARAM{waitForSync,boolean,optional} @@ -724,39 +737,40 @@ bool RestEdgeHandler::createDocumentCoordinator (string const& collname, /// /// @RESTHEADERPARAM{If-Match,string,optional} /// You can conditionally delete an edge document based on a target revision id by -/// using the `if-match` HTTP header. +/// using the *if-match* HTTP header. /// /// @RESTDESCRIPTION /// The body of the response contains a JSON object with the information about -/// the handle and the revision. The attribute `_id` contains the known -/// `document-handle` of the deleted edge document, the attribute `_rev` +/// the handle and the revision. The attribute *_id* contains the known +/// *document-handle* of the deleted edge document, the attribute *_rev* /// contains the edge document revision. /// -/// If the `waitForSync` parameter is not specified or set to -/// `false`, then the collection's default `waitForSync` behavior is -/// applied. The `waitForSync` URL parameter cannot be used to disable -/// synchronisation for collections that have a default `waitForSync` value -/// of `true`. +/// If the *waitForSync* parameter is not specified or set to +/// *false*, then the collection's default *waitForSync* behavior is +/// applied. The *waitForSync* URL parameter cannot be used to disable +/// synchronisation for collections that have a default *waitForSync* value +/// of *true*. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// is returned if the edge document was deleted successfully and `waitForSync` was -/// `true`. +/// is returned if the edge document was deleted successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{202} -/// is returned if the edge document was deleted successfully and `waitForSync` was -/// `false`. +/// is returned if the edge document was deleted successfully and *waitForSync* was +/// *false*. /// /// @RESTRETURNCODE{404} /// is returned if the collection or the edge document was not found. /// The response body contains an error document in this case. /// /// @RESTRETURNCODE{412} -/// is returned if a "If-Match" header or `rev` is given and the found +/// is returned if a "If-Match" header or *rev* is given and the found /// document has a different version. The response will also contain the found -/// document's current revision in the `_rev` attribute. Additionally, the -/// attributes `_id` and `_key` will be returned. +/// document's current revision in the *_rev* attribute. Additionally, the +/// attributes *_id* and *_key* will be returned. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// // ----------------------------------------------------------------------------- diff --git a/arangod/RestHandler/RestReplicationHandler.cpp b/arangod/RestHandler/RestReplicationHandler.cpp index 50541ec690..f5c14ad81f 100644 --- a/arangod/RestHandler/RestReplicationHandler.cpp +++ b/arangod/RestHandler/RestReplicationHandler.cpp @@ -426,9 +426,10 @@ uint64_t RestReplicationHandler::determineChunkSize () const { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_logger_start /// @brief starts the replication logger /// -/// @RESTHEADER{PUT /_api/replication/logger-start,starts the replication logger} +/// @RESTHEADER{PUT /_api/replication/logger-start, Start replication logger} /// /// @RESTDESCRIPTION /// Starts the server's replication logger. Will do nothing if the replication @@ -437,9 +438,9 @@ uint64_t RestReplicationHandler::determineChunkSize () const { /// The body of the response contains a JSON object with the following /// attributes: /// -/// - `running`: will contain `true` +/// - *running*: will contain *true* /// -/// Note: this method is not supported on a coordinator in a cluster. +/// **Note**: this method is not supported on a coordinator in a cluster. /// /// @RESTRETURNCODES /// @@ -468,6 +469,7 @@ uint64_t RestReplicationHandler::determineChunkSize () const { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandLoggerStart () { @@ -483,9 +485,10 @@ void RestReplicationHandler::handleCommandLoggerStart () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_logger_stop /// @brief stops the replication logger /// -/// @RESTHEADER{PUT /_api/replication/logger-stop,stops the replication logger} +/// @RESTHEADER{PUT /_api/replication/logger-stop, Stop replication logger} /// /// @RESTDESCRIPTION /// Stops the server's replication logger. Will do nothing if the replication @@ -494,9 +497,9 @@ void RestReplicationHandler::handleCommandLoggerStart () { /// The body of the response contains a JSON object with the following /// attributes: /// -/// - `running`: will contain `false` +/// - *running*: will contain *false* /// -/// Note: this method is not supported on a coordinator in a cluster. +/// **Note**: this method is not supported on a coordinator in a cluster. /// /// @RESTRETURNCODES /// @@ -526,6 +529,7 @@ void RestReplicationHandler::handleCommandLoggerStart () { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandLoggerStop () { @@ -541,9 +545,10 @@ void RestReplicationHandler::handleCommandLoggerStop () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_replication_logger_return_state /// @brief returns the state of the replication logger /// -/// @RESTHEADER{GET /_api/replication/logger-state,returns the replication logger state} +/// @RESTHEADER{GET /_api/replication/logger-state, Return replication logger state} /// /// @RESTDESCRIPTION /// Returns the current state of the server's replication logger. The state will @@ -557,31 +562,31 @@ void RestReplicationHandler::handleCommandLoggerStop () { /// The body of the response contains a JSON object with the following /// attributes: /// -/// - `state`: the current logger state as a JSON hash array with the following +/// - *state*: the current logger state as a JSON hash array with the following /// sub-attributes: /// -/// - `running`: whether or not the logger is running +/// - *running*: whether or not the logger is running /// -/// - `lastLogTick`: the tick value of the latest tick the logger has logged. +/// - *lastLogTick*: the tick value of the latest tick the logger has logged. /// This value can be used for incremental fetching of log data. /// -/// - `totalEvents`: total number of events logged since the server was started. +/// - *totalEvents*: total number of events logged since the server was started. /// The value is not reset between multiple stops and re-starts of the logger. /// -/// - `time`: the current date and time on the logger server +/// - *time*: the current date and time on the logger server /// -/// - `server`: a JSON hash with the following sub-attributes: +/// - *server*: a JSON hash with the following sub-attributes: /// -/// - `version`: the logger server's version +/// - *version*: the logger server's version /// -/// - `serverId`: the logger server's id +/// - *serverId*: the logger server's id /// -/// - `clients`: a list of all replication clients that ever connected to +/// - *clients*: a list of all replication clients that ever connected to /// the logger since it was started. This list can be used to determine /// approximately how much data the individual clients have already fetched -/// from the logger server. Each entry in the list contains a `time` value +/// from the logger server. Each entry in the list contains a *time* value /// indicating the server time the client last fetched data from the -/// replication logger. The `lastServedTick` value of each client indicates +/// replication logger. The *lastServedTick* value of each client indicates /// the latest tick value sent to the client upon a client request to the /// replication logger. /// @@ -628,6 +633,7 @@ void RestReplicationHandler::handleCommandLoggerStop () { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandLoggerState () { @@ -680,9 +686,10 @@ void RestReplicationHandler::handleCommandLoggerState () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_replication_logger_configuration /// @brief get the configuration of the replication logger /// -/// @RESTHEADER{GET /_api/replication/logger-config,returns the configuration of the replication logger} +/// @RESTHEADER{GET /_api/replication/logger-config,Configuration of the replication logger} /// /// @RESTDESCRIPTION /// Returns the configuration of the replication logger. @@ -690,18 +697,18 @@ void RestReplicationHandler::handleCommandLoggerState () { /// The body of the response is a JSON hash with the configuration. The /// following attributes may be present in the configuration: /// -/// - `autoStart`: whether or not to automatically start the replication logger +/// - *autoStart*: whether or not to automatically start the replication logger /// on server startup /// -/// - `logRemoteChanges`: whether or not externally created changes should be +/// - *logRemoteChanges*: whether or not externally created changes should be /// logged by the local logger /// -/// - `maxEvents`: the maximum number of log events kept by the replication -/// logger before deleting oldest events. A value of `0` means that the +/// - *maxEvents*: the maximum number of log events kept by the replication +/// logger before deleting oldest events. A value of *0* means that the /// number of events is not restricted. /// -/// - `maxEventsSize`: the maximum cumulated size of log event data kept by the -/// replication logger before deleting oldest events. A value of `0` means +/// - *maxEventsSize*: the maximum cumulated size of log event data kept by the +/// replication logger before deleting oldest events. A value of *0* means /// that the cumulated size of events is not restricted. /// /// @RESTRETURNCODES @@ -724,6 +731,7 @@ void RestReplicationHandler::handleCommandLoggerState () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandLoggerGetConfig () { @@ -744,34 +752,35 @@ void RestReplicationHandler::handleCommandLoggerGetConfig () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_logger_configuration /// @brief set the configuration of the replication logger /// -/// @RESTHEADER{PUT /_api/replication/logger-config,adjusts the configuration of the replication logger} +/// @RESTHEADER{PUT /_api/replication/logger-config, Configuration of the replication logger} /// /// @RESTBODYPARAM{configuration,json,required} /// A JSON representation of the configuration. /// /// @RESTDESCRIPTION -/// Sets the configuration of the replication logger. +/// Synchronizationn logger. /// /// The body of the request must be JSON hash with the configuration. The /// following attributes are allowed for the configuration: /// -/// - `autoStart`: whether or not to automatically start the replication logger +/// - *autoStart*: whether or not to automatically start the replication logger /// on server startup /// -/// - `logRemoteChanges`: whether or not externally created changes should be +/// - *logRemoteChanges*: whether or not externally created changes should be /// logged by the local logger /// -/// - `maxEvents`: the maximum number of log events kept by the replication -/// logger before deleting oldest events. Use a value of `0` to not restrict +/// - *maxEvents*: the maximum number of log events kept by the replication +/// logger before deleting oldest events. Use a value of *0* to not restrict /// the number of events. /// -/// - `maxEventsSize`: the maximum cumulated size of log event data kept by the -/// replication logger before deleting oldest events. Use a value of `0` to +/// - *maxEventsSize*: the maximum cumulated size of log event data kept by the +/// replication logger before deleting oldest events. Use a value of *0* to /// not restrict the size. /// -/// Note that when setting both `maxEvents` and `maxEventsSize`, reaching +/// **Note**: When setting both *maxEvents* and *maxEventsSize*, reaching /// either limitation will trigger a deletion of the "oldest" log events from /// the replication log. /// @@ -826,6 +835,7 @@ void RestReplicationHandler::handleCommandLoggerGetConfig () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandLoggerSetConfig () { @@ -833,9 +843,10 @@ void RestReplicationHandler::handleCommandLoggerSetConfig () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_replication_batch /// @brief handle a dump batch command /// -/// @RESTHEADER{POST /_api/replication/batch,creates a new dump batch} +/// @RESTHEADER{POST /_api/replication/batch, Create new dump batch} /// /// @RESTBODYPARAM{body,json,required} /// A JSON object with the batch configuration. @@ -845,14 +856,14 @@ void RestReplicationHandler::handleCommandLoggerSetConfig () { /// /// The body of the request must be a JSON hash with the following attributes: /// -/// - `ttl`: the time-to-live for the new batch (in seconds) +/// - *ttl*: the time-to-live for the new batch (in seconds) /// /// The response is a JSON hash with the following attributes: /// -/// - `id`: the id of the batch +/// - *id*: the id of the batch /// -/// Note: on a coordinator, this request must have the URL parameter -/// `DBserver` which must be an ID of a DBserver. +/// **Note**: on a coordinator, this request must have the URL parameter +/// *DBserver* which must be an ID of a DBserver. /// The very same request is forwarded synchronously to that DBserver. /// It is an error if this attribute is not bound in the coordinator case. /// @@ -862,17 +873,19 @@ void RestReplicationHandler::handleCommandLoggerSetConfig () { /// is returned if the batch was created successfully. /// /// @RESTRETURNCODE{400} -/// is returned if the ttl value is invalid or if `DBserver` attribute +/// is returned if the ttl value is invalid or if *DBserver* attribute /// is not specified or illegal on a coordinator. /// /// @RESTRETURNCODE{405} /// is returned when an invalid HTTP method is used. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_prolong /// @brief handle a dump batch command /// -/// @RESTHEADER{PUT /_api/replication/batch/`id`,prolongs an existing dump batch} +/// @RESTHEADER{PUT /_api/replication/batch/id, Prolong existing dump batch} /// /// @RESTBODYPARAM{body,json,required} /// A JSON object with the batch configration. @@ -888,12 +901,12 @@ void RestReplicationHandler::handleCommandLoggerSetConfig () { /// /// The body of the request must be a JSON hash with the following attributes: /// -/// - `ttl`: the time-to-live for the batch (in seconds) +/// - *ttl*: the time-to-live for the batch (in seconds) /// /// If the batch's ttl can be extended successully, the response is empty. /// -/// Note: on a coordinator, this request must have the URL parameter -/// `DBserver` which must be an ID of a DBserver. +/// **Note**: on a coordinator, this request must have the URL parameter +/// *DBserver* which must be an ID of a DBserver. /// The very same request is forwarded synchronously to that DBserver. /// It is an error if this attribute is not bound in the coordinator case. /// @@ -907,12 +920,14 @@ void RestReplicationHandler::handleCommandLoggerSetConfig () { /// /// @RESTRETURNCODE{405} /// is returned when an invalid HTTP method is used. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_api_replication_delete /// @brief handle a dump batch command /// -/// @RESTHEADER{DELETE /_api/replication/batch/`id`,deletes an existing dump batch} +/// @RESTHEADER{DELETE /_api/replication/batch/id, Deletes an existing dump batch} /// /// @RESTURLPARAMETERS /// @@ -922,8 +937,8 @@ void RestReplicationHandler::handleCommandLoggerSetConfig () { /// @RESTDESCRIPTION /// Deletes the existing dump batch, allowing compaction and cleanup to resume. /// -/// Note: on a coordinator, this request must have the URL parameter -/// `DBserver` which must be an ID of a DBserver. +/// **Note**: on a coordinator, this request must have the URL parameter +/// *DBserver* which must be an ID of a DBserver. /// The very same request is forwarded synchronously to that DBserver. /// It is an error if this attribute is not bound in the coordinator case. /// @@ -937,6 +952,7 @@ void RestReplicationHandler::handleCommandLoggerSetConfig () { /// /// @RESTRETURNCODE{405} /// is returned when an invalid HTTP method is used. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandBatch () { @@ -1110,9 +1126,10 @@ void RestReplicationHandler::handleTrampolineCoordinator () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_replication_logger_returns /// @brief returns ranged data from the replication log /// -/// @RESTHEADER{GET /_api/replication/logger-follow,returns recent log entries from the replication log} +/// @RESTHEADER{GET /_api/replication/logger-follow, Returns log entries} /// /// @RESTQUERYPARAMETERS /// @@ -1127,95 +1144,95 @@ void RestReplicationHandler::handleTrampolineCoordinator () { /// /// @RESTDESCRIPTION /// Returns data from the server's replication log. This method can be called -/// by replication clients after an initial synchronisation of data. The method +/// by replication clients after an initial synchronization of data. The method /// will return all "recent" log entries from the logger server, and the clients /// can replay and apply these entries locally so they get to the same data /// state as the logger server. /// /// Clients can call this method repeatedly to incrementally fetch all changes -/// from the logger server. In this case, they should provide the `from` value so +/// from the logger server. In this case, they should provide the *from* value so /// they will only get returned the log events since their last fetch. /// -/// When the `from` URL parameter is not used, the logger server will return log -/// entries starting at the beginning of its replication log. When the `from` +/// When the *from* URL parameter is not used, the logger server will return log +/// entries starting at the beginning of its replication log. When the *from* /// parameter is used, the logger server will only return log entries which have -/// higher tick values than the specified `from` value (note: the log entry with a -/// tick value equal to `from` will be excluded). Use the `from` value when +/// higher tick values than the specified *from* value (note: the log entry with a +/// tick value equal to *from* will be excluded). Use the *from* value when /// incrementally fetching log data. /// -/// The `to` URL parameter can be used to optionally restrict the upper bound of +/// The *to* URL parameter can be used to optionally restrict the upper bound of /// the result to a certain tick value. If used, the result will contain only log events -/// with tick values up to (including) `to`. In incremental fetching, there is no -/// need to use the `to` parameter. It only makes sense in special situations, +/// with tick values up to (including) *to*. In incremental fetching, there is no +/// need to use the *to* parameter. It only makes sense in special situations, /// when only parts of the change log are required. /// -/// The `chunkSize` URL parameter can be used to control the size of the result. -/// It must be specified in bytes. The `chunkSize` value will only be honored -/// approximately. Otherwise a too low `chunkSize` value could cause the server +/// The *chunkSize* URL parameter can be used to control the size of the result. +/// It must be specified in bytes. The *chunkSize* value will only be honored +/// approximately. Otherwise a too low *chunkSize* value could cause the server /// to not be able to put just one log entry into the result and return it. -/// Therefore, the `chunkSize` value will only be consulted after a log entry has +/// Therefore, the *chunkSize* value will only be consulted after a log entry has /// been written into the result. If the result size is then bigger than -/// `chunkSize`, the server will respond with as many log entries as there are -/// in the response already. If the result size is still smaller than `chunkSize`, +/// *chunkSize*, the server will respond with as many log entries as there are +/// in the response already. If the result size is still smaller than *chunkSize*, /// the server will try to return more data if there's more data left to return. /// -/// If `chunkSize` is not specified, some server-side default value will be used. +/// If *chunkSize* is not specified, some server-side default value will be used. /// -/// The `Content-Type` of the result is `application/x-arango-dump`. This is an +/// The *Content-Type* of the result is *application/x-arango-dump*. This is an /// easy-to-process format, with all log events going onto separate lines in the /// response body. Each log event itself is a JSON hash, with at least the /// following attributes: /// -/// - `tick`: the log event tick value +/// - *tick*: the log event tick value /// -/// - `type`: the log event type +/// - *type*: the log event type /// /// Individual log events will also have additional attributes, depending on the /// event type. A few common attributes which are used for multiple events types /// are: /// -/// - `cid`: id of the collection the event was for +/// - *cid*: id of the collection the event was for /// -/// - `tid`: id of the transaction the event was contained in +/// - *tid*: id of the transaction the event was contained in /// -/// - `key`: document key +/// - *key*: document key /// -/// - `rev`: document revision id +/// - *rev*: document revision id /// -/// - `data`: the original document data +/// - *data*: the original document data /// /// A more detailed description of the individual replication event types and their /// data structures can be found in @ref RefManualReplicationEventTypes. /// /// The response will also contain the following HTTP headers: /// -/// - `x-arango-replication-active`: whether or not the logger is active. Clients +/// - *x-arango-replication-active*: whether or not the logger is active. Clients /// can use this flag as an indication for their polling frequency. If the /// logger is not active and there are no more replication events available, it /// might be sensible for a client to abort, or to go to sleep for a long time /// and try again later to check whether the logger has been activated. /// -/// - `x-arango-replication-lastincluded`: the tick value of the last included +/// - *x-arango-replication-lastincluded*: the tick value of the last included /// value in the result. In incremental log fetching, this value can be used -/// as the `from` value for the following request. Note that if the result is -/// empty, the value will be `0`. This value should not be used as `from` value +/// as the *from* value for the following request. **Note** that if the result is +/// empty, the value will be *0*. This value should not be used as *from* value /// by clients in the next request (otherwise the server would return the log /// events from the start of the log again). /// -/// - `x-arango-replication-lasttick`: the last tick value the logger server has +/// - *x-arango-replication-lasttick*: the last tick value the logger server has /// logged (not necessarily included in the result). By comparing the the last /// tick and last included tick values, clients have an approximate indication of /// how many events there are still left to fetch. /// -/// - `x-arango-replication-checkmore`: whether or not there already exists more +/// - *x-arango-replication-checkmore*: whether or not there already exists more /// log data which the client could fetch immediately. If there is more log data -/// available, the client could call `logger-follow` again with an adjusted `from` +/// available, the client could call *logger-follow* again with an adjusted *from* /// value to fetch remaining log entries until there are no more. /// /// If there isn't any more log data to fetch, the client might decide to go /// to sleep for a while before calling the logger again. /// -/// Note: this method is not supported on a coordinator in a cluster. +/// **Note**: this method is not supported on a coordinator in a cluster. /// /// @RESTRETURNCODES /// @@ -1230,7 +1247,7 @@ void RestReplicationHandler::handleTrampolineCoordinator () { /// in this case. /// /// @RESTRETURNCODE{400} -/// is returned if either the `from` or `to` values are invalid. +/// is returned if either the *from* or *to* values are invalid. /// /// @RESTRETURNCODE{405} /// is returned when an invalid HTTP method is used. @@ -1304,6 +1321,7 @@ void RestReplicationHandler::handleTrampolineCoordinator () { /// /// logRawResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandLoggerFollow () { @@ -1398,78 +1416,79 @@ void RestReplicationHandler::handleCommandLoggerFollow () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_inventory /// @brief returns the server inventory /// -/// @RESTHEADER{GET /_api/replication/inventory,returns an inventory of collections and indexes} +/// @RESTHEADER{GET /_api/replication/inventory, Return inventory of collections and indexes} /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{includeSystem,boolean,optional} -/// Include system collections in the result. The default value is `false`. +/// Include system collections in the result. The default value is *false*. /// /// @RESTDESCRIPTION /// Returns the list of collections and indexes available on the server. This /// list can be used by replication clients to initiate an initial sync with the /// server. /// -/// The response will contain a JSON hash array with the `collection` and `state` +/// The response will contain a JSON hash array with the *collection* and *state* /// attributes. /// -/// `collections` is a list of collections with the following sub-attributes: +/// *collections* is a list of collections with the following sub-attributes: /// -/// - `parameters`: the collection properties +/// - *parameters*: the collection properties /// -/// - `indexes`: a list of the indexes of a the collection. Primary indexes and edges indexes +/// - *indexes*: a list of the indexes of a the collection. Primary indexes and edges indexes /// are not included in this list. /// -/// `tick`: the system-wide tick value at the start of the dump +/// *tick*: the system-wide tick value at the start of the dump /// -/// The `state` attribute contains the current state of the replication logger. It +/// The *state* attribute contains the current state of the replication logger. It /// contains the following sub-attributes: /// -/// - `running`: whether or not the replication logger is currently active +/// - *running*: whether or not the replication logger is currently active /// -/// - `lastLogTick`: the value of the last tick the replication logger has written +/// - *lastLogTick*: the value of the last tick the replication logger has written /// -/// - `time`: the current time on the server +/// - *time*: the current time on the server /// -/// Replication clients should note the `lastLogTick` value returned. They can then +/// Replication clients should note the *lastLogTick* value returned. They can then /// fetch collections' data using the dump method up to the value of lastLogTick, and /// query the continuous replication log for log events after this tick value. /// /// To create a full copy of the collections on the logger server, a replication client /// can execute these steps: /// -/// - call the `/inventory` API method. This returns the `lastLogTick` value and the +/// - call the */inventory* API method. This returns the *lastLogTick* value and the /// list of collections and indexes from the logger server. /// -/// - for each collection returned by `/inventory`, create the collection locally and -/// call `/dump` to stream the collection data to the client, up to the value of -/// `lastLogTick`. +/// - for each collection returned by */inventory*, create the collection locally and +/// call */dump* to stream the collection data to the client, up to the value of +/// *lastLogTick*. /// After that, the client can create the indexes on the collections as they were -/// reported by `/inventory`. +/// reported by */inventory*. /// /// If the clients wants to continuously stream replication log events from the logger /// server, the following additional steps need to be carried out: /// -/// - the client should call `/logger-follow` initially to fetch the first batch of -/// replication events that were logged after the client's call to `/inventory`. +/// - the client should call */logger-follow* initially to fetch the first batch of +/// replication events that were logged after the client's call to */inventory*. /// -/// The call to `/logger-follow` should use a `from` parameter with the value of the -/// `lastLogTick` as reported by `/inventory`. The call to `/logger-follow` will return the -/// `x-arango-replication-lastincluded` which will contain the last tick value included +/// The call to */logger-follow* should use a *from* parameter with the value of the +/// *lastLogTick* as reported by */inventory*. The call to */logger-follow* will return the +/// *x-arango-replication-lastincluded* which will contain the last tick value included /// in the response. /// -/// - the client can then continuously call `/logger-follow` to incrementally fetch new +/// - the client can then continuously call */logger-follow* to incrementally fetch new /// replication events that occurred after the last transfer. /// -/// Calls should use a `from` parameter with the value of the `x-arango-replication-lastincluded` +/// Calls should use a *from* parameter with the value of the *x-arango-replication-lastincluded* /// header of the previous response. If there are no more replication events, the /// response will be empty and clients can go to sleep for a while and try again /// later. /// -/// Note: on a coordinator, this request must have the URL parameter -/// `DBserver` which must be an ID of a DBserver. +/// **Note**: on a coordinator, this request must have the URL parameter +/// *DBserver* which must be an ID of a DBserver. /// The very same request is forwarded synchronously to that DBserver. /// It is an error if this attribute is not bound in the coordinator case. /// @@ -1520,6 +1539,7 @@ void RestReplicationHandler::handleCommandLoggerFollow () { /// db._drop("IndexedCollection1"); /// db._drop("IndexedCollection2"); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandInventory () { @@ -1586,14 +1606,15 @@ void RestReplicationHandler::handleCommandInventory () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_replication_cluster_inventory /// @brief returns the cluster inventory, only on coordinator /// -/// @RESTHEADER{GET /_api/replication/clusterInventory,returns an inventory of collections and indexes} +/// @RESTHEADER{GET /_api/replication/clusterInventory, Return cluster inventory of collections and indexes} /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{includeSystem,boolean,optional} -/// Include system collections in the result. The default value is `false`. +/// Include system collections in the result. The default value is *false*. /// /// @RESTDESCRIPTION /// Returns the list of collections and indexes available on the cluster. @@ -1601,7 +1622,7 @@ void RestReplicationHandler::handleCommandInventory () { /// The response will be a list of JSON hash array, one for each collection, /// which contains exactly two keys "parameters" and "indexes". This /// information comes from Plan/Collections//* in the agency, -/// just that the `indexes` attribute there is relocated to adjust it to +/// just that the *indexes* attribute there is relocated to adjust it to /// the data format of arangodump. /// /// @RESTRETURNCODES @@ -1614,6 +1635,7 @@ void RestReplicationHandler::handleCommandInventory () { /// /// @RESTRETURNCODE{500} /// is returned if an error occurred while assembling the response. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandClusterInventory () { @@ -2974,9 +2996,10 @@ void RestReplicationHandler::handleCommandRestoreDataCoordinator () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_replication_dump /// @brief dumps the data of a collection /// -/// @RESTHEADER{GET /_api/replication/dump,returns the data of a collection} +/// @RESTHEADER{GET /_api/replication/dump, Return data of a collection} /// /// @RESTQUERYPARAMETERS /// @@ -2993,39 +3016,39 @@ void RestReplicationHandler::handleCommandRestoreDataCoordinator () { /// Approximate maximum size of the returned result. /// /// @RESTQUERYPARAM{ticks,boolean,optional} -/// Whether or not to include tick values in the dump. Default value is `true`. +/// Whether or not to include tick values in the dump. Default value is *true*. /// /// @RESTDESCRIPTION /// Returns the data from the collection for the requested range. /// -/// When the `from` URL parameter is not used, collection events are returned from -/// the beginning. When the `from` parameter is used, the result will only contain -/// collection entries which have higher tick values than the specified `from` value -/// (note: the log entry with a tick value equal to `from` will be excluded). +/// When the *from* URL parameter is not used, collection events are returned from +/// the beginning. When the *from* parameter is used, the result will only contain +/// collection entries which have higher tick values than the specified *from* value +/// (note: the log entry with a tick value equal to *from* will be excluded). /// -/// The `to` URL parameter can be used to optionally restrict the upper bound of +/// The *to* URL parameter can be used to optionally restrict the upper bound of /// the result to a certain tick value. If used, the result will only contain -/// collection entries with tick values up to (including) `to`. +/// collection entries with tick values up to (including) *to*. /// -/// The `chunkSize` URL parameter can be used to control the size of the result. -/// It must be specified in bytes. The `chunkSize` value will only be honored -/// approximately. Otherwise a too low `chunkSize` value could cause the server +/// The *chunkSize* URL parameter can be used to control the size of the result. +/// It must be specified in bytes. The *chunkSize* value will only be honored +/// approximately. Otherwise a too low *chunkSize* value could cause the server /// to not be able to put just one entry into the result and return it. -/// Therefore, the `chunkSize` value will only be consulted after an entry has +/// Therefore, the *chunkSize* value will only be consulted after an entry has /// been written into the result. If the result size is then bigger than -/// `chunkSize`, the server will respond with as many entries as there are -/// in the response already. If the result size is still smaller than `chunkSize`, +/// *chunkSize*, the server will respond with as many entries as there are +/// in the response already. If the result size is still smaller than *chunkSize*, /// the server will try to return more data if there's more data left to return. /// -/// If `chunkSize` is not specified, some server-side default value will be used. +/// If *chunkSize* is not specified, some server-side default value will be used. /// -/// The `Content-Type` of the result is `application/x-arango-dump`. This is an +/// The *Content-Type* of the result is *application/x-arango-dump*. This is an /// easy-to-process format, with all entries going onto separate lines in the /// response body. /// /// Each line itself is a JSON hash, with at least the following attributes: /// -/// - `type`: the type of entry. Possible values for `type` are: +/// - *type*: the type of entry. Possible values for *type* are: /// /// - 2300: document insertion/update /// @@ -3033,17 +3056,17 @@ void RestReplicationHandler::handleCommandRestoreDataCoordinator () { /// /// - 2302: document/edge deletion /// -/// - `key`: the key of the document/edge or the key used in the deletion operation +/// - *key*: the key of the document/edge or the key used in the deletion operation /// -/// - `rev`: the revision id of the document/edge or the deletion operation +/// - *rev*: the revision id of the document/edge or the deletion operation /// -/// - `data`: the actual document/edge data for types 2300 and 2301. The full +/// - *data*: the actual document/edge data for types 2300 and 2301. The full /// document/edge data will be returned even for updates. /// /// A more detailed description of the different entry types and their /// data structures can be found in @ref RefManualReplicationEventTypes. /// -/// Note: there will be no distinction between inserts and updates when calling this method. +/// **Note**: there will be no distinction between inserts and updates when calling this method. /// /// @RESTRETURNCODES /// @@ -3051,7 +3074,7 @@ void RestReplicationHandler::handleCommandRestoreDataCoordinator () { /// is returned if the request was executed successfully. /// /// @RESTRETURNCODE{400} -/// is returned if either the `from` or `to` values are invalid. +/// is returned if either the *from* or *to* values are invalid. /// /// @RESTRETURNCODE{404} /// is returned when the collection could not be found. @@ -3098,6 +3121,7 @@ void RestReplicationHandler::handleCommandRestoreDataCoordinator () { /// /// c.drop(); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandDump () { @@ -3233,45 +3257,46 @@ void RestReplicationHandler::handleCommandDump () { } //////////////////////////////////////////////////////////////////////////////// -/// @brief synchronises data from a remote endpoint +/// @startDocuBlock JSF_put_api_replication_synchronize +/// @brief synchronizes data from a remote endpoint /// -/// @RESTHEADER{PUT /_api/replication/sync,synchronises data from a remote endpoint} +/// @RESTHEADER{PUT /_api/replication/sync, Synchronize data from a remote endpoint} /// /// @RESTBODYPARAM{configuration,json,required} /// A JSON representation of the configuration. /// /// @RESTDESCRIPTION -/// Starts a full data synchronisation from a remote endpoint into the local +/// Starts a full data synchronization from a remote endpoint into the local /// ArangoDB database. /// /// The body of the request must be JSON hash with the configuration. The /// following attributes are allowed for the configuration: /// -/// - `endpoint`: the endpoint to connect to (e.g. "tcp://192.168.173.13:8529"). +/// - *endpoint*: the endpoint to connect to (e.g. "tcp://192.168.173.13:8529"). /// -/// - `database`: the database name on the master (if not specified, defaults to the +/// - *database*: the database name on the master (if not specified, defaults to the /// name of the local current database). /// -/// - `username`: an optional ArangoDB username to use when connecting to the endpoint. +/// - *username*: an optional ArangoDB username to use when connecting to the endpoint. /// -/// - `password`: the password to use when connecting to the endpoint. +/// - *password*: the password to use when connecting to the endpoint. /// -/// - `restrictType`: an optional string value for collection filtering. When -/// specified, the allowed values are `include` or `exclude`. +/// - *restrictType*: an optional string value for collection filtering. When +/// specified, the allowed values are *include* or *exclude*. /// -/// - `restrictCollections`: an optional list of collections for use with -/// `restrictType`. If `restrictType` is `include`, only the specified collections -/// will be sychronised. If `restrictType` is `exclude`, all but the specified -/// collections will be synchronised. +/// - *restrictCollections*: an optional list of collections for use with +/// *restrictType*. If *restrictType* is *include*, only the specified collections +/// will be sychronised. If *restrictType* is *exclude*, all but the specified +/// collections will be synchronized. /// /// In case of success, the body of the response is a JSON hash with the following /// attributes: /// -/// - `collections`: a list of collections that were transferred from the endpoint +/// - *collections*: a list of collections that were transferred from the endpoint /// -/// - `lastLogTick`: the last log tick on the endpoint at the time the transfer -/// was started. Use this value as the `from` value when starting the continuous -/// synchronisation later. +/// - *lastLogTick*: the last log tick on the endpoint at the time the transfer +/// was started. Use this value as the *from* value when starting the continuous +/// synchronization later. /// /// WARNING: calling this method will sychronise data from the collections found /// on the remote endpoint to the local ArangoDB database. All data in the local @@ -3279,7 +3304,7 @@ void RestReplicationHandler::handleCommandDump () { /// /// Use with caution! /// -/// Note: this method is not supported on a coordinator in a cluster. +/// **Note**: this method is not supported on a coordinator in a cluster. /// /// @RESTRETURNCODES /// @@ -3297,6 +3322,7 @@ void RestReplicationHandler::handleCommandDump () { /// /// @RESTRETURNCODE{501} /// is returned when this operation is called on a coordinator in a cluster. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandSync () { @@ -3413,15 +3439,16 @@ void RestReplicationHandler::handleCommandSync () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_serverID /// @brief get the server's id /// -/// @RESTHEADER{GET /_api/replication/server-id,returns the servers id} +/// @RESTHEADER{GET /_api/replication/server-id, Return server id} /// /// @RESTDESCRIPTION /// Returns the servers id. The id is also returned by other replication API /// methods, and this method is an easy means of determining a server's id. /// -/// The body of the response is a JSON hash with the attribute `serverId`. The +/// The body of the response is a JSON hash with the attribute *serverId*. The /// server id is returned as a string. /// /// @RESTRETURNCODES @@ -3444,6 +3471,7 @@ void RestReplicationHandler::handleCommandSync () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandServerId () { @@ -3462,9 +3490,10 @@ void RestReplicationHandler::handleCommandServerId () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_applier /// @brief get the configuration of the replication applier /// -/// @RESTHEADER{GET /_api/replication/applier-config,returns the configuration of the replication applier} +/// @RESTHEADER{GET /_api/replication/applier-config, Return configuration of replication applier} /// /// @RESTDESCRIPTION /// Returns the configuration of the replication applier. @@ -3472,30 +3501,30 @@ void RestReplicationHandler::handleCommandServerId () { /// The body of the response is a JSON hash with the configuration. The /// following attributes may be present in the configuration: /// -/// - `endpoint`: the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). +/// - *endpoint*: the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). /// -/// - `database`: the name of the database to connect to (e.g. "_system"). +/// - *database*: the name of the database to connect to (e.g. "_system"). /// -/// - `username`: an optional ArangoDB username to use when connecting to the endpoint. +/// - *username*: an optional ArangoDB username to use when connecting to the endpoint. /// -/// - `password`: the password to use when connecting to the endpoint. +/// - *password*: the password to use when connecting to the endpoint. /// -/// - `maxConnectRetries`: the maximum number of connection attempts the applier +/// - *maxConnectRetries*: the maximum number of connection attempts the applier /// will make in a row. If the applier cannot establish a connection to the /// endpoint in this number of attempts, it will stop itself. /// -/// - `connectTimeout`: the timeout (in seconds) when attempting to connect to the +/// - *connectTimeout*: the timeout (in seconds) when attempting to connect to the /// endpoint. This value is used for each connection attempt. /// -/// - `requestTimeout`: the timeout (in seconds) for individual requests to the endpoint. +/// - *requestTimeout*: the timeout (in seconds) for individual requests to the endpoint. /// -/// - `chunkSize`: the requested maximum size for log transfer packets that +/// - *chunkSize*: the requested maximum size for log transfer packets that /// is used when the endpoint is contacted. /// -/// - `autoStart`: whether or not to auto-start the replication applier on +/// - *autoStart*: whether or not to auto-start the replication applier on /// (next and following) server starts /// -/// - `adaptivePolling`: whether or not the replication applier will use +/// - *adaptivePolling*: whether or not the replication applier will use /// adaptive polling. /// /// @RESTRETURNCODES @@ -3518,6 +3547,7 @@ void RestReplicationHandler::handleCommandServerId () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandApplierGetConfig () { @@ -3543,9 +3573,10 @@ void RestReplicationHandler::handleCommandApplierGetConfig () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_applier_adjust /// @brief set the configuration of the replication applier /// -/// @RESTHEADER{PUT /_api/replication/applier-config,adjusts the configuration of the replication applier} +/// @RESTHEADER{PUT /_api/replication/applier-config, Adjust configuration of replication applier} /// /// @RESTBODYPARAM{configuration,json,required} /// A JSON representation of the configuration. @@ -3559,32 +3590,32 @@ void RestReplicationHandler::handleCommandApplierGetConfig () { /// The body of the request must be JSON hash with the configuration. The /// following attributes are allowed for the configuration: /// -/// - `endpoint`: the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). +/// - *endpoint*: the logger server to connect to (e.g. "tcp://192.168.173.13:8529"). /// The endpoint must be specified. /// -/// - `database`: the name of the database on the endpoint. If not specified, defaults +/// - *database*: the name of the database on the endpoint. If not specified, defaults /// to the current local database name. /// -/// - `username`: an optional ArangoDB username to use when connecting to the endpoint. +/// - *username*: an optional ArangoDB username to use when connecting to the endpoint. /// -/// - `password`: the password to use when connecting to the endpoint. +/// - *password*: the password to use when connecting to the endpoint. /// -/// - `maxConnectRetries`: the maximum number of connection attempts the applier +/// - *maxConnectRetries*: the maximum number of connection attempts the applier /// will make in a row. If the applier cannot establish a connection to the /// endpoint in this number of attempts, it will stop itself. /// -/// - `connectTimeout`: the timeout (in seconds) when attempting to connect to the +/// - *connectTimeout*: the timeout (in seconds) when attempting to connect to the /// endpoint. This value is used for each connection attempt. /// -/// - `requestTimeout`: the timeout (in seconds) for individual requests to the endpoint. +/// - *requestTimeout*: the timeout (in seconds) for individual requests to the endpoint. /// -/// - `chunkSize`: the requested maximum size for log transfer packets that +/// - *chunkSize*: the requested maximum size for log transfer packets that /// is used when the endpoint is contacted. /// -/// - `autoStart`: whether or not to auto-start the replication applier on +/// - *autoStart*: whether or not to auto-start the replication applier on /// (next and following) server starts /// -/// - `adaptivePolling`: if set to `true`, the replication applier will fall +/// - *adaptivePolling*: if set to *true*, the replication applier will fall /// to sleep for an increasingly long period in case the logger server at the /// endpoint does not have any more replication events to apply. Using /// adaptive polling is thus useful to reduce the amount of work for both the @@ -3593,7 +3624,7 @@ void RestReplicationHandler::handleCommandApplierGetConfig () { /// longer for the replication applier to detect that there are new replication /// events on the logger server. /// -/// Setting `adaptivePolling` to false will make the replication applier +/// Setting *adaptivePolling* to false will make the replication applier /// contact the logger server in a constant interval, regardless of whether /// the logger server provides updates frequently or seldomly. /// @@ -3636,6 +3667,7 @@ void RestReplicationHandler::handleCommandApplierGetConfig () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandApplierSetConfig () { @@ -3724,14 +3756,15 @@ void RestReplicationHandler::handleCommandApplierSetConfig () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_applier_start /// @brief start the replication applier /// -/// @RESTHEADER{PUT /_api/replication/applier-start,starts the replication applier} +/// @RESTHEADER{PUT /_api/replication/applier-start, Start replication applier} /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{from,string,optional} -/// The remote `lastLogTick` value from which to start applying. If not specified, +/// The remote *lastLogTick* value from which to start applying. If not specified, /// the last saved tick from the previous applier run is used. If there is no /// previous applier state saved, the applier will start at the beginning of the /// logger server's log. @@ -3747,7 +3780,7 @@ void RestReplicationHandler::handleCommandApplierSetConfig () { /// method. /// /// To detect replication applier errors after the applier was started, use the -/// `/_api/replication/applier-state` API instead. +/// */_api/replication/applier-state* API instead. /// /// @RESTRETURNCODES /// @@ -3784,6 +3817,7 @@ void RestReplicationHandler::handleCommandApplierSetConfig () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandApplierStart () { @@ -3817,9 +3851,10 @@ void RestReplicationHandler::handleCommandApplierStart () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_replication_applier_stop /// @brief stops the replication applier /// -/// @RESTHEADER{PUT /_api/replication/applier-stop,stops the replication applier} +/// @RESTHEADER{PUT /_api/replication/applier-stop, Stop replication applier} /// /// @RESTDESCRIPTION /// Stops the replication applier. This will return immediately if the @@ -3857,6 +3892,7 @@ void RestReplicationHandler::handleCommandApplierStart () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandApplierStop () { @@ -3873,9 +3909,10 @@ void RestReplicationHandler::handleCommandApplierStop () { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_replication_applier_state /// @brief returns the state of the replication applier /// -/// @RESTHEADER{GET /_api/replication/applier-state,returns the state of the replication applier} +/// @RESTHEADER{GET /_api/replication/applier-state, State of the replication applier} /// /// @RESTDESCRIPTION /// Returns the state of the replication applier, regardless of whether the @@ -3883,66 +3920,66 @@ void RestReplicationHandler::handleCommandApplierStop () { /// /// The response is a JSON hash with the following attributes: /// -/// - `state`: a JSON hash with the following sub-attributes: +/// - *state*: a JSON hash with the following sub-attributes: /// -/// - `running`: whether or not the applier is active and running +/// - *running*: whether or not the applier is active and running /// -/// - `lastAppliedContinuousTick`: the last tick value from the continuous +/// - *lastAppliedContinuousTick*: the last tick value from the continuous /// replication log the applier has applied. /// -/// - `lastProcessedContinuousTick`: the last tick value from the continuous +/// - *lastProcessedContinuousTick*: the last tick value from the continuous /// replication log the applier has processed. /// /// Regularly, the last applied and last processed tick values should be /// identical. For transactional operations, the replication applier will first /// process incoming log events before applying them, so the processed tick /// value might be higher than the applied tick value. This will be the case -/// until the applier encounters the `transaction commit` log event for the +/// until the applier encounters the *transaction commit* log event for the /// transaction. /// -/// - `lastAvailableContinuousTick`: the last tick value the logger server can +/// - *lastAvailableContinuousTick*: the last tick value the logger server can /// provide. /// -/// - `time`: the time on the applier server. +/// - *time*: the time on the applier server. /// -/// - `totalRequests`: the total number of requests the applier has made to the +/// - *totalRequests*: the total number of requests the applier has made to the /// endpoint. /// -/// - `totalFailedConnects`: the total number of failed connection attempts the +/// - *totalFailedConnects*: the total number of failed connection attempts the /// applier has made. /// -/// - `totalEvents`: the total number of log events the applier has processed. +/// - *totalEvents*: the total number of log events the applier has processed. /// -/// - `progress`: a JSON hash with details about the replication applier progress. +/// - *progress*: a JSON hash with details about the replication applier progress. /// It contains the following sub-attributes if there is progress to report: /// -/// - `message`: a textual description of the progress +/// - *message*: a textual description of the progress /// -/// - `time`: the date and time the progress was logged +/// - *time*: the date and time the progress was logged /// -/// - `failedConnects`: the current number of failed connection attempts +/// - *failedConnects*: the current number of failed connection attempts /// -/// - `lastError`: a JSON hash with details about the last error that happened on +/// - *lastError*: a JSON hash with details about the last error that happened on /// the applier. It contains the following sub-attributes if there was an error: /// -/// - `errorNum`: a numerical error code +/// - *errorNum*: a numerical error code /// -/// - `errorMessage`: a textual error description +/// - *errorMessage*: a textual error description /// -/// - `time`: the date and time the error occurred +/// - *time*: the date and time the error occurred /// -/// In case no error has occurred, `lastError` will be empty. +/// In case no error has occurred, *lastError* will be empty. /// -/// - `server`: a JSON hash with the following sub-attributes: +/// - *server*: a JSON hash with the following sub-attributes: /// -/// - `version`: the applier server's version +/// - *version*: the applier server's version /// -/// - `serverId`: the applier server's id +/// - *serverId*: the applier server's id /// -/// - `endpoint`: the endpoint the applier is connected to (if applier is +/// - *endpoint*: the endpoint the applier is connected to (if applier is /// active) or will connect to (if applier is currently inactive) /// -/// - `database`: the name of the database the applier is connected to (if applier is +/// - *database*: the name of the database the applier is connected to (if applier is /// active) or will connect to (if applier is currently inactive) /// /// @RESTRETURNCODES @@ -3985,6 +4022,7 @@ void RestReplicationHandler::handleCommandApplierStop () { /// assert(response.code === 200); /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// void RestReplicationHandler::handleCommandApplierGetState () { diff --git a/js/actions/api-aqlfunction.js b/js/actions/api-aqlfunction.js index 79bd89c3bb..b69406b6d6 100644 --- a/js/actions/api-aqlfunction.js +++ b/js/actions/api-aqlfunction.js @@ -42,14 +42,15 @@ var aqlfunctions = require("org/arangodb/aql/functions"); //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_aqlfunction /// @brief gets all reqistered AQL user functions /// -/// @RESTHEADER{GET /_api/aqlfunction,returns registered AQL user functions} +/// @RESTHEADER{GET /_api/aqlfunction, Return registered AQL user functions} /// /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{namespace,string,optional} -/// Returns all registered AQL user functions from namespace `namespace`. +/// Returns all registered AQL user functions from namespace *namespace*. /// /// @RESTDESCRIPTION /// Returns all registered AQL user functions. @@ -57,16 +58,16 @@ var aqlfunctions = require("org/arangodb/aql/functions"); /// The call will return a JSON list with all user functions found. Each user /// function will at least have the following attributes: /// -/// - `name`: The fully qualified name of the user function +/// - *name*: The fully qualified name of the user function /// -/// - `code`: A string representation of the function body +/// - *code*: A string representation of the function body /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// if success `HTTP 200` is returned. +/// if success *HTTP 200* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestAqlfunctionsGetAll} /// var url = "/_api/aqlfunction"; @@ -77,6 +78,7 @@ var aqlfunctions = require("org/arangodb/aql/functions"); /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function get_api_aqlfunction (req, res) { @@ -95,9 +97,10 @@ function get_api_aqlfunction (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_aqlfunction /// @brief create a new AQL user function /// -/// @RESTHEADER{POST /_api/aqlfunction,creates or replaces an AQL user function} +/// @RESTHEADER{POST /_api/aqlfunction, Create AQL user function} /// /// @RESTBODYPARAM{body,json,required} /// the body with name and code of the aql user function. @@ -107,49 +110,49 @@ function get_api_aqlfunction (req, res) { /// The following data need to be passed in a JSON representation in the body of /// the POST request: /// -/// - `name`: the fully qualified name of the user functions. +/// - *name*: the fully qualified name of the user functions. /// -/// - `code`: a string representation of the function body. +/// - *code*: a string representation of the function body. /// -/// - `isDeterministic`: an optional boolean value to indicate that the function +/// - *isDeterministic*: an optional boolean value to indicate that the function /// results are fully deterministic (function return value solely depends on /// the input value and return value is the same for repeated calls with same -/// input). The `isDeterministic` attribute is currently not used but may be +/// input). The *isDeterministic* attribute is currently not used but may be /// used later for optimisations. /// /// In case of success, the returned JSON object has the following properties: /// -/// - `error`: boolean flag to indicate that an error occurred (`false` +/// - *error*: boolean flag to indicate that an error occurred (*false* /// in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// /// The body of the response will contain a JSON object with additional error /// details. The object has the following attributes: /// -/// - `error`: boolean flag to indicate that an error occurred (`true` in this case) +/// - *error*: boolean flag to indicate that an error occurred (*true* in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// -/// - `errorNum`: the server error number +/// - *errorNum*: the server error number /// -/// - `errorMessage`: a descriptive error message +/// - *errorMessage*: a descriptive error message /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} /// If the function already existed and was replaced by the -/// call, the server will respond with `HTTP 200`. +/// call, the server will respond with *HTTP 200*. /// /// @RESTRETURNCODE{201} /// If the function can be registered by the server, the server will respond with -/// `HTTP 201`. +/// *HTTP 201*. /// /// @RESTRETURNCODE{400} /// If the JSON representation is malformed or mandatory data is missing from the -/// request, the server will respond with `HTTP 400`. +/// request, the server will respond with *HTTP 400*. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestAqlfunctionCreate} /// var url = "/_api/aqlfunction"; @@ -164,6 +167,7 @@ function get_api_aqlfunction (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_aqlfunction (req, res) { @@ -179,9 +183,10 @@ function post_api_aqlfunction (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_delete_api_aqlfunction /// @brief remove an existing AQL user function /// -/// @RESTHEADER{DELETE /_api/aqlfunction/{name},remove an existing AQL user function} +/// @RESTHEADER{DELETE /_api/aqlfunction/name, Remove existing AQL user function} /// /// @RESTURLPARAMETERS /// @@ -191,46 +196,46 @@ function post_api_aqlfunction (req, res) { /// @RESTQUERYPARAMETERS /// /// @RESTQUERYPARAM{group,string,optional} -/// If set to `true`, then the function name provided in `name` is treated as +/// If set to *true*, then the function name provided in *name* is treated as /// a namespace prefix, and all functions in the specified namespace will be deleted. -/// If set to `false`, the function name provided in `name` must be fully +/// If set to *false*, the function name provided in *name* must be fully /// qualified, including any namespaces. /// /// @RESTDESCRIPTION /// -/// Removes an existing AQL user function, identified by `name`. +/// Removes an existing AQL user function, identified by *name*. /// /// In case of success, the returned JSON object has the following properties: /// -/// - `error`: boolean flag to indicate that an error occurred (`false` +/// - *error*: boolean flag to indicate that an error occurred (*false* /// in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// /// The body of the response will contain a JSON object with additional error /// details. The object has the following attributes: /// -/// - `error`: boolean flag to indicate that an error occurred (`true` in this case) +/// - *error*: boolean flag to indicate that an error occurred (*true* in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// -/// - `errorNum`: the server error number +/// - *errorNum*: the server error number /// -/// - `errorMessage`: a descriptive error message +/// - *errorMessage*: a descriptive error message /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} /// If the function can be removed by the server, the server will respond with -/// `HTTP 200`. +/// *HTTP 200*. /// /// @RESTRETURNCODE{400} -/// If the user function name is malformed, the server will respond with `HTTP 400`. +/// If the user function name is malformed, the server will respond with *HTTP 400*. /// /// @RESTRETURNCODE{404} -/// If the specified user user function does not exist, the server will respond with `HTTP 404`. +/// If the specified user user function does not exist, the server will respond with *HTTP 404*. /// -/// *Examples* +/// @EXAMPLES /// /// deletes a function: /// @@ -257,6 +262,7 @@ function post_api_aqlfunction (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function delete_api_aqlfunction (req, res) { diff --git a/js/actions/api-collection.js b/js/actions/api-collection.js index 536fb38bc6..104dc74b37 100644 --- a/js/actions/api-collection.js +++ b/js/actions/api-collection.js @@ -176,9 +176,10 @@ function parseBodyForCreateCollection (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_collection /// @brief creates a collection /// -/// @RESTHEADER{POST /_api/collection,creates a collection} +/// @RESTHEADER{POST /_api/collection, Create collection} /// /// @RESTBODYPARAM{body,json,required} /// the body with name and options for a collection. @@ -187,27 +188,28 @@ function parseBodyForCreateCollection (req, res) { /// Creates an new collection with a given name. The request must contain an /// object with the following attributes. /// -/// - `name`: The name of the collection. +/// - *name*: The name of the collection. /// -/// - `waitForSync` (optional, default: false): If `true` then +/// - *waitForSync* (optional, default: false): If *true* then /// the data is synchronised to disk before returning from a create or /// update of a document. /// -/// - `doCompact` (optional, default is `true`): whether or not the collection +/// - *doCompact* (optional, default is *true*): whether or not the collection /// will be compacted. /// -/// - `journalSize` (optional, default is a @ref +/// - *journalSize* (optional, default is a @ref /// CommandLineArangod "configuration parameter"): The maximal size of -/// a journal or datafile. Note that this also limits the maximal +/// a journal or datafile. +/// **Note**: 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 +/// - *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 +/// - *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 @@ -219,39 +221,39 @@ function parseBodyForCreateCollection (req, res) { /// This option should threrefore be used for cache-type collections only, /// and not for data that cannot be re-created otherwise. /// -/// - `keyOptions` (optional) additional options for key generation. If -/// specified, then `keyOptions` should be a JSON array containing the +/// - *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 +/// - *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. +/// - *increment*: increment value for *autoincrement* key generator. /// Not used for other key generator types. -/// - `offset`: initial offset value for `autoincrement` key generator. +/// - *offset*: initial offset value for *autoincrement* key generator. /// Not used for other key generator types. /// -/// - `type` (optional, default is `2`): the type of the collection to -/// create. The following values for `type` are valid: -/// - `2`: document collection -/// - `3`: edges collection +/// - *type* (optional, default is *2*): the type of the collection to +/// create. The following values for *type* are valid: +/// - *2*: document collection +/// - *3*: edges collection /// -/// - `numberOfShards` (optional, default is `1`): in a cluster, this value +/// - *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 +/// - *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 of 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. +/// determine the target shard. +/// **Note**: Values of shard key attributes cannot be changed once set. /// This option is meaningless in a single server setup. -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestCollectionCreateCollection} /// var url = "/_api/collection"; @@ -298,6 +300,7 @@ function parseBodyForCreateCollection (req, res) { /// db._flushCache(); /// db._drop("testCollectionUsers"); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_collection (req, res) { @@ -355,6 +358,7 @@ function post_api_collection (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_collections /// @brief returns all collections /// /// @RESTHEADER{GET /_api/collection,reads all collections} @@ -365,15 +369,15 @@ function post_api_collection (req, res) { /// Whether or not system collections should be excluded from the result. /// /// @RESTDESCRIPTION -/// Returns an object with an attribute `collections` containing a +/// Returns an object with an attribute *collections* containing a /// list of all collection descriptions. The same information is also -/// available in the `names` as hash map with the collection names +/// available in the *names* as hash map with the collection names /// as keys. /// -/// By providing the optional URL parameter `excludeSystem` with a value of -/// `true`, all system collections will be excluded from the response. +/// By providing the optional URL parameter *excludeSystem* with a value of +/// *true*, all system collections will be excluded from the response. /// -/// *Examples* +/// @EXAMPLES /// /// Return information about all collections: /// @@ -386,6 +390,7 @@ function post_api_collection (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function get_api_collections (req, res) { @@ -420,10 +425,10 @@ function get_api_collections (req, res) { } //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_get_api_collection_name +/// @startDocuBlock JSA_get_api_collection_name /// @brief returns a collection /// -/// @RESTHEADER{GET /_api/collection/{collection-name},returns information about a collection} +/// @RESTHEADER{GET /_api/collection/{collection-name}, Return information about a collection} /// /// @RESTURLPARAMETERS /// @@ -434,11 +439,11 @@ function get_api_collections (req, res) { /// The result is an object describing the collection with the following /// attributes: /// -/// - `id`: The identifier of the collection. +/// - *id*: The identifier of the collection. /// -/// - `name`: The name of the collection. +/// - *name*: The name of the collection. /// -/// - `status`: The status of the collection as number. +/// - *status*: The status of the collection as number. /// - 1: new born collection /// - 2: unloaded /// - 3: loaded @@ -447,22 +452,22 @@ function get_api_collections (req, res) { /// /// Every other status indicates a corrupted collection. /// -/// - `type`: The type of the collection as number. +/// - *type*: The type of the collection as number. /// - 2: document collection (normal case) /// - 3: edges collection /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is +/// If the *collection-name* is unknown, then a *HTTP 404* is /// returned. -/// +/// @endDocuBlock ///////////////////////////////////////////////////////////////////////////// ///////////////////////////////////////////////////////////////////////////// -/// @fn JSA_get_api_collection_properties +/// @startDocuBlock JSA_get_api_collection_properties /// -/// @RESTHEADER{GET /_api/collection/{collection-name}/properties,reads the properties of a collection} +/// @RESTHEADER{GET /_api/collection/{collection-name}/properties, Read properties of a collection} /// /// @RESTURLPARAMETERS /// @@ -471,36 +476,36 @@ function get_api_collections (req, res) { /// /// @RESTDESCRIPTION /// In addition to the above, the result will always contain the -/// `waitForSync`, `doCompact`, `journalSize`, and `isVolatile` attributes. +/// *waitForSync*, *doCompact*, *journalSize*, and *isVolatile* attributes. /// This is achieved by forcing a load of the underlying collection. /// -/// - `waitForSync`: If `true` then creating or changing a +/// - *waitForSync*: If *true* then creating or changing a /// document will wait until the data has been synchronised to disk. /// -/// - `doCompact`: Whether or not the collection will be compacted. +/// - *doCompact*: Whether or not the collection will be compacted. /// -/// - `journalSize`: The maximal size setting for journals / datafiles. +/// - *journalSize*: The maximal size setting for journals / datafiles. /// -/// - `isVolatile`: If `true` then the collection data will be +/// - *isVolatile*: If *true* then the collection data will be /// kept in memory only and ArangoDB will not write or sync the data /// to disk. /// /// In a cluster setup, the result will also contain the following attributes: -/// - `numberOfShards`: the number of shards of the collection. +/// - *numberOfShards*: the number of shards of the collection. /// -/// - `shardKeys`: contains the names of document attributes that are used to +/// - *shardKeys*: contains the names of document attributes that are used to /// determine the target shard for documents. /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` +/// If the *collection-name* is unknown, then a *HTTP 404* /// is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Using an identifier: /// @@ -532,12 +537,13 @@ function get_api_collections (req, res) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////// -/// @fn JSA_get_api_collection_count +/// @startDocuBlock JSA_get_api_collection_count /// -/// @RESTHEADER{GET /_api/collection/{collection-name}/count,returns the number of documents in a collection} +/// @RESTHEADER{GET /_api/collection/{collection-name}/count, Return number of documents in a collection} /// /// @RESTURLPARAMETERS /// @@ -546,21 +552,21 @@ function get_api_collections (req, res) { /// /// @RESTDESCRIPTION /// In addition to the above, the result also contains the number of documents. -/// Note that this will always load the collection into memory. +/// **Note** that this will always load the collection into memory. /// -/// - `count`: The number of documents inside the collection. +/// - *count*: The number of documents inside the collection. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` +/// If the *collection-name* is unknown, then a *HTTP 404* /// is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Using an identifier and requesting the number of documents: /// @@ -580,12 +586,13 @@ function get_api_collections (req, res) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////// -/// @fn JSA_get_api_collection_figures +/// @startDocuBlock JSA_get_api_collection_figures /// -/// @RESTHEADER{GET /_api/collection/{collection-name}/figures,returns the stats for a collection} +/// @RESTHEADER{GET /_api/collection/{collection-name}/figures, Return stats for a collection} /// /// @RESTURLPARAMETERS /// @@ -594,77 +601,77 @@ function get_api_collections (req, res) { /// /// @RESTDESCRIPTION /// In addition to the above, the result also contains the number of documents -/// and additional statistical information about the collection. Note that this -/// will always load the collection into memory. +/// and additional statistical information about the collection. +/// **Note** : This will always load the collection into memory. /// -/// - `count`: The number of documents currently present in the collection. +/// - *count*: The number of documents currently present in the collection. /// -/// - `figures.alive.count`: The number of currently active documents. +/// - *figures.alive.count*: The number of currently active documents. /// -/// - `figures.alive.size`: The total size in bytes used by all +/// - *figures.alive.size*: The total size in bytes used by all /// active documents. /// -/// - `figures.dead.count`: The number of dead documents. This includes document +/// - *figures.dead.count*: The number of dead documents. This includes document /// versions that have been deleted or replaced by a newer version. /// -/// - `figures.dead.size`: The total size in bytes used by all dead documents. +/// - *figures.dead.size*: The total size in bytes used by all dead documents. /// -/// - `figures.dead.deletion`: The total number of deletion markers in the +/// - *figures.dead.deletion*: The total number of deletion markers in the /// collection. /// -/// - `figures.datafiles.count`: The number of current datafiles. -/// - `figures.datafiles.fileSize`: The total filesize of all datafiles. +/// - *figures.datafiles.count*: The number of current datafiles. +/// - *figures.datafiles.fileSize*: The total filesize of all datafiles. /// -/// - `figures.journals.count`: The number of journal files. -/// - `figures.journals.fileSize`: The total filesize of all journal files. +/// - *figures.journals.count*: The number of journal files. +/// - *figures.journals.fileSize*: The total filesize of all journal files. /// -/// - `figures.compactors.count`: The number of compactor files. -/// - `figures.compactors.fileSize`: The total filesize of all compactor files. +/// - *figures.compactors.count*: The number of compactor files. +/// - *figures.compactors.fileSize*: The total filesize of all compactor files. /// -/// - `figures.shapefiles.count`: The number of shape files. -/// - `figures.shapefiles.fileSize`: The total filesize of all shape files. +/// - *figures.shapefiles.count*: The number of shape files. +/// - *figures.shapefiles.fileSize*: The total filesize of all shape files. /// -/// - `figures.shapes.count`: The total number of shapes in the +/// - *figures.shapes.count*: The total number of shapes in the /// collection (this includes shapes that are not in use anymore) /// -/// - `figures.attributes.count`: The total number of attributes in the +/// - *figures.attributes.count*: The total number of attributes in the /// collection (this includes attributes that are not in use anymore) /// -/// - `figures.attributes.size`: The total size used by all attribute +/// - *figures.attributes.size*: The total size used by all attribute /// names in the collection (this includes attributes that are not in use anymore) /// -/// - `figures.indexes.count`: The total number of indexes defined for the +/// - *figures.indexes.count*: The total number of indexes defined for the /// collection (this includes internal indexes such as the primary index) /// -/// - `figures.indexes.size`: The total memory allocated by the indexes in bytes +/// - *figures.indexes.size*: The total memory allocated by the indexes in bytes /// -/// - `journalSize`: The maximal size of the journal in bytes. +/// - *journalSize*: The maximal size of the journal in bytes. /// -/// Note: the filesizes of collection and index parameter JSON files are +/// **Note**: 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 +/// 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. +/// 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 +/// *fileSize* values. Still the sum of the *fileSize* values can still be /// used as a lower bound approximation of the disk usage. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` +/// If the *collection-name* is unknown, then a *HTTP 404* /// is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Using an identifier and requesting the figures of the collection: /// @@ -681,12 +688,13 @@ function get_api_collections (req, res) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock /////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_get_api_collection_revision +/// @startDocuBlock JSA_get_api_collection_revision /// -/// @RESTHEADER{GET /_api/collection/{collection-name}/revision,return a collection revision id} +/// @RESTHEADER{GET /_api/collection/{collection-name}/revision, Return collection revision id} /// /// @RESTURLPARAMETERS /// @@ -699,19 +707,19 @@ function get_api_collections (req, res) { /// string that clients can use to check whether data in a collection /// has changed since the last revision check. /// -/// - `revision`: The collection revision id as a string. +/// - *revision*: The collection revision id as a string. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` +/// If the *collection-name* is unknown, then a *HTTP 404* /// is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Retrieving the revision of a collection /// @@ -728,12 +736,13 @@ function get_api_collections (req, res) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// /////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_get_api_collection_checksum +/// @startDocuBlock JSA_get_api_collection_checksum /// -/// @RESTHEADER{GET /_api/collection/{collection-name}/checksum,returns a checksum for the collection} +/// @RESTHEADER{GET /_api/collection/{collection-name}/checksum, Return checksum for the collection} /// /// @RESTURLPARAMETERS /// @@ -757,36 +766,36 @@ function get_api_collections (req, res) { /// returned too so one can make sure the checksums are calculated for the same /// state of data. /// -/// By default, the checksum will only be calculated on the `_key` system attribute +/// By default, the checksum will only be calculated on the *_key* system attribute /// of the documents contained in the collection. For edge collections, the system -/// attributes `_from` and `_to` will also be included in the calculation. +/// attributes *_from* and *_to* will also be included in the calculation. /// -/// By setting the optional URL parameter `withRevisions` to `true`, then revision -/// ids (`_rev` system attributes) are included in the checksumming. +/// By setting the optional URL parameter *withRevisions* to *true*, then revision +/// ids (*_rev* system attributes) are included in the checksumming. /// -/// By providing the optional URL parameter `withData` with a value of `true`, +/// By providing the optional URL parameter *withData* with a value of *true*, /// the user-defined document attributes will be included in the calculation too. -/// Note that including user-defined attributes will make the checksumming slower. +/// **Note**: Including user-defined attributes will make the checksumming slower. /// /// The response is a JSON object with the following attributes: /// -/// - `checksum`: The calculated checksum as a number. +/// - *checksum*: The calculated checksum as a number. /// -/// - `revision`: The collection revision id as a string. +/// - *revision*: The collection revision id as a string. /// -/// Note: this method is not available in a cluster. +/// **Note**: this method is not available in a cluster. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` +/// If the *collection-name* is unknown, then a *HTTP 404* /// is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Retrieving the checksum of a collection: /// @@ -822,6 +831,7 @@ function get_api_collections (req, res) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function get_api_collection (req, res) { @@ -957,9 +967,10 @@ function get_api_collection (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_collection_load /// @brief loads a collection /// -/// @RESTHEADER{PUT /_api/collection/{collection-name}/load,loads a collection} +/// @RESTHEADER{PUT /_api/collection/{collection-name}/load, Load collection} /// /// @RESTURLPARAMETERS /// @@ -971,38 +982,38 @@ function get_api_collection (req, res) { /// /// The request might optionally contain the following attribute: /// -/// - `count`: If set, this controls whether the return value should include -/// the number of documents in the collection. Setting `count` to -/// `false` may speed up loading a collection. The default value for -/// `count` is `true`. +/// - *count*: If set, this controls whether the return value should include +/// the number of documents in the collection. Setting *count* to +/// *false* may speed up loading a collection. The default value for +/// *count* is *true*. /// /// On success an object with the following attributes is returned: /// -/// - `id`: The identifier of the collection. +/// - *id*: The identifier of the collection. /// -/// - `name`: The name of the collection. +/// - *name*: The name of the collection. /// -/// - `count`: The number of documents inside the collection. This is only -/// returned if the `count` input parameters is set to `true` or has +/// - *count*: The number of documents inside the collection. This is only +/// returned if the *count* input parameters is set to *true* or has /// not been specified. /// -/// - `status`: The status of the collection as number. +/// - *status*: The status of the collection as number. /// -/// - `type`: The collection type. Valid types are: +/// - *type*: The collection type. Valid types are: /// - 2: document collection /// - 3: edges collection /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` +/// If the *collection-name* is unknown, then a *HTTP 404* /// is returned. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestCollectionIdentifierLoad} /// var cn = "products"; @@ -1017,6 +1028,7 @@ function get_api_collection (req, res) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function put_api_collection_load (req, res, collection) { @@ -1040,9 +1052,10 @@ function put_api_collection_load (req, res, collection) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_collection_unload /// @brief unloads a collection /// -/// @RESTHEADER{PUT /_api/collection/{collection-name}/unload,unloads a collection} +/// @RESTHEADER{PUT /_api/collection/{collection-name}/unload, Unload collection} /// /// @RESTURLPARAMETERS /// @@ -1054,26 +1067,26 @@ function put_api_collection_load (req, res, collection) { /// memory, again. On success an object with the following attributes is /// returned: /// -/// - `id`: The identifier of the collection. +/// - *id*: The identifier of the collection. /// -/// - `name`: The name of the collection. +/// - *name*: The name of the collection. /// -/// - `status`: The status of the collection as number. +/// - *status*: The status of the collection as number. /// -/// - `type`: The collection type. Valid types are: +/// - *type*: The collection type. Valid types are: /// - 2: document collection /// - 3: edges collection /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestCollectionIdentifierUnload} /// var cn = "products"; @@ -1088,6 +1101,7 @@ function put_api_collection_load (req, res, collection) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function put_api_collection_unload (req, res, collection) { @@ -1104,9 +1118,10 @@ function put_api_collection_unload (req, res, collection) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_collection_truncate /// @brief truncates a collection /// -/// @RESTHEADER{PUT /_api/collection/{collection-name}/truncate,truncates a collection} +/// @RESTHEADER{PUT /_api/collection/{collection-name}/truncate, Truncate collection} /// /// @RESTURLPARAMETERS /// @@ -1116,7 +1131,7 @@ function put_api_collection_unload (req, res, collection) { /// @RESTDESCRIPTION /// Removes all documents from the collection, but leaves the indexes intact. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestCollectionIdentifierTruncate} /// var cn = "products"; @@ -1131,6 +1146,7 @@ function put_api_collection_unload (req, res, collection) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function put_api_collection_truncate (req, res, collection) { @@ -1147,9 +1163,10 @@ function put_api_collection_truncate (req, res, collection) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_collection_properties /// @brief changes a collection /// -/// @RESTHEADER{PUT /_api/collection/{collection-name}/properties,changes the properties of a collection} +/// @RESTHEADER{PUT /_api/collection/{collection-name}/properties, Change properties of a collection} /// /// @RESTURLPARAMETERS /// @@ -1160,33 +1177,33 @@ function put_api_collection_truncate (req, res, collection) { /// Changes the properties of a collection. Expects an object with the /// attribute(s) /// -/// - `waitForSync`: If `true` then creating or changing a +/// - *waitForSync*: If *true* then creating or changing a /// document will wait until the data has been synchronised to disk. /// -/// - `journalSize`: Size (in bytes) for new journal files that are +/// - *journalSize*: Size (in bytes) for new journal files that are /// created for the collection. /// /// If returns an object with the attributes /// -/// - `id`: The identifier of the collection. +/// - *id*: The identifier of the collection. /// -/// - `name`: The name of the collection. +/// - *name*: The name of the collection. /// -/// - `waitForSync`: The new value. +/// - *waitForSync*: The new value. /// -/// - `journalSize`: The new value. +/// - *journalSize*: The new value. /// -/// - `status`: The status of the collection as number. +/// - *status*: The status of the collection as number. /// -/// - `type`: The collection type. Valid types are: +/// - *type*: The collection type. Valid types are: /// - 2: document collection /// - 3: edges collection /// -/// Note: some other collection properties, such as `type`, `isVolatile`, -/// `numberOfShards` or `shardKeys` cannot be changed once a collection is +/// **Note**: some other collection properties, such as *type*, *isVolatile*, +/// *numberOfShards* or *shardKeys* cannot be changed once a collection is /// created. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestCollectionIdentifierPropertiesSync} /// var cn = "products"; @@ -1201,6 +1218,7 @@ function put_api_collection_truncate (req, res, collection) { /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function put_api_collection_properties (req, res, collection) { @@ -1223,9 +1241,10 @@ function put_api_collection_properties (req, res, collection) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_collection_rename /// @brief renames a collection /// -/// @RESTHEADER{PUT /_api/collection/{collection-name}/rename,renames a collection} +/// @RESTHEADER{PUT /_api/collection/{collection-name}/rename, Rename collection} /// /// @RESTURLPARAMETERS /// @@ -1235,21 +1254,21 @@ function put_api_collection_properties (req, res, collection) { /// @RESTDESCRIPTION /// Renames a collection. Expects an object with the attribute(s) /// -/// - `name`: The new name. +/// - *name*: The new name. /// /// If returns an object with the attributes /// -/// - `id`: The identifier of the collection. +/// - *id*: The identifier of the collection. /// -/// - `name`: The new name of the collection. +/// - *name*: The new name of the collection. /// -/// - `status`: The status of the collection as number. +/// - *status*: The status of the collection as number. /// -/// - `type`: The collection type. Valid types are: +/// - *type*: The collection type. Valid types are: /// - 2: document collection /// - 3: edges collection /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestCollectionIdentifierRename} /// var cn = "products1"; @@ -1264,6 +1283,7 @@ function put_api_collection_properties (req, res, collection) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function put_api_collection_rename (req, res, collection) { @@ -1294,9 +1314,10 @@ function put_api_collection_rename (req, res, collection) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_put_api_collection_rotate /// @brief rotates the journal of a collection /// -/// @RESTHEADER{PUT /_api/collection/{collection-name}/rotate,rotates the journal of a collection} +/// @RESTHEADER{PUT /_api/collection/{collection-name}/rotate, Rotate journal of a collection} /// /// @RESTURLPARAMETERS /// @@ -1314,19 +1335,19 @@ function put_api_collection_rename (req, res, collection) { /// /// If returns an object with the attributes /// -/// - `result`: will be `true` if rotation succeeded +/// - *result*: will be *true* if rotation succeeded /// -/// Note: this method is not available in a cluster. +/// **Note**: This method is not available in a cluster. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the collection currently has no journal, `HTTP 500` is returned. +/// If the collection currently has no journal, *HTTP 500* is returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Rotating a journal: /// @@ -1363,6 +1384,7 @@ function put_api_collection_rename (req, res, collection) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function put_api_collection_rotate (req, res, collection) { @@ -1423,9 +1445,10 @@ function put_api_collection (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_delete_api_collection /// @brief deletes a collection /// -/// @RESTHEADER{DELETE /_api/collection/{collection-name},deletes a collection} +/// @RESTHEADER{DELETE /_api/collection/{collection-name}, Delete collection} /// /// @RESTURLPARAMETERS /// @@ -1433,25 +1456,25 @@ function put_api_collection (req, res) { /// The name of the collection to delete. /// /// @RESTDESCRIPTION -/// Deletes a collection identified by `collection-name`. +/// Deletes a collection identified by *collection-name*. /// /// If the collection was successfully deleted then, an object is returned with /// the following attributes: /// -/// - `error`: `false` +/// - *error*: *false* /// -/// - `id`: The identifier of the deleted collection. +/// - *id*: The identifier of the deleted collection. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{400} -/// If the `collection-name` is missing, then a `HTTP 400` is +/// If the *collection-name* is missing, then a *HTTP 400* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Using an identifier: /// @@ -1483,6 +1506,7 @@ function put_api_collection (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function delete_api_collection (req, res) { diff --git a/js/actions/api-cursor.js b/js/actions/api-cursor.js index 2a7b5afa9f..2537ecd12d 100644 --- a/js/actions/api-cursor.js +++ b/js/actions/api-cursor.js @@ -47,9 +47,10 @@ var internal = require("internal"); //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_cursor /// @brief create a cursor and return the first results /// -/// @RESTHEADER{POST /_api/cursor,creates a cursor} +/// @RESTHEADER{POST /_api/cursor, Create cursor} /// /// @RESTBODYPARAM{query,json,required} /// A JSON object describing the query and query parameters. @@ -61,74 +62,74 @@ var internal = require("internal"); /// /// The following attributes can be used inside the JSON object: /// -/// - `query`: contains the query string to be executed (mandatory) +/// - *query*: contains the query string to be executed (mandatory) /// -/// - `count`: boolean flag that indicates whether the number of documents +/// - *count*: boolean flag that indicates whether the number of documents /// in the result set should be returned in the "count" attribute of the result (optional). /// Calculating the "count" attribute might in the future have a performance /// impact for some queries so this option is turned off by default, and "count" /// is only returned when requested. /// -/// - `batchSize`: maximum number of result documents to be transferred from +/// - *batchSize*: maximum number of result documents to be transferred from /// the server to the client in one roundtrip (optional). If this attribute is /// not set, a server-controlled default value will be used. /// -/// - `bindVars`: key/value list of bind parameters (optional). +/// - *bindVars*: key/value list of bind parameters (optional). /// -/// - `options`: key/value list of extra options for the query (optional). +/// - *options*: key/value list of extra options for the query (optional). /// /// The following options are supported at the moment: /// -/// - `fullCount`: if set to `true` and the query contains a `LIMIT` clause, then the -/// result will contain an extra attribute `extra` with a sub-attribute `fullCount`. +/// - *fullCount*: if set to *true* and the query contains a *LIMIT* clause, then the +/// result will contain an extra attribute *extra* with a sub-attribute *fullCount*. /// This sub-attribute will contain the number of documents in the result before the /// last LIMIT in the query was applied. It can be used to count the number of documents that /// match certain filter criteria, but only return a subset of them, in one go. -/// It is thus similar to MySQL's `SQL_CALC_FOUND_ROWS` hint. Note that setting the option -/// will disable a few LIMIT optimisations and may lead to more documents being processed, -/// and thus make queries run longer. Note that the `fullCount` sub-attribute will only +/// It is thus similar to MySQL's *SQL_CALC_FOUND_ROWS* hint. Note that setting the option +/// will disable a few LIMIT optimizations and may lead to more documents being processed, +/// and thus make queries run longer. Note that the *fullCount* sub-attribute will only /// be present in the result if the query has a LIMIT clause and the LIMIT clause is /// actually used in the query. /// /// If the result set can be created by the server, the server will respond with -/// `HTTP 201`. The body of the response will contain a JSON object with the +/// *HTTP 201*. The body of the response will contain a JSON object with the /// result set. /// /// The returned JSON object has the following properties: /// -/// - `error`: boolean flag to indicate that an error occurred (`false` +/// - *error*: boolean flag to indicate that an error occurred (*false* /// in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// -/// - `result`: an array of result documents (might be empty if query has no results) +/// - *result*: an array of result documents (might be empty if query has no results) /// -/// - `hasMore`: a boolean indicator whether there are more results +/// - *hasMore*: a boolean indicator whether there are more results /// available for the cursor on the server /// -/// - `count`: the total number of result documents available (only -/// available if the query was executed with the `count` attribute set) +/// - *count*: the total number of result documents available (only +/// available if the query was executed with the *count* attribute set) /// -/// - `id`: id of temporary cursor created on the server (optional, see above) +/// - *id*: id of temporary cursor created on the server (optional, see above) /// -/// - `extra`: an optional JSON object with extra information about the query result +/// - *extra*: an optional JSON object with extra information about the query result /// /// If the JSON representation is malformed or the query specification is -/// missing from the request, the server will respond with `HTTP 400`. +/// missing from the request, the server will respond with *HTTP 400*. /// /// The body of the response will contain a JSON object with additional error /// details. The object has the following attributes: /// -/// - `error`: boolean flag to indicate that an error occurred (`true` in this case) +/// - *error*: boolean flag to indicate that an error occurred (*true* in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// -/// - `errorNum`: the server error number +/// - *errorNum*: the server error number /// -/// - `errorMessage`: a descriptive error message +/// - *errorMessage*: a descriptive error message /// /// If the query specification is complete, the server will process the query. If an -/// error occurs during query processing, the server will respond with `HTTP 400`. +/// error occurs during query processing, the server will respond with *HTTP 400*. /// Again, the body of the response will contain details about the error. /// /// A list of query errors can be found @ref ArangoErrors here. @@ -143,13 +144,13 @@ var internal = require("internal"); /// missing from the request. /// /// @RESTRETURNCODE{404} -/// The server will respond with `HTTP 404` in case a non-existing collection is +/// The server will respond with *HTTP 404* in case a non-existing collection is /// accessed in the query. /// /// @RESTRETURNCODE{405} -/// The server will respond with `HTTP 405` if an unsupported HTTP method is used. +/// The server will respond with *HTTP 405* if an unsupported HTTP method is used. /// -/// *Examples* +/// @EXAMPLES /// /// Executes a query and extract the result in a single go: /// @@ -251,6 +252,7 @@ var internal = require("internal"); /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_cursor(req, res) { @@ -299,9 +301,10 @@ function post_api_cursor(req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_cursor_identifier /// @brief return the next results from an existing cursor /// -/// @RESTHEADER{PUT /_api/cursor/`cursor-identifier`,reads next batch from a cursor} +/// @RESTHEADER{PUT /_api/cursor/cursor-identifier, Read next batch from cursor} /// /// @RESTURLPARAMETERS /// @@ -313,29 +316,29 @@ function post_api_cursor(req, res) { /// If the cursor is still alive, returns an object with the following /// attributes. /// -/// - `id`: the `cursor-identifier` -/// - `result`: a list of documents for the current batch -/// - `hasMore`: `false` if this was the last batch -/// - `count`: if present the total number of elements +/// - *id*: the *cursor-identifier* +/// - *result*: a list of documents for the current batch +/// - *hasMore*: *false* if this was the last batch +/// - *count*: if present the total number of elements /// -/// Note that even if `hasMore` returns `true`, the next call might -/// still return no documents. If, however, `hasMore` is `false`, then -/// the cursor is exhausted. Once the `hasMore` attribute has a value of -/// `false`, the client can stop. +/// Note that even if *hasMore* returns *true*, the next call might +/// still return no documents. If, however, *hasMore* is *false*, then +/// the cursor is exhausted. Once the *hasMore* attribute has a value of +/// *false*, the client can stop. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// The server will respond with `HTTP 200` in case of success. +/// The server will respond with *HTTP 200* in case of success. /// /// @RESTRETURNCODE{400} -/// If the cursor identifier is ommitted, the server will respond with `HTTP 404`. +/// If the cursor identifier is omitted, the server will respond with *HTTP 404*. /// /// @RESTRETURNCODE{404} /// If no cursor with the specified identifier can be found, the server will respond -/// with `HTTP 404`. +/// with *HTTP 404*. /// -/// *Examples* +/// @EXAMPLES /// /// Valid request for next batch: /// @@ -390,6 +393,7 @@ function post_api_cursor(req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function put_api_cursor (req, res) { @@ -419,9 +423,10 @@ function put_api_cursor (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_cursor_delete /// @brief dispose an existing cursor /// -/// @RESTHEADER{DELETE /_api/cursor/`cursor-identifier`,deletes a cursor} +/// @RESTHEADER{DELETE /_api/cursor/cursor-identifier, Delete cursor} /// /// @RESTURLPARAMETERS /// @@ -448,7 +453,7 @@ function put_api_cursor (req, res) { /// is returned if the server is not aware of the cursor. It is also /// returned if a cursor is used after it has been destroyed. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestCursorDelete} /// var url = "/_api/cursor"; @@ -476,6 +481,7 @@ function put_api_cursor (req, res) { /// /// assert(response.code === 202); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function delete_api_cursor(req, res) { diff --git a/js/actions/api-database.js b/js/actions/api-database.js index ef53a86b5b..7232954623 100644 --- a/js/actions/api-database.js +++ b/js/actions/api-database.js @@ -44,15 +44,15 @@ var API = "_api/database"; //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_get_api_database_list +/// @startDocuBlock JSF_get_api_database_list /// @brief retrieves a list of all existing databases /// -/// @RESTHEADER{GET /_api/database,retrieves a list of all existing databases} +/// @RESTHEADER{GET /_api/database, List of databases} /// /// @RESTDESCRIPTION /// Retrieves the list of all existing databases /// -/// Note: retrieving the list of databases is only possible from within the `_system` database. +/// **Note**: retrieving the list of databases is only possible from within the *_system* database. /// /// @RESTRETURNCODES /// @@ -63,9 +63,9 @@ var API = "_api/database"; /// is returned if the request is invalid. /// /// @RESTRETURNCODE{403} -/// is returned if the request was not executed in the `_system` database. +/// is returned if the request was not executed in the *_system* database. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestDatabaseGet} /// var url = "/_api/database"; @@ -75,13 +75,14 @@ var API = "_api/database"; /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_get_api_database_user +/// @startDocuBlock JSF_get_api_database_user /// @brief retrieves a list of all databases the current user can access /// -/// @RESTHEADER{GET /_api/database/user,retrieves a list of all databases the current user can access} +/// @RESTHEADER{GET /_api/database/user, List of accessible databases } /// /// @RESTDESCRIPTION /// Retrieves the list of all databases the current user can access without @@ -95,7 +96,7 @@ var API = "_api/database"; /// @RESTRETURNCODE{400} /// is returned if the request is invalid. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestDatabaseGetUser} /// var url = "/_api/database/user"; @@ -105,26 +106,27 @@ var API = "_api/database"; /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_get_api_database_current +/// @startDocuBlock JSF_get_api_database_current /// @brief retrieves information about the current database /// -/// @RESTHEADER{GET /_api/database/current,retrieves information about the current database} +/// @RESTHEADER{GET /_api/database/current, Information of the database} /// /// @RESTDESCRIPTION /// Retrieves information about the current database /// /// The response is a JSON object with the following attributes: /// -/// - `name`: the name of the current database +/// - *name*: the name of the current database /// -/// - `id`: the id of the current database +/// - *id*: the id of the current database /// -/// - `path`: the filesystem path of the current database +/// - *path*: the filesystem path of the current database /// -/// - `isSystem`: whether or not the current database is the `_system` database +/// - *isSystem*: whether or not the current database is the *_system* database /// /// @RESTRETURNCODES /// @@ -137,7 +139,7 @@ var API = "_api/database"; /// @RESTRETURNCODE{404} /// is returned if the database could not be found. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestDatabaseGetInfo} /// var url = "/_api/database/current"; @@ -147,6 +149,7 @@ var API = "_api/database"; /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function get_api_database (req, res) { @@ -211,9 +214,10 @@ function get_api_database (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_database_new /// @brief creates a new database /// -/// @RESTHEADER{POST /_api/database,creates a new database} +/// @RESTHEADER{POST /_api/database, Create database} /// /// @RESTBODYPARAM{body,json,required} /// the body with the name of the database. @@ -221,32 +225,32 @@ function get_api_database (req, res) { /// @RESTDESCRIPTION /// Creates a new database /// -/// The request body must be a JSON object with the attribute `name`. `name` must +/// The request body must be a JSON object with the attribute *name*. *name* must /// contain a valid @ref DatabaseNames "database name". /// -/// The request body can optionally contain an attribute `users`, which then +/// The request body can optionally contain an attribute *users*, which then /// must be a list of user objects to initially create for the new database. /// Each user object can contain the following attributes: /// -/// - `username`: the user name as a string. This attribute is mandatory. +/// - *username*: the user name as a string. This attribute is mandatory. /// -/// - `passwd`: the user password as a string. If not specified, then it defaults +/// - *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 accout should be -/// actived or not. The default value is `true`. +/// - *active*: a boolean flag indicating whether the user accout should be +/// actived 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 +/// - *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 `users` is not specified or does not contain any users, a default user -/// `root` will be created with an empty string password. This ensures that the +/// If *users* is not specified or does not contain any users, a default user +/// *root* will be created with an empty string password. This ensures that the /// new database will be accessible after it is created. /// -/// The response is a JSON object with the attribute `result` set to `true`. +/// The response is a JSON object with the attribute *result* set to *true*. /// -/// Note: creating a new database is only possible from within the `_system` database. +/// **Note**: creating a new database is only possible from within the *_system* database. /// /// @RESTRETURNCODES /// @@ -258,14 +262,14 @@ function get_api_database (req, res) { /// specified name already exists. /// /// @RESTRETURNCODE{403} -/// is returned if the request was not executed in the `_system` database. +/// is returned if the request was not executed in the *_system* database. /// /// @RESTRETURNCODE{409} /// is returned if a database with the specified name already exists. /// -/// *Examples* +/// @EXAMPLES /// -/// Creating a database named `example`. +/// Creating a database named *example*. /// /// @EXAMPLE_ARANGOSH_RUN{RestDatabaseCreate} /// var url = "/_api/database"; @@ -287,7 +291,7 @@ function get_api_database (req, res) { /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN /// -/// Creating a database named `mydb` with two users. +/// Creating a database named *mydb* with two users. /// /// @EXAMPLE_ARANGOSH_RUN{RestDatabaseCreateUsers} /// var url = "/_api/database"; @@ -320,6 +324,7 @@ function get_api_database (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_database (req, res) { @@ -389,9 +394,10 @@ function post_api_database (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_database_delete /// @brief drop an existing database /// -/// @RESTHEADER{DELETE /_api/database/`database-name`,drops an existing database} +/// @RESTHEADER{DELETE /_api/database/database-name, Drop database} /// /// @RESTURLPARAMETERS /// @@ -401,8 +407,8 @@ function post_api_database (req, res) { /// @RESTDESCRIPTION /// Deletes the database along with all data stored in it. /// -/// Note: dropping a database is only possible from within the `_system` database. -/// The `_system` database itself cannot be dropped. +/// **Note**: dropping a database is only possible from within the *_system* database. +/// The *_system* database itself cannot be dropped. /// /// @RESTRETURNCODES /// @@ -413,12 +419,12 @@ function post_api_database (req, res) { /// is returned if the request is malformed. /// /// @RESTRETURNCODE{403} -/// is returned if the request was not executed in the `_system` database. +/// is returned if the request was not executed in the *_system* database. /// /// @RESTRETURNCODE{404} /// is returned if the database could not be found. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestDatabaseDrop} /// var url = "/_api/database"; @@ -431,6 +437,7 @@ function post_api_database (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function delete_api_database (req, res) { diff --git a/js/actions/api-edges.js b/js/actions/api-edges.js index 6050d73745..e2d14662c1 100644 --- a/js/actions/api-edges.js +++ b/js/actions/api-edges.js @@ -39,9 +39,10 @@ var API = "/_api/edges"; //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock API_EDGE_READINOUTBOUND /// @brief get edges /// -/// @RESTHEADER{GET /_api/edges/{collection-id},reads in- or outbound edges} +/// @RESTHEADER{GET /_api/edges/collection-id, Read in- or outbound edges} /// /// @RESTURLPARAMETERS /// @@ -54,14 +55,14 @@ var API = "/_api/edges"; /// The id of the start vertex. /// /// @RESTQUERYPARAM{direction,string,optional} -/// Selects `in` or `out` direction for edges. If not set, any edges are +/// Selects *in* or *out* direction for edges. If not set, any edges are /// returned. /// /// @RESTDESCRIPTION /// Returns the list of edges starting or ending in the vertex identified by -/// `vertex-handle`. +/// *vertex-handle*. /// -/// *Examples* +/// @EXAMPLES /// /// Any direction /// @@ -134,6 +135,7 @@ var API = "/_api/edges"; /// db._drop("vertices"); /// db._graphs.remove("graph"); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function get_edges (req, res) { diff --git a/js/actions/api-explain.js b/js/actions/api-explain.js index 9c5444a016..5fc15fd28c 100644 --- a/js/actions/api-explain.js +++ b/js/actions/api-explain.js @@ -43,14 +43,15 @@ var EXPLAIN = require("internal").AQL_EXPLAIN; //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_explain /// @brief explain a query and return information about it /// -/// @RESTHEADER{POST /_api/explain,explains a query} +/// @RESTHEADER{POST /_api/explain, Explain query} /// /// @RESTBODYPARAM{body,json,required} -/// The query string needs to be passed in the attribute `query` of a JSON +/// The query string needs to be passed in the attribute *query* of a JSON /// object as the body of the POST request. If the query references any bind -/// variables, these must also be passed in the attribute `bindVars`. +/// variables, these must also be passed in the attribute *bindVars*. /// /// @RESTDESCRIPTION /// @@ -66,28 +67,28 @@ var EXPLAIN = require("internal").AQL_EXPLAIN; /// The top-level statements will appear in the result in the same order in which /// they have been used in the original query. Each result element has at most the /// following attributes: -/// - `id`: the row number of the top-level statement, starting at 1 -/// - `type`: the type of the top-level statement (e.g. `for`, `return` ...) -/// - `loopLevel`: the nesting level of the top-level statement, starting at 1 +/// - *id*: the row number of the top-level statement, starting at 1 +/// - *type*: the type of the top-level statement (e.g. *for*, *return* ...) +/// - *loopLevel*: the nesting level of the top-level statement, starting at 1 /// Depending on the type of top-level statement, there might be other attributes /// providing additional information, for example, if and which indexed will be /// used. -/// Many top-level statements will provide an `expression` attribute that -/// contains data about the expression they operate on. This is true for `FOR`, -/// `FILTER`, `SORT`, `COLLECT`, and `RETURN` statements. The -/// `expression` attribute has the following sub-attributes: -/// - `type`: the type of the expression. Some possible values are: -/// - `collection`: an iteration over documents from a collection. The -/// `value` attribute will then contain the collection name. The `extra` +/// Many top-level statements will provide an *expression* attribute that +/// contains data about the expression they operate on. This is true for *FOR*, +/// *FILTER*, *SORT*, *COLLECT*, and *RETURN* statements. The +/// *expression* attribute has the following sub-attributes: +/// - *type*: the type of the expression. Some possible values are: +/// - *collection*: an iteration over documents from a collection. The +/// *value* attribute will then contain the collection name. The *extra* /// attribute will contain information about if and which index is used when /// accessing the documents from the collection. If no index is used, the -/// `accessType` sub-attribute of the `extra` attribute will have the -/// value `all`, otherwise it will be `index`. -/// - `list`: a list of dynamic values. The `value` attribute will contain the +/// *accessType* sub-attribute of the *extra* attribute will have the +/// value *all*, otherwise it will be *index*. +/// - *list*: a list of dynamic values. The *value* attribute will contain the /// list elements. -/// - `const list`: a list of constant values. The `value` attribute will contain the +/// - *const list*: a list of constant values. The *value* attribute will contain the /// list elements. -/// - `reference`: a reference to another variable. The `value` attribute +/// - *reference*: a reference to another variable. The *value* attribute /// will contain the name of the variable that is referenced. /// /// Please note that the structure of the explain result data might change in future @@ -97,22 +98,22 @@ var EXPLAIN = require("internal").AQL_EXPLAIN; /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the query is valid, the server will respond with `HTTP 200` and -/// return a list of the individual query execution steps in the `"plan"` +/// If the query is valid, the server will respond with *HTTP 200* and +/// return a list of the individual query execution steps in the *"plan"* /// attribute of the response. /// /// @RESTRETURNCODE{400} -/// The server will respond with `HTTP 400` in case of a malformed request, +/// The server will respond with *HTTP 400* in case of a malformed request, /// or if the query contains a parse error. The body of the response will /// contain the error details embedded in a JSON object. /// Omitting bind variables if the query references any will result also result -/// in an `HTTP 400` error. +/// in an *HTTP 400* error. /// /// @RESTRETURNCODE{404} -/// The server will respond with `HTTP 404` in case a non-existing collection is +/// The server will respond with *HTTP 404* in case a non-existing collection is /// accessed in the query. /// -/// *Examples* +/// @EXAMPLES /// /// Valid query: /// @@ -149,9 +150,9 @@ var EXPLAIN = require("internal").AQL_EXPLAIN; /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN /// -/// The data returned in the `plan` attribute of the result contains one -/// element per AQL top-level statement (i.e. `FOR`, `RETURN`, -/// `FILTER` etc.). If the query optimiser removed some unnecessary statements, +/// The data returned in the *plan* attribute of the result contains one +/// element per AQL top-level statement (i.e. *FOR*, *RETURN*, +/// *FILTER* etc.). If the query optimiser removed some unnecessary statements, /// the result might also contain less elements than there were top-level /// statements in the AQL query. /// The following example shows a query with a non-sensible filter condition that @@ -170,6 +171,7 @@ var EXPLAIN = require("internal").AQL_EXPLAIN; /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_explain (req, res) { diff --git a/js/actions/api-index.js b/js/actions/api-index.js index 50fa44d9c3..902b9bb635 100644 --- a/js/actions/api-index.js +++ b/js/actions/api-index.js @@ -43,9 +43,10 @@ var API = "_api/index"; //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_index /// @brief returns all indexes of a collection /// -/// @RESTHEADER{GET /_api/index,reads all indexes of a collection} +/// @RESTHEADER{GET /_api/index, Read all indexes of a collection} /// /// @RESTQUERYPARAMETERS /// @@ -54,12 +55,12 @@ var API = "_api/index"; /// /// @RESTDESCRIPTION /// -/// Returns an object with an attribute `indexes` containing a list of all +/// Returns an object with an attribute *indexes* containing a list of all /// index descriptions for the given collection. The same information is also -/// available in the `identifiers` as hash map with the index handle as +/// available in the *identifiers* as hash map with the index handle as /// keys. /// -/// *Examples* +/// @EXAMPLES /// /// Return information about all indexes: /// @@ -76,6 +77,7 @@ var API = "_api/index"; /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function get_api_indexes (req, res) { @@ -102,9 +104,10 @@ function get_api_indexes (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_get_api_reads_index /// @brief returns an index /// -/// @RESTHEADER{GET /_api/index/{index-handle},reads an index} +/// @RESTHEADER{GET /_api/index/{index-handle},Read index} /// /// @RESTURLPARAMETERS /// @@ -116,21 +119,21 @@ function get_api_indexes (req, res) { /// The result is an objects describing the index. It has at least the following /// attributes: /// -/// - `id`: The identifier of the index. +/// - *id*: The identifier of the index. /// /// All other attributes are type-dependent. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index exists, then a `HTTP 200` is +/// If the index exists, then a *HTTP 200* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the index does not exist, then a `HTTP 404` +/// If the index does not exist, then a *HTTP 404* /// is returned. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestIndexPrimaryIndex} /// var cn = "products"; @@ -144,6 +147,7 @@ function get_api_indexes (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function get_api_index (req, res) { @@ -193,10 +197,10 @@ function get_api_index (req, res) { } //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_post_api_index_cap +/// @startDocuBlock JSF_post_api_index_cap /// @brief creates a cap constraint /// -/// @RESTHEADER{POST /_api/index,creates a cap constraint} +/// @RESTHEADER{POST /_api/index, Create cap constraint} /// /// @RESTQUERYPARAMETERS /// @@ -207,44 +211,44 @@ function get_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Creates a cap constraint for the collection `collection-name`, +/// Creates a cap constraint for the collection *collection-name*, /// if it does not already exist. Expects an object containing the index details. /// -/// - `type`: must be equal to `"cap"`. +/// - *type*: must be equal to *"cap"*. /// -/// - `size`: The maximal number of documents for the collection. If specified, +/// - *size*: The maximal number of documents for the collection. If specified, /// the value must be greater than zero. /// -/// - `byteSize`: The maximal size of the active document data in the collection +/// - *byteSize*: The maximal size of the active document data in the collection /// (in bytes). If specified, the value must be at least 16384. /// -/// Note that the cap constraint does not index particular attributes of the +/// **Note**: The cap constraint does not index particular attributes of the /// documents in a collection, but limits the number of documents in the /// collection to a maximum value. The cap constraint thus does not support -/// attribute names specified in the `fields` attribute nor uniqueness of -/// any kind via the `unique` attribute. +/// attribute names specified in the *fields* attribute nor uniqueness of +/// any kind via the *unique* attribute. /// -/// It is allowed to specify either `size` or `byteSize`, or both at +/// 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. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index already exists, then an `HTTP 200` is returned. +/// If the index already exists, then an *HTTP 200* is returned. /// /// @RESTRETURNCODE{201} -/// If the index does not already exist and could be created, then an `HTTP 201` +/// If the index does not already exist and could be created, then an *HTTP 201* /// is returned. /// /// @RESTRETURNCODE{400} -/// If either `size` or `byteSize` contain invalid values, then an `HTTP 400` +/// If either *size* or *byteSize* contain invalid values, then an *HTTP 400* /// is returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Creating a cap constraint /// @@ -265,13 +269,14 @@ function get_api_index (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_post_api_index_geo +/// @startDocuBlock JSF_post_api_index_geo /// @brief creates a geo index /// -/// @RESTHEADER{POST /_api/index,creates a geo-spatial index} +/// @RESTHEADER{POST /_api/index, Create geo-spatial index} /// /// @RESTQUERYPARAMETERS /// @@ -282,57 +287,57 @@ function get_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Creates a geo-spatial index in the collection `collection-name`, if +/// Creates a geo-spatial index in the collection *collection-name*, if /// it does not already exist. Expects an object containing the index details. /// -/// - `type`: must be equal to `"geo"`. +/// - *type*: must be equal to *"geo"*. /// -/// - `fields`: A list with one or two attribute paths. +/// - *fields*: A list with one or two attribute paths. /// -/// If it is a list with one attribute path `location`, then a geo-spatial -/// index on all documents is created using `location` as path to the +/// If it is a list with one attribute path *location*, then a geo-spatial +/// index on all documents is created using *location* as path to the /// coordinates. The value of the attribute must be a list with at least two /// double values. The list must contain the latitude (first value) and the /// longitude (second value). All documents, which do not have the attribute /// path or with value that are not suitable, are ignored. /// -/// If it is a list with two attribute paths `latitude` and `longitude`, -/// then a geo-spatial index on all documents is created using `latitude` -/// and `longitude` as paths the latitude and the longitude. The value of -/// the attribute `latitude` and of the attribute `longitude` must a +/// If it is a list with two attribute paths *latitude* and *longitude*, +/// then a geo-spatial index on all documents is created using *latitude* +/// and *longitude* as paths the latitude and the longitude. The value of +/// the attribute *latitude* and of the attribute *longitude* must a /// double. All documents, which do not have the attribute paths or which /// values are not suitable, are ignored. /// -/// - `geoJson`: If a geo-spatial index on a `location` is constructed -/// and `geoJson` is `true`, then the order within the list is longitude +/// - *geoJson*: If a geo-spatial index on a *location* is constructed +/// and *geoJson* is *true*, then the order within the list is longitude /// followed by latitude. This corresponds to the format described in /// http://geojson.org/geojson-spec.html#positions /// -/// - `constraint`: If `constraint` is `true`, then a geo-spatial +/// - *constraint*: If *constraint* is *true*, then a geo-spatial /// constraint is created. The constraint is a non-unique variant of the index. -/// Note that it is also possible to set the `unique` attribute instead of -/// the `constraint` attribute. +/// **Note**: It is also possible to set the *unique* attribute instead of +/// the *constraint* attribute. /// -/// - `ignoreNull`: If a geo-spatial constraint is created and -/// `ignoreNull` is true, then documents with a null in `location` or at -/// least one null in `latitude` or `longitude` are ignored. +/// - *ignoreNull*: If a geo-spatial constraint is created and +/// *ignoreNull* is true, then documents with a null in *location* or at +/// least one null in *latitude* or *longitude* are ignored. /// -/// Note: unique indexes on non-shard keys are not supported in a cluster. +/// **Note**: Unique indexes on non-shard keys are not supported in a cluster. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index already exists, then a `HTTP 200` is +/// If the index already exists, then a *HTTP 200* is /// returned. /// /// @RESTRETURNCODE{201} -/// If the index does not already exist and could be created, then a `HTTP 201` +/// If the index does not already exist and could be created, then a *HTTP 201* /// is returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Creating a geo index with a location attribute: /// @@ -367,13 +372,14 @@ function get_api_index (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_post_api_index_hash +/// @startDocuBlock JSF_post_api_index_hash /// @brief creates a hash index /// -/// @RESTHEADER{POST /_api/index,creates a hash index} +/// @RESTHEADER{POST /_api/index, Create hash index} /// /// @RESTQUERYPARAMETERS /// @@ -384,37 +390,37 @@ function get_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Creates a hash index for the collection `collection-name`, if it +/// Creates a hash index for the collection *collection-name*, if it /// does not already exist. The call expects an object containing the index /// details. /// -/// - `type`: must be equal to `"hash"`. +/// - *type*: must be equal to *"hash"*. /// -/// - `fields`: A list of attribute paths. +/// - *fields*: A list of attribute paths. /// -/// - `unique`: If `true`, then create a unique index. +/// - *unique*: If *true*, then create a unique index. /// -/// Note: unique indexes on non-shard keys are not supported in a cluster. +/// **Note**: unique indexes on non-shard keys are not supported in a cluster. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index already exists, then a `HTTP 200` is +/// If the index already exists, then a *HTTP 200* is /// returned. /// /// @RESTRETURNCODE{201} -/// If the index does not already exist and could be created, then a `HTTP 201` +/// If the index does not already exist and could be created, then a *HTTP 201* /// is returned. /// /// @RESTRETURNCODE{400} /// If the collection already contains documents and you try to create a unique /// hash index in such a way that there are documents violating the uniqueness, -/// then a `HTTP 400` is returned. +/// then a *HTTP 400* is returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Creating an unique constraint: /// @@ -449,13 +455,14 @@ function get_api_index (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_post_api_index_skiplist +/// @startDocuBlock JSF_post_api_index_skiplist /// @brief creates a skip-list /// -/// @RESTHEADER{POST /_api/index,creates a skip list} +/// @RESTHEADER{POST /_api/index, Create skip list} /// /// @RESTQUERYPARAMETERS /// @@ -466,37 +473,37 @@ function get_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Creates a skip-list index for the collection `collection-name`, if +/// Creates a skip-list index for the collection *collection-name*, if /// it does not already exist. The call expects an object containing the index /// details. /// -/// - `type`: must be equal to `"skiplist"`. +/// - *type*: must be equal to *"skiplist"*. /// -/// - `fields`: A list of attribute paths. +/// - *fields*: A list of attribute paths. /// -/// - `unique`: If `true`, then create a unique index. +/// - *unique*: If *true*, then create a unique index. /// -/// Note: unique indexes on non-shard keys are not supported in a cluster. +/// **Note**: unique indexes on non-shard keys are not supported in a cluster. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index already exists, then a `HTTP 200` is +/// If the index already exists, then a *HTTP 200* is /// returned. /// /// @RESTRETURNCODE{201} -/// If the index does not already exist and could be created, then a `HTTP 201` +/// If the index does not already exist and could be created, then a *HTTP 201* /// is returned. /// /// @RESTRETURNCODE{400} /// If the collection already contains documents and you try to create a unique /// skip-list index in such a way that there are documents violating the -/// uniqueness, then a `HTTP 400` is returned. +/// uniqueness, then a *HTTP 400* is returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Creating a skiplist: /// @@ -514,13 +521,14 @@ function get_api_index (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_post_api_index_fulltext +/// @startDocuBlock JSF_post_api_index_fulltext /// @brief creates a fulltext index /// -/// @RESTHEADER{POST /_api/index,creates a fulltext index} +/// @RESTHEADER{POST /_api/index, Create fulltext index} /// /// @RESTQUERYPARAMETERS /// @@ -531,34 +539,34 @@ function get_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Creates a fulltext index for the collection `collection-name`, if +/// Creates a fulltext index for the collection *collection-name*, if /// it does not already exist. The call expects an object containing the index /// details. /// -/// - `type`: must be equal to `"fulltext"`. +/// - *type*: must be equal to *"fulltext"*. /// -/// - `fields`: A list of attribute names. Currently, the list is limited -/// to exactly one attribute, so the value of `fields` should look like -/// this for example: `[ "text" ]`. +/// - *fields*: A list of attribute names. Currently, the list is limited +/// to exactly one attribute, so the value of *fields* should look like +/// this for example: *[ "text" ]*. /// -/// - `minLength`: Minimum character length of words to index. Will default +/// - *minLength*: Minimum character length of words to index. Will default /// to a server-defined value if unspecified. It is thus recommended to set /// this value explicitly when creating the index. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index already exists, then a `HTTP 200` is +/// If the index already exists, then a *HTTP 200* is /// returned. /// /// @RESTRETURNCODE{201} -/// If the index does not already exist and could be created, then a `HTTP 201` +/// If the index does not already exist and could be created, then a *HTTP 201* /// is returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Creating a fulltext index: /// @@ -576,13 +584,14 @@ function get_api_index (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSF_post_api_index_bitarray +/// @startDocuBlock JSF_post_api_index_bitarray /// @brief creates a bitarray /// -/// @RESTHEADER{POST /_api/index,creates a bitarray index} +/// @RESTHEADER{POST /_api/index, Create bitarray index} /// /// @RESTQUERYPARAMETERS /// @@ -593,30 +602,30 @@ function get_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Creates a bitarray index for the collection `collection-name`, if +/// Creates a bitarray index for the collection *collection-name*, if /// it does not already exist. The call expects an object containing the index /// details. /// -/// - `type`: must be equal to `"bitarray"`. +/// - *type*: must be equal to *"bitarray"*. /// -/// - `fields`: A list of pairs. A pair consists of an attribute path followed by a list of values. +/// - *fields*: A list of pairs. A pair consists of an attribute path followed by a list of values. /// -/// - `unique`: Must always be set to `false`. +/// - *unique*: Must always be set to *false*. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index already exists, then a `HTTP 200` is +/// If the index already exists, then a *HTTP 200* is /// returned. /// /// @RESTRETURNCODE{201} -/// If the index does not already exist and could be created, then a `HTTP 201` +/// If the index does not already exist and could be created, then a *HTTP 201* /// is returned. /// /// @RESTRETURNCODE{404} -/// If the `collection-name` is unknown, then a `HTTP 404` is returned. +/// If the *collection-name* is unknown, then a *HTTP 404* is returned. /// -/// *Examples* +/// @EXAMPLES /// /// Creating a bitarray index: /// @@ -638,12 +647,14 @@ function get_api_index (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_index /// @brief creates an index /// -/// @RESTHEADER{POST /_api/index,creates an index} +/// @RESTHEADER{POST /_api/index, Create index} /// /// @RESTQUERYPARAMETERS /// @@ -654,56 +665,54 @@ function get_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Creates a new index in the collection `collection`. Expects +/// Creates a new index in the collection *collection*. Expects /// an object containing the index details. /// -/// The type of the index to be created must specified in the `type` +/// The type of the index to be created must specified in the *type* /// attribute of the index details. Depending on the index type, additional /// other attributes may need to specified in the request in order to create /// the index. /// -/// See @ref HttpIndexCap, @ref HttpIndexGeo, @ref HttpIndexHash, -/// @ref HttpIndexFulltext, and @ref HttpIndexSkiplist for details. -/// /// Most indexes (a notable exception being the cap constraint) require the -/// list of attributes to be indexed in the `fields` attribute of the index +/// list of attributes to be indexed in the *fields* attribute of the index /// details. Depending on the index type, a single attribute or multiple /// attributes may be indexed. /// -/// Indexing system attributes such as `_id`, `_key`, `_from`, and `_to` +/// Indexing system attributes such as *_id*, *_key*, *_from*, and *_to* /// is not supported by any index type. Manually creating an index that /// relies on any of these attributes is unsupported. /// /// Some indexes can be created as unique or non-unique variants. Uniqueness -/// can be controlled for most indexes by specifying the `unique` in the -/// index details. Setting it to `true` will create a unique index. -/// Setting it to `false` or omitting the `unique` attribute will +/// can be controlled for most indexes by specifying the *unique* in the +/// index details. Setting it to *true* will create a unique index. +/// Setting it to *false* or omitting the *unique* attribute will /// create a non-unique index. /// -/// Note that the following index types do not support uniqueness, and using -/// the `unique` attribute with these types may lead to an error: +/// **Note**: The following index types do not support uniqueness, and using +/// the *unique* attribute with these types may lead to an error: /// - cap constraints /// - fulltext indexes /// - bitarray indexes /// -/// Note also that unique indexes on non-shard keys are not supported in a +/// **Note**: Unique indexes on non-shard keys are not supported in a /// cluster. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index already exists, then an `HTTP 200` is returned. +/// If the index already exists, then an *HTTP 200* is returned. /// /// @RESTRETURNCODE{201} -/// If the index does not already exist and could be created, then an `HTTP 201` +/// If the index does not already exist and could be created, then an *HTTP 201* /// is returned. /// /// @RESTRETURNCODE{400} /// If an invalid index description is posted or attributes are used that the -/// target index will not support, then an `HTTP 400` is returned. +/// target index will not support, then an *HTTP 400* is returned. /// /// @RESTRETURNCODE{404} -/// If `collection` is unknown, then an `HTTP 404` is returned. +/// If *collection* is unknown, then an *HTTP 404* is returned. +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_index (req, res) { @@ -764,9 +773,10 @@ function post_api_index (req, res) { } //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_index_delete /// @brief deletes an index /// -/// @RESTHEADER{DELETE /_api/index/{index-handle},deletes an index} +/// @RESTHEADER{DELETE /_api/index/{index-handle}, Delete index} /// /// @RESTQUERYPARAMETERS /// @@ -775,17 +785,17 @@ function post_api_index (req, res) { /// /// @RESTDESCRIPTION /// -/// Deletes an index with `index-handle`. +/// Deletes an index with *index-handle*. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the index could be deleted, then an `HTTP 200` is +/// If the index could be deleted, then an *HTTP 200* is /// returned. /// /// @RESTRETURNCODE{404} -/// If the `index-handle` is unknown, then an `HTTP 404` is returned. -/// *Examples* +/// If the *index-handle* is unknown, then an *HTTP 404* is returned. +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestIndexDeleteUniqueSkiplist} /// var cn = "products"; @@ -800,6 +810,7 @@ function post_api_index (req, res) { /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function delete_api_index (req, res) { diff --git a/js/actions/api-query.js b/js/actions/api-query.js index 1f644f30cb..600299a481 100644 --- a/js/actions/api-query.js +++ b/js/actions/api-query.js @@ -44,33 +44,31 @@ var PARSE = require("internal").AQL_PARSE; //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_query /// @brief parse a query and return information about it /// -/// @RESTHEADER{POST /_api/query,parses a query} +/// @RESTHEADER{POST /_api/query, Parse query} /// /// @RESTBODYPARAM{query,json,required} -/// -/// @RESTDESCRIPTION -/// /// To validate a query string without executing it, the query string can be /// passed to the server via an HTTP POST request. /// -/// These query string needs to be passed in the attribute `query` of a JSON +/// These query string needs to be passed in the attribute *query* of a JSON /// object as the body of the POST request. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// If the query is valid, the server will respond with `HTTP 200` and +/// If the query is valid, the server will respond with *HTTP 200* and /// return the names of the bind parameters it found in the query (if any) in -/// the `"bindVars"` attribute of the response. +/// the *"bindVars"* attribute of the response. /// /// @RESTRETURNCODE{400} -/// The server will respond with `HTTP 400` in case of a malformed request, +/// The server will respond with *HTTP 400* in case of a malformed request, /// or if the query contains a parse error. The body of the response will /// contain the error details embedded in a JSON object. /// -/// *Examples* +/// @EXAMPLES /// /// Valid query: /// @@ -97,6 +95,7 @@ var PARSE = require("internal").AQL_PARSE; /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_query (req, res) { diff --git a/js/actions/api-simple.js b/js/actions/api-simple.js index a980b61568..1ea92aca48 100644 --- a/js/actions/api-simple.js +++ b/js/actions/api-simple.js @@ -44,11 +44,11 @@ var API = "_api/simple/"; // ----------------------------------------------------------------------------- //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_by_example_hash +/// @startDocuBlock JSA_put_api_simple_by_example_hash /// @brief returns all documents of a collection matching a given example, /// using a specific hash index /// -/// @RESTHEADER{PUT /_api/simple/by-example-hash,executes query by-example using a hash index} +/// @RESTHEADER{PUT /_api/simple/by-example-hash, Hash index} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query specification. @@ -60,19 +60,19 @@ var API = "_api/simple/"; /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `index`: The id of the index to be used for the query. The index must exist -/// and must be of type `hash`. +/// - *index*: The id of the index to be used for the query. The index must exist +/// and must be of type *hash*. /// -/// - `example`: an example document. The example must contain a value for each +/// - *example*: an example document. The example must contain a value for each /// attribute in the index. /// -/// - `skip`: The number of documents to skip in the query. (optional) +/// - *skip*: The number of documents to skip in the query. (optional) /// -/// - `limit`: The maximal number of documents to return. (optional) +/// - *limit*: The maximal number of documents to return. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -84,18 +84,18 @@ var API = "_api/simple/"; /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// The same error code is also returned if an invalid index id or type is used. -/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_by_example_skiplist +/// @startDocuBlock JSA_put_api_simple_by_example_skiplist /// @brief returns all documents of a collection matching a given example, /// using a specific skiplist index /// -/// @RESTHEADER{PUT /_api/simple/by-example-skiplist,executes query by-example using a skiplist index} +/// @RESTHEADER{PUT /_api/simple/by-example-skiplist, Skiplist index} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query specification. @@ -107,19 +107,19 @@ var API = "_api/simple/"; /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `index`: The id of the index to be used for the query. The index must -/// exist and must be of type `skiplist`. +/// - *index*: The id of the index to be used for the query. The index must +/// exist and must be of type *skiplist*. /// -/// - `example`: an example document. The example must contain a value for each +/// - *example*: an example document. The example must contain a value for each /// attribute in the index. /// -/// - `skip`: The number of documents to skip in the query. (optional) +/// - *skip*: The number of documents to skip in the query. (optional) /// -/// - `limit`: The maximal number of documents to return. (optional) +/// - *limit*: The maximal number of documents to return. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -131,18 +131,18 @@ var API = "_api/simple/"; /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// The same error code is also returned if an invalid index id or type is used. -/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_by_example_bitarray +/// @startDocuBlock JSA_put_api_simple_by_example_bitarray /// @brief returns all documents of a collection matching a given example, /// using a specific bitarray index /// -/// @RESTHEADER{PUT /_api/simple/by-example-bitarray,executes query by-example using a bitarray index} +/// @RESTHEADER{PUT /_api/simple/by-example-bitarray, Bitarray index} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query specification. @@ -154,19 +154,19 @@ var API = "_api/simple/"; /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `index`: The id of the index to be used for the query. The index must -/// exist and must be of type `bitarray`. +/// - *index*: The id of the index to be used for the query. The index must +/// exist and must be of type *bitarray*. /// -/// - `example`: an example document. The example must contain a value for each +/// - *example*: an example document. The example must contain a value for each /// attribute in the index. /// -/// - `skip`: The number of documents to skip in the query. (optional) +/// - *skip*: The number of documents to skip in the query. (optional) /// -/// - `limit`: The maximal number of documents to return. (optional) +/// - *limit*: The maximal number of documents to return. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -178,18 +178,18 @@ var API = "_api/simple/"; /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// The same error code is also returned if an invalid index id or type is used. -/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_by_condition_skiplist +/// @startDocuBlock JSA_put_api_simple_by_condition_skiplist /// @brief returns all documents of a collection matching a given condition, /// using a specific skiplist index /// -/// @RESTHEADER{PUT /_api/simple/by-condition-skiplist,executes query by-condition using a skiplist index} +/// @RESTHEADER{PUT /_api/simple/by-condition-skiplist,Query by-condition using Skiplist index} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query specification. @@ -201,19 +201,19 @@ var API = "_api/simple/"; /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `index`: The id of the index to be used for the query. The index must -/// exist and must be of type `skiplist`. +/// - *index*: The id of the index to be used for the query. The index must +/// exist and must be of type *skiplist*. /// -/// - `condition`: the condition which all returned documents shall satisfy. +/// - *condition*: the condition which all returned documents shall satisfy. /// Conditions must be specified for all indexed attributes. /// -/// - `skip`: The number of documents to skip in the query. (optional) +/// - *skip*: The number of documents to skip in the query. (optional) /// -/// - `limit`: The maximal number of documents to return. (optional) +/// - *limit*: The maximal number of documents to return. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -225,18 +225,18 @@ var API = "_api/simple/"; /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// The same error code is also returned if an invalid index id or type is used. -/// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_by_condition_bitarray +/// @startDocuBlock JSA_put_api_simple_by_condition_bitarray /// @brief returns all documents of a collection matching a given condition, /// using a specific bitarray index /// -/// @RESTHEADER{PUT /_api/simple/by-condition-bitarray,executes query by-condition using a bitarray index} +/// @RESTHEADER{PUT /_api/simple/by-condition-bitarray, Query by-condition using bitarray index} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query specification. @@ -248,19 +248,19 @@ var API = "_api/simple/"; /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `index`: The id of the index to be used for the query. The index must -/// exist and must be of type `bitarray`. +/// - *index*: The id of the index to be used for the query. The index must +/// exist and must be of type *bitarray*. /// -/// - `condition`: the condition which all returned documents shall satisfy. +/// - *condition*: the condition which all returned documents shall satisfy. /// Conditions must be specified for all indexed attributes. /// -/// - `skip`: The number of documents to skip in the query. (optional) +/// - *skip*: The number of documents to skip in the query. (optional) /// -/// - `limit`: The maximal number of documents to return. (optional) +/// - *limit*: The maximal number of documents to return. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -272,10 +272,11 @@ var API = "_api/simple/"; /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// The same error code is also returned if an invalid index id or type is used. /// +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////////// @@ -382,10 +383,10 @@ setupIndexQueries(); // ----------------------------------------------------------------------------- //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_all +/// @startDocuBlock JSA_put_api_simple_all /// @brief returns all documents of a collection /// -/// @RESTHEADER{PUT /_api/simple/all,executes simple query ALL} +/// @RESTHEADER{PUT /_api/simple/all, Return all} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query. @@ -395,14 +396,14 @@ setupIndexQueries(); /// Returns all documents of a collections. The call expects a JSON object /// as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `skip`: The number of documents to skip in the query (optional). +/// - *skip*: The number of documents to skip in the query (optional). /// -/// - `limit`: The maximal amount of documents to return. The `skip` -/// is applied before the `limit` restriction. (optional) +/// - *limit*: The maximal amount of documents to return. The *skip* +/// is applied before the *limit* restriction. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -414,12 +415,12 @@ setupIndexQueries(); /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// -/// Limit the amount of documents using `limit` +/// Limit the amount of documents using *limit* /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleAllSkipLimit} /// var cn = "products"; @@ -442,7 +443,7 @@ setupIndexQueries(); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN /// -/// Using a `batchSize` value +/// Using a *batchSize* value /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleAllBatch} /// var cn = "products"; @@ -464,6 +465,7 @@ setupIndexQueries(); /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -512,10 +514,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_any +/// @startDocuBlock JSA_put_api_simple_any /// @brief returns a random document from a collection /// -/// @RESTHEADER{PUT /_api/simple/any,returns a random document from a collection} +/// @RESTHEADER{PUT /_api/simple/any, Random document} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query. @@ -525,11 +527,11 @@ actions.defineHttp({ /// Returns a random document from a collection. The call expects a JSON object /// as body with the following attributes: /// -/// - `collection`: The identifier or name of the collection to query. +/// - *collection*: The identifier or name of the collection to query. /// /// Returns a JSON object with the document stored in the attribute -/// `document` if the collection contains at least one document. If -/// the collection is empty, the `document` attrbute contains null. +/// *document* if the collection contains at least one document. If +/// the collection is empty, the *document* attrbute contains null. /// /// @RESTRETURNCODES /// @@ -541,10 +543,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleAny} /// var cn = "products"; @@ -566,6 +568,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -605,10 +608,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_near +/// @startDocuBlock JSA_put_api_simple_near /// @brief returns all documents of a collection near a given location /// -/// @RESTHEADER{PUT /_api/simple/near,executes a near query} +/// @RESTHEADER{PUT /_api/simple/near, Near query} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query. @@ -620,30 +623,30 @@ actions.defineHttp({ /// being first in the list. If there are near documents of equal distance, documents /// are chosen randomly from this set until the limit is reached. /// -/// In order to use the `near` operator, a geo index must be defined for the +/// In order to use the *near* operator, a geo index must be defined for the /// collection. This index also defines which attribute holds the coordinates /// for the document. If you have more then one geo-spatial index, you can use -/// the `geo` field to select a particular index. +/// the *geo* field to select a particular index. /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `latitude`: The latitude of the coordinate. +/// - *latitude*: The latitude of the coordinate. /// -/// - `longitude`: The longitude of the coordinate. +/// - *longitude*: The longitude of the coordinate. /// -/// - `distance`: If given, the attribute key used to return the distance to +/// - *distance*: If given, the attribute key used to return the distance to /// the given coordinate. (optional). If specified, distances are returned in meters. /// -/// - `skip`: The number of documents to skip in the query. (optional) +/// - *skip*: The number of documents to skip in the query. (optional) /// -/// - `limit`: The maximal amount of documents to return. The `skip` is -/// applied before the `limit` restriction. The default is 100. (optional) +/// - *limit*: The maximal amount of documents to return. The *skip* is +/// applied before the *limit* restriction. The default is 100. (optional) /// -/// - `geo`: If given, the identifier of the geo-index to use. (optional) +/// - *geo*: If given, the identifier of the geo-index to use. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -655,10 +658,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// Without distance: /// @@ -716,6 +719,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -786,10 +790,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_within +/// @startDocuBlock JSA_put_api_simple_within /// @brief returns all documents of a collection within a given radius /// -/// @RESTHEADER{PUT /_api/simple/within,executes a within query} +/// @RESTHEADER{PUT /_api/simple/within, Within query} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query. @@ -797,34 +801,34 @@ actions.defineHttp({ /// @RESTDESCRIPTION /// /// This will find all documents within a given radius around the coordinate -/// (`latitude`, `longitude`). The returned list is sorted by distance. +/// (*latitude*, *longitude*). The returned list is sorted by distance. /// -/// In order to use the `within` operator, a geo index must be defined for +/// In order to use the *within* operator, a geo index must be defined for /// the collection. This index also defines which attribute holds the /// coordinates for the document. If you have more then one geo-spatial index, -/// you can use the `geo` field to select a particular index. +/// you can use the *geo* field to select a particular index. /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `latitude`: The latitude of the coordinate. +/// - *latitude*: The latitude of the coordinate. /// -/// - `longitude`: The longitude of the coordinate. +/// - *longitude*: The longitude of the coordinate. /// -/// - `radius`: The maximal radius (in meters). +/// - *radius*: The maximal radius (in meters). /// -/// - `distance`: If given, the attribute key used to return the distance to +/// - *distance*: If given, the attribute key used to return the distance to /// the given coordinate. (optional). If specified, distances are returned in meters. /// -/// - `skip`: The number of documents to skip in the query. (optional) +/// - *skip*: The number of documents to skip in the query. (optional) /// -/// - `limit`: The maximal amount of documents to return. The `skip` is -/// applied before the `limit` restriction. The default is 100. (optional) +/// - *limit*: The maximal amount of documents to return. The *skip* is +/// applied before the *limit* restriction. The default is 100. (optional) /// -/// - `geo`: If given, the identifier of the geo-index to use. (optional) +/// - *geo*: If given, the identifier of the geo-index to use. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -836,10 +840,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// Without distance: /// @@ -892,6 +896,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -962,10 +967,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_fulltext +/// @startDocuBlock JSA_put_api_simple_fulltext /// @brief returns documents of a collection as a result of a fulltext query /// -/// @RESTHEADER{PUT /_api/simple/fulltext,executes a fulltext index query} +/// @RESTHEADER{PUT /_api/simple/fulltext, Fulltext index query} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query. @@ -973,27 +978,27 @@ actions.defineHttp({ /// @RESTDESCRIPTION /// /// This will find all documents from the collection that match the fulltext -/// query specified in `query`. +/// query specified in *query*. /// -/// In order to use the `fulltext` operator, a fulltext index must be defined +/// In order to use the *fulltext* operator, a fulltext index must be defined /// for the collection and the specified attribute. /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `attribute`: The attribute that contains the texts. +/// - *attribute*: The attribute that contains the texts. /// -/// - `query`: The fulltext query. +/// - *query*: The fulltext query. /// -/// - `skip`: The number of documents to skip in the query (optional). +/// - *skip*: The number of documents to skip in the query (optional). /// -/// - `limit`: The maximal amount of documents to return. The `skip` -/// is applied before the `limit` restriction. (optional) +/// - *limit*: The maximal amount of documents to return. The *skip* +/// is applied before the *limit* restriction. (optional) /// -/// - `index`: The identifier of the fulltext-index to use. +/// - *index*: The identifier of the fulltext-index to use. /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -1005,10 +1010,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleFulltext} /// var cn = "products"; @@ -1028,6 +1033,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -1085,10 +1091,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_by_example +/// @startDocuBlock JSA_put_api_simple_by_example /// @brief returns all documents of a collection matching a given example /// -/// @RESTHEADER{PUT /_api/simple/by-example,executes simple query by-example} +/// @RESTHEADER{PUT /_api/simple/by-example, Simple query by-example} /// /// @RESTBODYPARAM{query,string,required} /// Contains the query. @@ -1099,16 +1105,16 @@ actions.defineHttp({ /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `example`: The example document. +/// - *example*: The example document. /// -/// - `skip`: The number of documents to skip in the query (optional). +/// - *skip*: The number of documents to skip in the query (optional). /// -/// - `limit`: The maximal amount of documents to return. The `skip` -/// is applied before the `limit` restriction. (optional) +/// - *limit*: The maximal amount of documents to return. The *skip* +/// is applied before the *limit* restriction. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -1120,10 +1126,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// Matching an attribute: /// @@ -1187,6 +1193,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -1239,10 +1246,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_first_example +/// @startDocuBlock JSA_put_api_simple_first_example /// @brief returns one document of a collection matching a given example /// -/// @RESTHEADER{PUT /_api/simple/first-example,returns a document matching an example} +/// @RESTHEADER{PUT /_api/simple/first-example, Document matching an example} /// /// @RESTBODYPARAM{query,json,required} /// Contains the query. @@ -1253,11 +1260,11 @@ actions.defineHttp({ /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `example`: The example document. +/// - *example*: The example document. /// -/// Returns a result containing the document or `HTTP 404` if no +/// Returns a result containing the document or *HTTP 404* if no /// document matched the example. /// /// If more than one document in the collection matches the specified example, only @@ -1274,10 +1281,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// If a matching document was found: /// @@ -1320,6 +1327,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -1367,10 +1375,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_first +/// @startDocuBlock JSA_put_api_simple_first /// @brief returns the first document(s) of a collection /// -/// @RESTHEADER{PUT /_api/simple/first,returns the first document(s) of a collection} +/// @RESTHEADER{PUT /_api/simple/first, First document of a collection} /// /// @RESTBODYPARAM{query,json,required} /// Contains the query. @@ -1378,16 +1386,16 @@ actions.defineHttp({ /// @RESTDESCRIPTION /// /// This will return the first document(s) from the collection, in the order of -/// insertion/update time. When the `count` argument is supplied, the result +/// insertion/update time. When the *count* argument is supplied, the result /// will be a list of documents, with the "oldest" document being first in the /// result list. -/// If the `count` argument is not supplied, the result is the "oldest" document -/// of the collection, or `null` if the collection is empty. +/// If the *count* argument is not supplied, the result is the "oldest" document +/// of the collection, or *null* if the collection is empty. /// /// The request body must be a JSON object with the following attributes: -/// - `collection`: the name of the collection +/// - *collection*: the name of the collection /// -/// - `count`: the number of documents to return at most. Specifiying count is +/// - *count*: the number of documents to return at most. Specifiying count is /// optional. If it is not specified, it defaults to 1. /// /// Note: this method is not supported for sharded collections with more than @@ -1403,10 +1411,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// Retrieving the first n documents: /// @@ -1449,6 +1457,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -1485,10 +1494,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_last +/// @startDocuBlock JSA_put_api_simple_last /// @brief returns the last document(s) of a collection /// -/// @RESTHEADER{PUT /_api/simple/last,returns the last document(s) of a collection} +/// @RESTHEADER{PUT /_api/simple/last, Last document of a collection} /// /// @RESTBODYPARAM{query,json,required} /// Contains the query. @@ -1496,18 +1505,18 @@ actions.defineHttp({ /// @RESTDESCRIPTION /// /// This will return the last documents from the collection, in the order of -/// insertion/update time. When the `count` argument is supplied, the result +/// insertion/update time. When the *count* argument is supplied, the result /// will be a list of documents, with the "latest" document being first in the /// result list. /// /// The request body must be a JSON object with the following attributes: -/// - `collection`: the name of the collection +/// - *collection*: the name of the collection /// -/// - `count`: the number of documents to return at most. Specifiying count is +/// - *count*: the number of documents to return at most. Specifiying count is /// optional. If it is not specified, it defaults to 1. /// -/// If the `count` argument is not supplied, the result is the "latest" document -/// of the collection, or `null` if the collection is empty. +/// If the *count* argument is not supplied, the result is the "latest" document +/// of the collection, or *null* if the collection is empty. /// /// Note: this method is not supported for sharded collections with more than /// one shard. @@ -1522,10 +1531,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// Retrieving the last n documents: /// @@ -1568,6 +1577,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -1604,10 +1614,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_range +/// @startDocuBlock JSA_put_api_simple_range /// @brief returns all documents of a collection within a range /// -/// @RESTHEADER{PUT /_api/simple/range,executes simple range query} +/// @RESTHEADER{PUT /_api/simple/range, Simple range query} /// /// @RESTBODYPARAM{query,json,required} /// Contains the query. @@ -1619,23 +1629,23 @@ actions.defineHttp({ /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to query. +/// - *collection*: The name of the collection to query. /// -/// - `attribute`: The attribute path to check. +/// - *attribute*: The attribute path to check. /// -/// - `left`: The lower bound. +/// - *left*: The lower bound. /// -/// - `right`: The upper bound. +/// - *right*: The upper bound. /// -/// - `closed`: If `true`, use interval including `left` and `right`, -/// otherwise exclude `right`, but include `left`. +/// - *closed*: If *true*, use interval including *left* and *right*, +/// otherwise exclude *right*, but include *left*. /// -/// - `skip`: The number of documents to skip in the query (optional). +/// - *skip*: The number of documents to skip in the query (optional). /// -/// - `limit`: The maximal amount of documents to return. The `skip` -/// is applied before the `limit` restriction. (optional) +/// - *limit*: The maximal amount of documents to return. The *skip* +/// is applied before the *limit* restriction. (optional) /// -/// Returns a cursor containing the result, see @ref HttpCursor for details. +/// Returns a cursor containing the result, see [Http Cursor](../HttpAqlQueryCursor/README.md) for details. /// /// @RESTRETURNCODES /// @@ -1647,10 +1657,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleRange} /// var cn = "products"; @@ -1671,6 +1681,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -1730,10 +1741,10 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_remove_by_example +/// @startDocuBlock JSA_put_api_simple_remove_by_example /// @brief removes all documents of a collection that match an example /// -/// @RESTHEADER{PUT /_api/simple/remove-by-example,removes documents by example} +/// @RESTHEADER{PUT /_api/simple/remove-by-example, Remove documents by example} /// /// @RESTBODYPARAM{query,json,required} /// Contains the query. @@ -1745,23 +1756,23 @@ actions.defineHttp({ /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to remove from. +/// - *collection*: The name of the collection to remove from. /// -/// - `example`: An example document that all collection documents are compared +/// - *example*: An example document that all collection documents are compared /// against. /// /// - options: an json object which can contains following attributes: /// -/// - `waitForSync`: if set to true, then all removal operations will +/// - *waitForSync*: if set to true, then all removal operations will /// instantly be synchronised to disk. If this is not specified, then the /// collection's default sync behavior will be applied. /// -/// - `limit`: an optional value that determines how many documents to -/// delete at most. If `limit` is specified but is less than the number +/// - *limit*: an optional value that determines how many documents to +/// delete at most. If *limit* is specified but is less than the number /// of documents in the collection, it is undefined which of the documents /// will be deleted. /// -/// Note: the `limit` attribute is not supported on sharded collections. +/// Note: the *limit* attribute is not supported on sharded collections. /// Using it will result in an error. /// The options attributes waitForSync and limit can given yet without /// an ecapsulation into a json object. but this may be deprecated in future @@ -1779,10 +1790,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleRemoveByExample} /// var cn = "products"; @@ -1845,6 +1856,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -1892,11 +1904,11 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_replace_by_example +/// @startDocuBlock JSA_put_api_simple_replace_by_example /// @brief replaces the body of all documents of a collection that match an /// example /// -/// @RESTHEADER{PUT /_api/simple/replace-by-example,replaces documents by example} +/// @RESTHEADER{PUT /_api/simple/replace-by-example, Replace documents by example} /// /// @RESTBODYPARAM{query,json,required} /// Contains the query. @@ -1905,31 +1917,31 @@ actions.defineHttp({ /// /// This will find all documents in the collection that match the specified /// example object, and replace the entire document body with the new value -/// specified. Note that document meta-attributes such as `_id`, `_key`, -/// `_from`, `_to` etc. cannot be replaced. +/// specified. Note that document meta-attributes such as *_id*, *_key*, +/// *_from*, *_to* etc. cannot be replaced. /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to replace within. +/// - *collection*: The name of the collection to replace within. /// -/// - `example`: An example document that all collection documents are compared +/// - *example*: An example document that all collection documents are compared /// against. /// -/// - `newValue`: The replacement document that will get inserted in place +/// - *newValue*: The replacement document that will get inserted in place /// of the "old" documents. /// -/// - `options`: an json object which can contain following attributes +/// - *options*: an json object which can contain following attributes /// -/// - `waitForSync`: if set to true, then all removal operations will +/// - *waitForSync*: if set to true, then all removal operations will /// instantly be synchronised to disk. If this is not specified, then the /// collection's default sync behavior will be applied. /// -/// - `limit`: an optional value that determines how many documents to -/// replace at most. If `limit` is specified but is less than the number +/// - *limit*: an optional value that determines how many documents to +/// replace at most. If *limit* is specified but is less than the number /// of documents in the collection, it is undefined which of the documents /// will be replaced. /// -/// Note: the `limit` attribute is not supported on sharded collections. +/// Note: the *limit* attribute is not supported on sharded collections. /// Using it will result in an error. /// The options attributes waitForSync and limit can given yet without /// an ecapsulation into a json object. but this may be deprecated in future @@ -1947,10 +1959,10 @@ actions.defineHttp({ /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// /// @EXAMPLE_ARANGOSH_RUN{RestSimpleReplaceByExample} /// var cn = "products"; @@ -1999,6 +2011,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ @@ -2050,11 +2063,11 @@ actions.defineHttp({ }); //////////////////////////////////////////////////////////////////////////////// -/// @fn JSA_put_api_simple_update_by_example +/// @startDocuBlock JSA_put_api_simple_update_by_example /// @brief partially updates the body of all documents of a collection that /// match an example /// -/// @RESTHEADER{PUT /_api/simple/update-by-example,updates documents by example} +/// @RESTHEADER{PUT /_api/simple/update-by-example, Update documents by example} /// /// @RESTBODYPARAM{query,json,required} /// Contains the query. @@ -2063,37 +2076,37 @@ actions.defineHttp({ /// /// This will find all documents in the collection that match the specified /// example object, and partially update the document body with the new value -/// specified. Note that document meta-attributes such as `_id`, `_key`, -/// `_from`, `_to` etc. cannot be replaced. +/// specified. Note that document meta-attributes such as *_id*, *_key*, +/// *_from*, *_to* etc. cannot be replaced. /// /// The call expects a JSON object as body with the following attributes: /// -/// - `collection`: The name of the collection to update within. +/// - *collection*: The name of the collection to update within. /// -/// - `example`: An example document that all collection documents are compared +/// - *example*: An example document that all collection documents are compared /// against. /// -/// - `newValue`: A document containing all the attributes to update in the +/// - *newValue*: A document containing all the attributes to update in the /// found documents. /// -/// - `options`: a json object wich can contains following attributes: +/// - *options*: a json object wich can contains following attributes: /// -/// - `keepNull`: This 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` +/// - *keepNull*: This 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 updated document. /// -/// - `waitForSync`: if set to true, then all removal operations will +/// - *waitForSync*: if set to true, then all removal operations will /// instantly be synchronised to disk. If this is not specified, then the /// collection's default sync behavior will be applied. /// -/// - `limit`: an optional value that determines how many documents to -/// update at most. If `limit` is specified but is less than the number +/// - *limit*: an optional value that determines how many documents to +/// update at most. If *limit* is specified but is less than the number /// of documents in the collection, it is undefined which of the documents /// will be updated. /// -/// Note: the `limit` attribute is not supported on sharded collections. +/// Note: the *limit* attribute is not supported on sharded collections. /// Using it will result in an error. /// /// Returns the number of documents that were updated. @@ -2102,18 +2115,18 @@ actions.defineHttp({ /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} -/// is returned if the collection was updated successfully and `waitForSync` was -/// `true`. +/// is returned if the collection was updated successfully and *waitForSync* was +/// *true*. /// /// @RESTRETURNCODE{400} /// is returned if the body does not contain a valid JSON representation of a /// query. The response body contains an error document in this case. /// /// @RESTRETURNCODE{404} -/// is returned if the collection specified by `collection` is unknown. The +/// is returned if the collection specified by *collection* is unknown. The /// response body contains an error document in this case. /// -/// *Examples* +/// @EXAMPLES /// using old syntax for options /// @EXAMPLE_ARANGOSH_RUN{RestSimpleUpdateByExample} /// var cn = "products"; @@ -2162,6 +2175,7 @@ actions.defineHttp({ /// logJsonResponse(response); /// db._drop(cn); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// actions.defineHttp({ diff --git a/js/actions/api-transaction.js b/js/actions/api-transaction.js index bb49b166a7..fe75d23fba 100644 --- a/js/actions/api-transaction.js +++ b/js/actions/api-transaction.js @@ -36,12 +36,13 @@ var actions = require("org/arangodb/actions"); // ----------------------------------------------------------------------------- //////////////////////////////////////////////////////////////////////////////// +/// @startDocuBlock JSF_post_api_transaction /// @brief execute a server-side transaction /// -/// @RESTHEADER{POST /_api/transaction,executes a transaction} +/// @RESTHEADER{POST /_api/transaction, Execute transaction} /// /// @RESTBODYPARAM{body,string,required} -/// Contains the `collections` and `action`. +/// Contains the *collections* and *action*. /// /// @RESTDESCRIPTION /// @@ -49,85 +50,85 @@ var actions = require("org/arangodb/actions"); /// /// The following attributes must be specified inside the JSON object: /// -/// - `collections`: contains the list of collections to be used in the -/// transaction (mandatory). `collections` must be a JSON array that can -/// have the optional sub-attributes `read` and `write`. `read` -/// and `write` must each be either lists of collections names or strings +/// - *collections*: contains the list of collections to be used in the +/// transaction (mandatory). *collections* must be a JSON array that can +/// have the optional sub-attributes *read* and *write*. *read* +/// and *write* must each be either lists of collections names or strings /// with a single collection name. /// -/// - `action`: the actual transaction operations to be executed, in the +/// - *action*: the actual transaction operations to be executed, in the /// form of stringified Javascript code. The code will be executed on server /// side, with late binding. It is thus critical that the code specified in -/// `action` properly sets up all the variables it needs. -/// If the code specified in `action` ends with a return statement, the -/// value returned will also be returned by the REST API in the `result` +/// *action* properly sets up all the variables it needs. +/// If the code specified in *action* ends with a return statement, the +/// value returned will also be returned by the REST API in the *result* /// attribute if the transaction committed successfully. /// /// The following optional attributes may also be specified in the request: /// -/// - `waitForSync`: an optional boolean flag that, if set, will force the +/// - *waitForSync*: an optional boolean flag that, if set, will force the /// transaction to write all data to disk before returning. /// -/// - `lockTimeout`: an optional numeric value that can be used to set a +/// - *lockTimeout*: an optional 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 +/// value will be used. Setting *lockTimeout* to *0* will make ArangoDB /// not time out waiting for a lock. /// -/// - `params`: optional arguments passed to `action`. +/// - *params*: optional arguments passed to *action*. /// /// If the transaction is fully executed and committed on the server, -/// `HTTP 200` will be returned. Additionally, the return value of the -/// code defined in `action` will be returned in the `result` attribute. +/// *HTTP 200* will be returned. Additionally, the return value of the +/// code defined in *action* will be returned in the *result* attribute. /// /// For successfully committed transactions, the returned JSON object has the /// following properties: /// -/// - `error`: boolean flag to indicate if an error occurred (`false` +/// - *error*: boolean flag to indicate if an error occurred (*false* /// in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// -/// - `result`: the return value of the transaction +/// - *result*: the return value of the transaction /// /// If the transaction specification is either missing or malformed, the server -/// will respond with `HTTP 400`. +/// will respond with *HTTP 400*. /// /// The body of the response will then contain a JSON object with additional error /// details. The object has the following attributes: /// -/// - `error`: boolean flag to indicate that an error occurred (`true` in this case) +/// - *error*: boolean flag to indicate that an error occurred (*true* in this case) /// -/// - `code`: the HTTP status code +/// - *code*: the HTTP status code /// -/// - `errorNum`: the server error number +/// - *errorNum*: the server error number /// -/// - `errorMessage`: a descriptive error message +/// - *errorMessage*: a descriptive error message /// /// If a transaction fails to commit, either by an exception thrown in the -/// `action` code, or by an internal error, the server will respond with +/// *action* code, or by an internal error, the server will respond with /// an error. /// Any other errors will be returned with any of the return codes -/// `HTTP 400`, `HTTP 409`, or `HTTP 500`. +/// *HTTP 400*, *HTTP 409*, or *HTTP 500*. /// /// @RESTRETURNCODES /// /// @RESTRETURNCODE{200} /// If the transaction is fully executed and committed on the server, -/// `HTTP 200` will be returned. +/// *HTTP 200* will be returned. /// /// @RESTRETURNCODE{400} /// If the transaction specification is either missing or malformed, the server -/// will respond with `HTTP 400`. +/// will respond with *HTTP 400*. /// /// @RESTRETURNCODE{404} /// If the transaction specification contains an unknown collection, the server -/// will respond with `HTTP 404`. +/// will respond with *HTTP 404*. /// /// @RESTRETURNCODE{500} /// Exceptions thrown by users will make the server respond with a return code of -/// `HTTP 500` +/// *HTTP 500* /// -/// *Examples* +/// @EXAMPLES /// /// Executing a transaction on a single collection: /// @@ -238,6 +239,7 @@ var actions = require("org/arangodb/actions"); /// /// logJsonResponse(response); /// @END_EXAMPLE_ARANGOSH_RUN +/// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// function post_api_transaction(req, res) { diff --git a/js/apps/system/aardvark/frontend/js/graphViewer/graph/gharialAdapter.js b/js/apps/system/aardvark/frontend/js/graphViewer/graph/gharialAdapter.js index 26ad8c6102..fe3b332c63 100644 --- a/js/apps/system/aardvark/frontend/js/graphViewer/graph/gharialAdapter.js +++ b/js/apps/system/aardvark/frontend/js/graphViewer/graph/gharialAdapter.js @@ -123,7 +123,8 @@ function GharialAdapter(nodes, edges, viewer, config) { if (query !== queries.getAllGraphs) { bindVars.graph = graphName; if (query !== queries.connectedEdges - && query !== queries.childrenCentrality) { + && query !== queries.childrenCentrality + && query !== queries.randomVertices) { bindVars.dir = direction; } } @@ -154,28 +155,11 @@ function GharialAdapter(nodes, edges, viewer, config) { }, getNRandom = function(n, callback) { - var list = [], - i = 0, - rand, - onSuccess = function(data) { - list.push(data.document || {}); - if (list.length === n) { - callback(list); - } - }; - for (i = 0; i < n; i++) { - rand = Math.floor(Math.random() * nodeCollections.length); - $.ajax({ - cache: false, - type: 'PUT', - url: api.any, - data: JSON.stringify({ - collection: nodeCollections[rand] - }), - contentType: "application/json", - success: onSuccess - }); - } + sendQuery(queries.randomVertices, { + limit: n + }, function(res) { + callback(res); + }); }, parseResultOfTraversal = function (result, callback) { @@ -250,6 +234,7 @@ function GharialAdapter(nodes, edges, viewer, config) { + "})"; queries.childrenCentrality = "RETURN LENGTH(GRAPH_EDGES(@graph, @id, {direction: any}))"; queries.connectedEdges = "RETURN GRAPH_EDGES(@graph, @id)"; + queries.randomVertices = "FOR x IN GRAPH_VERTICES(@graph, {}) SORT RAND() LIMIT @limit RETURN x"; self.explore = absAdapter.explore; @@ -259,12 +244,11 @@ function GharialAdapter(nodes, edges, viewer, config) { self.loadRandomNode = function(callback) { getNRandom(1, function(list) { - var r = list[0]; - if (r._id) { - self.loadInitialNode(r._id, callback); - return; + if (list.length === 0) { + callback({errorCode: 404}); + return; } - return; + self.loadInitialNode(list[0]._id, callback); }); }; diff --git a/js/apps/system/aardvark/frontend/js/graphViewer/graphViewer.js b/js/apps/system/aardvark/frontend/js/graphViewer/graphViewer.js index 02934440cd..eee0dc5936 100644 --- a/js/apps/system/aardvark/frontend/js/graphViewer/graphViewer.js +++ b/js/apps/system/aardvark/frontend/js/graphViewer/graphViewer.js @@ -211,7 +211,7 @@ function GraphViewer(svg, width, height, adapterConfig, config) { this.loadGraphWithRandomStart = function(callback) { adapter.loadRandomNode(function (node) { - if (node.errorCode) { + if (node.errorCode && node.errorCode === 404) { callback(node); return; } diff --git a/js/apps/system/aardvark/frontend/js/graphViewer/ui/eventDispatcherControls.js b/js/apps/system/aardvark/frontend/js/graphViewer/ui/eventDispatcherControls.js index 11444db815..b3ec55ec1d 100644 --- a/js/apps/system/aardvark/frontend/js/graphViewer/ui/eventDispatcherControls.js +++ b/js/apps/system/aardvark/frontend/js/graphViewer/ui/eventDispatcherControls.js @@ -431,7 +431,8 @@ function EventDispatcherControls(list, nodeShaper, edgeShaper, start, dispatcher .filter(":selected") .text(); adapter.useNodeCollection(nodeCollection); - } + }, + "Select" ); } self.rebindAll(self.newNodeRebinds()); @@ -497,7 +498,8 @@ function EventDispatcherControls(list, nodeShaper, edgeShaper, start, dispatcher .filter(":selected") .text(); adapter.useEdgeCollection(edgeCollection); - } + }, + "Select" ); } self.rebindAll(self.connectNodesRebinds()); diff --git a/js/apps/system/aardvark/frontend/js/graphViewer/ui/graphViewerUI.js b/js/apps/system/aardvark/frontend/js/graphViewer/ui/graphViewerUI.js index 8a12445340..7f8a3e903a 100644 --- a/js/apps/system/aardvark/frontend/js/graphViewer/ui/graphViewerUI.js +++ b/js/apps/system/aardvark/frontend/js/graphViewer/ui/graphViewerUI.js @@ -2,7 +2,7 @@ /*global document, $, _ */ /*global EventDispatcherControls, NodeShaperControls, EdgeShaperControls */ /*global LayouterControls, GharialAdapterControls*/ -/*global GraphViewer, d3, window, alert*/ +/*global GraphViewer, d3, window*/ //////////////////////////////////////////////////////////////////////////////// /// @brief Graph functionality /// @@ -453,7 +453,7 @@ function GraphViewerUI(container, adapterConfig, optWidth, optHeight, viewerConf } else { graphViewer.loadGraphWithRandomStart(function(node) { if (node && node.errorCode) { - alert("Sorry your graph seems to be empty"); + window.alert("Sorry your graph seems to be empty"); } }); } diff --git a/js/apps/system/aardvark/frontend/js/graphViewer/ui/modalDialogHelper.js b/js/apps/system/aardvark/frontend/js/graphViewer/ui/modalDialogHelper.js index 41f029af2c..182c18b7a4 100644 --- a/js/apps/system/aardvark/frontend/js/graphViewer/ui/modalDialogHelper.js +++ b/js/apps/system/aardvark/frontend/js/graphViewer/ui/modalDialogHelper.js @@ -292,6 +292,9 @@ var modalDialogHelper = modalDialogHelper || {}; }; addLineButton.id = id + "_addLine"; addLineButton.className = "graphViewer-icon-button gv-icon-small add"; + if (typeof list === "string" && list.length > 0) { + list = [list]; + } if (list.length > 0) { input.value = list[0]; } @@ -444,8 +447,8 @@ var modalDialogHelper = modalDialogHelper || {}; return content.bodyTable; }; - modalDialogHelper.createModalDialog = function(title, idprefix, objects, callback) { - var table = modalDialogHelper.modalDivTemplate(title, null, idprefix, callback); + modalDialogHelper.createModalDialog = function(title, idprefix, objects, callback, buttonTitle) { + var table = modalDialogHelper.modalDivTemplate(title, buttonTitle, idprefix, callback); _.each(objects, function(o) { insertModalRow(table, idprefix, o); }); diff --git a/js/apps/system/aardvark/frontend/js/views/graphManagementView.js b/js/apps/system/aardvark/frontend/js/views/graphManagementView.js index bd05173f46..2294a10d9a 100644 --- a/js/apps/system/aardvark/frontend/js/views/graphManagementView.js +++ b/js/apps/system/aardvark/frontend/js/views/graphManagementView.js @@ -12,12 +12,12 @@ removedECollList : [], events: { - "click #deleteGraph" : "deleteGraph", - "click .icon_arangodb_settings2" : "editGraph", - "click #createGraph" : "addNewGraph", - "keyup #graphManagementSearchInput" : "search", - "click #graphManagementSearchSubmit" : "search", - "click .tile-graph" : "loadGraphViewer" + "click #deleteGraph" : "deleteGraph", + "click .icon_arangodb_settings2.editGraph" : "editGraph", + "click #createGraph" : "addNewGraph", + "keyup #graphManagementSearchInput" : "search", + "click #graphManagementSearchSubmit" : "search", + "click .tile-graph" : "loadGraphViewer" }, loadGraphViewer: function(e) { @@ -180,14 +180,12 @@ } } ); - //if no edge definition is left if (edgeDefinitions.length === 0) { $('#s2id_newEdgeDefinitions0 .select2-choices').css("border-color", "red"); return; } - //get current edgeDefs/orphanage var graph = this.collection.findWhere({_key: name}); var currentEdgeDefinitions = graph.get("edgeDefinitions"); @@ -202,7 +200,6 @@ } } ); - //add new orphans editedVertexCollections.forEach( function(vC) { @@ -212,7 +209,6 @@ } ); - //evaluate all new, edited and deleted edge definitions var newEDs = []; var editedEDs = []; @@ -259,7 +255,6 @@ graph.deleteEdgeDefinition(eD); } ); - this.updateGraphManagementView(); window.modalView.hide(); }, @@ -315,6 +310,13 @@ index, edgeDefinitionElements; + if (!name) { + arangoHelper.arangoError( + "A name for the graph has to be provided." + ); + return 0; + } + if (this.collection.findWhere({_key: name})) { arangoHelper.arangoError( "The graph '" + name + "' already exists." @@ -343,12 +345,7 @@ } } ); - if (!name) { - arangoHelper.arangoError( - "A name for the graph has to be provided." - ); - return 0; - } + this.collection.create({ name: name, edgeDefinitions: edgeDefinitions, @@ -400,6 +397,9 @@ name = graph.get("_key"); edgeDefinitions = graph.get("edgeDefinitions"); + if (!edgeDefinitions || edgeDefinitions.length === 0 ) { + edgeDefinitions = [{collection : "", from : "", to :""}]; + } orphanCollections = graph.get("orphanCollections"); tableContent.push( diff --git a/js/apps/system/aardvark/lib/swagger.js b/js/apps/system/aardvark/lib/swagger.js index 796c626595..cd3b9d0598 100644 --- a/js/apps/system/aardvark/lib/swagger.js +++ b/js/apps/system/aardvark/lib/swagger.js @@ -87,7 +87,7 @@ exports.Swagger = function () { var result = {}, apis = [], pathes, - regex = /(:)([^\/]*)/, + regex = /(:)([^\/]*)/g, i, url, api, diff --git a/js/apps/system/aardvark/test/specs/views/graphManagementViewSpec.js b/js/apps/system/aardvark/test/specs/views/graphManagementViewSpec.js index 01c1e84006..217f5f60f8 100644 --- a/js/apps/system/aardvark/test/specs/views/graphManagementViewSpec.js +++ b/js/apps/system/aardvark/test/specs/views/graphManagementViewSpec.js @@ -1,6 +1,6 @@ /*jslint indent: 2, nomen: true, maxlen: 100, white: true plusplus: true, browser: true*/ /*global describe, beforeEach, afterEach, it, */ -/*global spyOn, runs, expect, waitsFor*/ +/*global spyOn, runs, expect, waitsFor, arangoHelper*/ /*global GraphManagementView, _, jasmine, $*/ (function () { @@ -40,6 +40,22 @@ document.body.removeChild(modalDiv); }); + it("should updateGraphManagementView", function () { + + spyOn(view.collection, "fetch").andCallFake(function (a) { + a.success(); + }); + + spyOn(view, "render"); + + view.updateGraphManagementView(); + + expect(view.render).toHaveBeenCalled(); + + + + }); + it("should fetch the graphs on render", function () { spyOn(graphs, "fetch"); view.render(); @@ -112,7 +128,7 @@ return "blabalblub"; }, width : function () { - return 100 + return 100; }, html : function () { @@ -142,6 +158,139 @@ ); }); + it("should showHideDefinition", function () { + var e = { + currentTarget: { + id: "row_newEdgeDefinitions1" + }, + stopPropagation : function () { + + } + }, + a = { + attr: function (x) { + return "row_newEdgeDefinitions1"; + }, + toggle : function () { + + } + }; + spyOn(a, "toggle"); + + spyOn(window, "$").andReturn(a); + + + view.showHideDefinition(e); + + expect(a.toggle).toHaveBeenCalled(); + }); + + it("should addDefinition", function () { + var e = { + currentTarget: { + id: "row_newEdgeDefinitions1" + }, + stopPropagation : function () { + + } + }, + a = { + attr: function (x) { + return "addAfter_newEdgeDefinitions1"; + }, + toggle : function () { + + }, + before : function () { + + }, + select2 : function () { + + } + }; + + spyOn(view.edgeDefintionTemplate, "render"); + + spyOn(window, "$").andReturn(a); + + spyOn(window.modalView, "undelegateEvents"); + spyOn(window.modalView, "delegateEvents"); + + view.options.collectionCollection.add( + {name : "NONSYSTEM", isSystem : false, type : "edge"}); + view.options.collectionCollection.add( + {name : "SYSTEM", isSystem : true, type : 'document'}); + + view.counter = 0; + + view.addRemoveDefinition(e); + + expect(window.modalView.undelegateEvents).toHaveBeenCalled(); + expect(window.modalView.delegateEvents).toHaveBeenCalled(); + expect(view.edgeDefintionTemplate.render).toHaveBeenCalledWith({number : 1}); + }); + + it("should removeDefinition", function () { + var e = { + currentTarget: { + id: "row_newEdgeDefinitions1" + }, + stopPropagation : function () { + + } + }, + a = { + attr: function (x) { + return "remove_newEdgeDefinitions1"; + }, + remove : function () { + + }, + before : function () { + + }, + select2 : function () { + + } + }; + + spyOn(view.edgeDefintionTemplate, "render"); + + spyOn(window, "$").andReturn(a); + + spyOn(window.modalView, "undelegateEvents"); + spyOn(window.modalView, "delegateEvents"); + + view.options.collectionCollection.add( + {name : "NONSYSTEM", isSystem : false, type : "edge"}); + view.options.collectionCollection.add( + {name : "SYSTEM", isSystem : true, type : 'document'}); + + view.counter = 0; + + view.addRemoveDefinition(e); + + expect(window.modalView.undelegateEvents).not.toHaveBeenCalled(); + expect(window.modalView.delegateEvents).not.toHaveBeenCalled(); + expect(view.edgeDefintionTemplate.render).not.toHaveBeenCalled(); + }); + + + it("should handle resize", function () { + + var ui = { + changeWidth : function () { + + } + }; + spyOn(ui, "changeWidth"); + view.ui = ui; + + view.handleResize(1); + expect(view.ui.changeWidth).toHaveBeenCalledWith(1); + + }); + it("should delete graph", function () { var e = { currentTarget: { @@ -209,8 +358,8 @@ to: ["blob"] }], orphanCollections: [] - }); - var e = { + }), + e = { currentTarget: { id: "blabalblub" }, @@ -260,8 +409,7 @@ to: ["blob"] }], orphanCollections: [] - }); - var e = { + }), e = { currentTarget: { id: "blabalblub" }, @@ -299,7 +447,8 @@ }); - it("should not set to and from for added definition as already in use and has been entered manually", function () { + it("should not set to and from for added definition as already in " + + "use and has been entered manually", function () { view.removedECollList = ["moppel"]; var model = view.collection.create({ _key: "blub2", @@ -310,8 +459,7 @@ to: ["blob"] }], orphanCollections: [] - }); - var e = { + }), e = { currentTarget: { id: "blabalblub" }, @@ -349,7 +497,8 @@ }); - it("should not set to and from for removed definition as already in use and has been entered manually", function () { + it("should not set to and from for removed definition as " + + "already in use and has been entered manually", function () { view.removedECollList = ["moppel"]; var model = view.collection.create({ _key: "blub2", @@ -360,8 +509,7 @@ to: ["blob"] }], orphanCollections: [] - }); - var e = { + }), e = { currentTarget: { id: "blabalblub" }, @@ -390,8 +538,8 @@ view.setFromAndTo(e); expect(e.stopPropagation).toHaveBeenCalled(); - expect(view.removedECollList.indexOf("moppel")).toEqual(-1) - expect(view.eCollList.indexOf("moppel")).not.toEqual(-1) + expect(view.removedECollList.indexOf("moppel")).toEqual(-1); + expect(view.eCollList.indexOf("moppel")).not.toEqual(-1); model.destroy(); @@ -413,19 +561,74 @@ spyOn(window.modalView, "show"); - view.options.collectionCollection.add({name : "NONSYSTEM", isSystem : false, type : "edge"}); - view.options.collectionCollection.add({name : "SYSTEM", isSystem : true, type : 'document'}); + view.options.collectionCollection.add( + {name : "NONSYSTEM", isSystem : false, type : "edge"}); + view.options.collectionCollection.add( + {name : "SYSTEM", isSystem : true, type : 'document'}); view.editGraph(e); expect(e.stopPropagation).toHaveBeenCalled(); - expect(view.removedECollList.length).toEqual(0) - expect(view.eCollList.length).not.toEqual(0) + expect(view.removedECollList.length).toEqual(0); + expect(view.eCollList.length).not.toEqual(0); expect(window.modalView.show).toHaveBeenCalled(); }); + it("should search", function () { + + var a = { + val : function () { + return "searchString"; + }, + html: function () { + return ""; + }, + focus: function () { + return ""; + }, + 0 : {setSelectionRange: function () { + return ""; + }} + }, g = { + _key: "blub2", + name: "blub2", + edgeDefinitions: [{ + collection: "blub", + from: ["bla"], + to: ["blob"] + },{ + collection: "blub2", + from: ["bla"], + to: ["blob"] + }], + orphanCollections: [], + get : function (a) { + return g[a]; + } + }; + + spyOn(view.collection, "filter").andCallFake(function (a) { + a(g); + return g; + }); + + spyOn(window, "$").andReturn(a); + spyOn(view.template, "render"); + + view.search(); + + expect(view.template.render).toHaveBeenCalledWith({ + graphs : g, + searchString : "searchString" + }); + + + + }); + + it("should create edit graph modal in edit mode", function () { var g = { @@ -442,15 +645,9 @@ }], orphanCollections: [], get : function (a) { - return g[a] + return g[a]; } - }; - - spyOn(view.collection, "findWhere").andReturn( - g - ); - - var e = { + }, e = { currentTarget: { id: "blabalblub" }, @@ -459,32 +656,243 @@ removed : {id : "moppel"} }; + spyOn(view.collection, "findWhere").andReturn( + g + ); + spyOn(e, "stopPropagation"); spyOn(window.modalView, "show"); - view.options.collectionCollection.add({name : "NONSYSTEM", isSystem : false, type : "edge"}); - view.options.collectionCollection.add({name : "SYSTEM", isSystem : true, type : 'document'}); + view.options.collectionCollection.add( + {name : "NONSYSTEM", isSystem : false, type : "edge"}); + view.options.collectionCollection.add( + {name : "SYSTEM", isSystem : true, type : 'document'}); view.editGraph(e); expect(e.stopPropagation).toHaveBeenCalled(); - expect(view.removedECollList.length).toEqual(1) - expect(view.eCollList.length).toEqual(0) + expect(view.removedECollList.length).toEqual(1); + expect(view.eCollList.length).toEqual(0); expect(window.modalView.show).toHaveBeenCalled(); }); - /*editGraph : function(e) { - e.stopPropagation(); - this.collection.fetch(); - this.graphToEdit = this.evaluateGraphName($(e.currentTarget).attr("id"), '_settings'); - var graph = this.collection.findWhere({_key: this.graphToEdit}); - this.createEditGraphModal( - graph + + it("should create edit graph modal in edit mode without defintions", function () { + + var g = { + _key: "blub2", + name: "blub2", + edgeDefinitions: [], + orphanCollections: [], + get : function (a) { + return g[a]; + } + }, e = { + currentTarget: { + id: "blabalblub" + }, + stopPropagation : function () {}, + val : "blub", + removed : {id : "moppel"} + }; + + spyOn(view.collection, "findWhere").andReturn( + g ); - },*/ + + spyOn(e, "stopPropagation"); + spyOn(window.modalView, "show"); + + + view.options.collectionCollection.add( + {name : "NONSYSTEM", isSystem : false, type : "edge"}); + view.options.collectionCollection.add( + {name : "SYSTEM", isSystem : true, type : 'document'}); + + view.editGraph(e); + + expect(e.stopPropagation).toHaveBeenCalled(); + expect(view.removedECollList.length).toEqual(0); + expect(view.eCollList.length).toEqual(1); + expect(window.modalView.show).toHaveBeenCalled(); + + + }); + + it("should not saveEditedGraph as no defintions are supplied", function () { + + var + a = { + p : "", + setParam : function (p) { + a.p = p; + }, + select2: function () { + if (a.p === "#newVertexCollections") { + return "newVertexCollections"; + } + if (a.p === "#s2id_newEdgeDefinitions1") { + return "collection"; + } + if (a.p === "#s2id_fromCollections1") { + return "fromCollection"; + } + if (a.p === "#s2id_toCollections1") { + return "toCollection"; + } + }, + attr : function () { + if (a.p.indexOf("edgeD") !== -1) { + return "1"; + } + }, + toArray: function () { + if (a.p === "[id^=s2id_newEdgeDefinitions]") { + return ["edgeD1", "edgeD2", "edgeD3"]; + } + }, + css : function () { + + }, + 0 : {value : "name"} + }; + + spyOn(_, "pluck").andCallFake(function (s, b) { + if (s === "newVertexCollections") { + return ["orphan1", "orphan2", "orphan3"]; + } + if (s === "collection") { + return [undefined]; + } + if (s === "fromCollection") { + return ["fromCollection"]; + } + if (s === "toCollection") { + return ["toCollection"]; + } + }); + + spyOn(window, "$").andCallFake(function (x) { + a.setParam(x); + return a; + }); + + spyOn(view, "updateGraphManagementView"); + + view.saveEditedGraph(); + + expect(view.updateGraphManagementView).not.toHaveBeenCalled(); + + + + }); + + it("should saveEditedGraph", function () { + + var + a = { + p : "", + setParam : function (p) { + a.p = p; + }, + select2: function () { + if (a.p === "#newVertexCollections") { + return "newVertexCollections"; + } + if (a.p.indexOf("#s2id_newEdgeDefinitions") !== -1) { + return a.p.split("#s2id_newEdgeDefinitions")[1]; + } + if (a.p.indexOf("#s2id_fromCollections") !== -1) { + return "fromCollection"; + } + if (a.p.indexOf("#s2id_toCollections") !== -1) { + return "toCollection"; + } + }, + attr : function () { + if (a.p.indexOf("edgeD") !== -1) { + return a.p; + } + }, + toArray: function () { + if (a.p === "[id^=s2id_newEdgeDefinitions]") { + return ["edgeD1", "edgeD2", "edgeD3"]; + } + }, + 0 : {value : "name"} + }, g = { + _key: "blub2", + name: "blub2", + edgeDefinitions: [{ + collection: "blub", + from: ["bla"], + to: ["blob"] + },{ + collection: "collection2", + from: ["bla"], + to: ["blob"] + }], + orphanCollections: ["o1", "o2", "o3"], + get : function (a) { + return g[a]; + }, + deleteVertexCollection : function (o) { + g.orphanCollections.splice(g.orphanCollections.indexOf(o), 1); + }, + addVertexCollection : function (o) { + g.orphanCollections.push(o); + }, + addEdgeDefinition : function (o) { + g.edgeDefinitions.push(o); + }, + modifyEdgeDefinition : function (o) { + }, + deleteEdgeDefinition : function (o) { + g.edgeDefinitions.forEach(function (e) { + if (e.collection === o.collection) { + delete g.edgeDefinitions[e]; + } + }); + } + }; + + spyOn(_, "pluck").andCallFake(function (s, b) { + if (s === "newVertexCollections") { + return ["orphan1", "orphan2", "orphan3"]; + } + if (s.indexOf("edgeD") !== -1) { + return ["collection" + s.split("edgeD")[1] ]; + } + if (s === "fromCollection") { + return ["fromCollection"]; + } + if (s === "toCollection") { + return ["toCollection"]; + } + }); + + spyOn(window, "$").andCallFake(function (x) { + a.setParam(x); + return a; + }); + spyOn(view.collection, "findWhere").andReturn( + g + ); + + spyOn(view, "updateGraphManagementView"); + spyOn(window.modalView, "hide"); + + view.saveEditedGraph(); + + expect(view.updateGraphManagementView).toHaveBeenCalled(); + expect(window.modalView.hide).toHaveBeenCalled(); + + + + }); it("should create a sorted list of all graphs", function () { var list = $("div.tile h5.collectionName", "#graphManagementThumbnailsIn"); @@ -495,6 +903,440 @@ expect($(list[2]).html()).toEqual(g3._key); }); + it("should not saveCreatedGraph as name already exists", function () { + + var + a = { + p : "", + setParam : function (p) { + a.p = p; + }, + select2: function () { + if (a.p === "#newVertexCollections") { + return "newVertexCollections"; + } + if (a.p.indexOf("#s2id_newEdgeDefinitions") !== -1) { + return a.p.split("#s2id_newEdgeDefinitions")[1]; + } + if (a.p.indexOf("#s2id_fromCollections") !== -1) { + return "fromCollection"; + } + if (a.p.indexOf("#s2id_toCollections") !== -1) { + return "toCollection"; + } + }, + attr : function () { + if (a.p.indexOf("edgeD") !== -1) { + return a.p; + } + }, + toArray: function () { + if (a.p === "[id^=s2id_newEdgeDefinitions]") { + return ["edgeD1", "edgeD2", "edgeD3"]; + } + }, + val : function () { + return "name"; + } + }, g = { + _key: "name", + name: "name", + edgeDefinitions: [{ + collection: "blub", + from: ["bla"], + to: ["blob"] + },{ + collection: "collection2", + from: ["bla"], + to: ["blob"] + }], + orphanCollections: ["o1", "o2", "o3"], + get : function (a) { + return g[a]; + }, + deleteVertexCollection : function (o) { + g.orphanCollections.splice(g.orphanCollections.indexOf(o), 1); + }, + addVertexCollection : function (o) { + g.orphanCollections.push(o); + }, + addEdgeDefinition : function (o) { + g.edgeDefinitions.push(o); + }, + modifyEdgeDefinition : function (o) { + }, + deleteEdgeDefinition : function (o) { + g.edgeDefinitions.forEach(function (e) { + if (e.collection === o.collection) { + delete g.edgeDefinitions[e]; + } + }); + } + }; + + spyOn(_, "pluck").andCallFake(function (s, b) { + if (s === "newVertexCollections") { + return ["orphan1", "orphan2", "orphan3"]; + } + if (s.indexOf("edgeD") !== -1) { + return ["collection" + s.split("edgeD")[1] ]; + } + if (s === "fromCollection") { + return ["fromCollection"]; + } + if (s === "toCollection") { + return ["toCollection"]; + } + }); + + spyOn(window, "$").andCallFake(function (x) { + a.setParam(x); + return a; + }); + + spyOn(view.collection, "findWhere").andReturn( + g + ); + + spyOn(arangoHelper, "arangoError"); + + view.createNewGraph(); + + expect(arangoHelper.arangoError).toHaveBeenCalledWith( + "The graph '" + "name" + "' already exists."); + + + + }); + + it("should saveCreatedGraph", function () { + + var + a = { + p : "", + setParam : function (p) { + a.p = p; + }, + select2: function () { + if (a.p === "#newVertexCollections") { + return "newVertexCollections"; + } + if (a.p.indexOf("#s2id_newEdgeDefinitions") !== -1) { + return a.p.split("#s2id_newEdgeDefinitions")[1]; + } + if (a.p.indexOf("#s2id_fromCollections") !== -1) { + return "fromCollection"; + } + if (a.p.indexOf("#s2id_toCollections") !== -1) { + return "toCollection"; + } + }, + attr : function () { + if (a.p.indexOf("edgeD") !== -1) { + return a.p; + } + }, + toArray: function () { + if (a.p === "[id^=s2id_newEdgeDefinitions]") { + return ["edgeD1", "edgeD2", "edgeD3"]; + } + }, + val : function () { + return "newName"; + } + }, g = { + _key: "name", + name: "name", + edgeDefinitions: [{ + collection: "blub", + from: ["bla"], + to: ["blob"] + },{ + collection: "collection2", + from: ["bla"], + to: ["blob"] + }], + orphanCollections: ["o1", "o2", "o3"], + get : function (a) { + return g[a]; + }, + deleteVertexCollection : function (o) { + g.orphanCollections.splice(g.orphanCollections.indexOf(o), 1); + }, + addVertexCollection : function (o) { + g.orphanCollections.push(o); + }, + addEdgeDefinition : function (o) { + g.edgeDefinitions.push(o); + }, + modifyEdgeDefinition : function (o) { + }, + deleteEdgeDefinition : function (o) { + g.edgeDefinitions.forEach(function (e) { + if (e.collection === o.collection) { + delete g.edgeDefinitions[e]; + } + }); + } + }; + + spyOn(_, "pluck").andCallFake(function (s, b) { + if (s === "newVertexCollections") { + return ["orphan1", "orphan2", "orphan3"]; + } + if (s.indexOf("edgeD") !== -1) { + return ["collection" + s.split("edgeD")[1] ]; + } + if (s === "fromCollection") { + return ["fromCollection"]; + } + if (s === "toCollection") { + return ["toCollection"]; + } + }); + + spyOn(window, "$").andCallFake(function (x) { + a.setParam(x); + return a; + }); + + spyOn(view.collection, "findWhere").andReturn( + undefined + ); + + spyOn(view, "updateGraphManagementView"); + + spyOn(view.collection, "create").andCallFake(function (a, b) { + b.success(); + }); + spyOn(window.modalView, "hide"); + view.createNewGraph(); + + expect(view.updateGraphManagementView).toHaveBeenCalled(); + + }); + + + it("should saveCreatedGraph but return an error", function () { + + var + a = { + p : "", + setParam : function (p) { + a.p = p; + }, + select2: function () { + if (a.p === "#newVertexCollections") { + return "newVertexCollections"; + } + if (a.p.indexOf("#s2id_newEdgeDefinitions") !== -1) { + return a.p.split("#s2id_newEdgeDefinitions")[1]; + } + if (a.p.indexOf("#s2id_fromCollections") !== -1) { + return "fromCollection"; + } + if (a.p.indexOf("#s2id_toCollections") !== -1) { + return "toCollection"; + } + }, + attr : function () { + if (a.p.indexOf("edgeD") !== -1) { + return a.p; + } + }, + toArray: function () { + if (a.p === "[id^=s2id_newEdgeDefinitions]") { + return ["edgeD1", "edgeD2", "edgeD3"]; + } + }, + val : function () { + return "newName"; + } + }, g = { + _key: "name", + name: "name", + edgeDefinitions: [{ + collection: "blub", + from: ["bla"], + to: ["blob"] + },{ + collection: "collection2", + from: ["bla"], + to: ["blob"] + }], + orphanCollections: ["o1", "o2", "o3"], + get : function (a) { + return g[a]; + }, + deleteVertexCollection : function (o) { + g.orphanCollections.splice(g.orphanCollections.indexOf(o), 1); + }, + addVertexCollection : function (o) { + g.orphanCollections.push(o); + }, + addEdgeDefinition : function (o) { + g.edgeDefinitions.push(o); + }, + modifyEdgeDefinition : function (o) { + }, + deleteEdgeDefinition : function (o) { + g.edgeDefinitions.forEach(function (e) { + if (e.collection === o.collection) { + delete g.edgeDefinitions[e]; + } + }); + } + }; + + spyOn(_, "pluck").andCallFake(function (s, b) { + if (s === "newVertexCollections") { + return ["orphan1", "orphan2", "orphan3"]; + } + if (s.indexOf("edgeD") !== -1) { + return ["collection" + s.split("edgeD")[1] ]; + } + if (s === "fromCollection") { + return ["fromCollection"]; + } + if (s === "toCollection") { + return ["toCollection"]; + } + }); + + spyOn(window, "$").andCallFake(function (x) { + a.setParam(x); + return a; + }); + + spyOn(view.collection, "findWhere").andReturn( + undefined + ); + + spyOn(view, "updateGraphManagementView"); + + spyOn(view.collection, "create").andCallFake(function (a, b) { + b.error(a, {responseText : '{"errorMessage" : "blub"}'}); + }); + spyOn(window.modalView, "hide"); + + spyOn(arangoHelper, "arangoError"); + + + view.createNewGraph(); + + expect(arangoHelper.arangoError).toHaveBeenCalledWith( + "blub"); + expect(view.updateGraphManagementView).not.toHaveBeenCalled(); + + }); + + + it("should not saveCreatedGraph as name is missing", function () { + + var + a = { + p : "", + setParam : function (p) { + a.p = p; + }, + select2: function () { + if (a.p === "#newVertexCollections") { + return "newVertexCollections"; + } + if (a.p.indexOf("#s2id_newEdgeDefinitions") !== -1) { + return a.p.split("#s2id_newEdgeDefinitions")[1]; + } + if (a.p.indexOf("#s2id_fromCollections") !== -1) { + return "fromCollection"; + } + if (a.p.indexOf("#s2id_toCollections") !== -1) { + return "toCollection"; + } + }, + attr : function () { + if (a.p.indexOf("edgeD") !== -1) { + return a.p; + } + }, + toArray: function () { + if (a.p === "[id^=s2id_newEdgeDefinitions]") { + return ["edgeD1", "edgeD2", "edgeD3"]; + } + }, + val : function () { + return undefined; + } + }, g = { + _key: "name", + name: "name", + edgeDefinitions: [{ + collection: "blub", + from: ["bla"], + to: ["blob"] + },{ + collection: "collection2", + from: ["bla"], + to: ["blob"] + }], + orphanCollections: ["o1", "o2", "o3"], + get : function (a) { + return g[a]; + }, + deleteVertexCollection : function (o) { + g.orphanCollections.splice(g.orphanCollections.indexOf(o), 1); + }, + addVertexCollection : function (o) { + g.orphanCollections.push(o); + }, + addEdgeDefinition : function (o) { + g.edgeDefinitions.push(o); + }, + modifyEdgeDefinition : function (o) { + }, + deleteEdgeDefinition : function (o) { + g.edgeDefinitions.forEach(function (e) { + if (e.collection === o.collection) { + delete g.edgeDefinitions[e]; + } + }); + } + }; + + spyOn(_, "pluck").andCallFake(function (s, b) { + if (s === "newVertexCollections") { + return ["orphan1", "orphan2", "orphan3"]; + } + if (s.indexOf("edgeD") !== -1) { + return ["collection" + s.split("edgeD")[1] ]; + } + if (s === "fromCollection") { + return ["fromCollection"]; + } + if (s === "toCollection") { + return ["toCollection"]; + } + }); + + spyOn(window, "$").andCallFake(function (x) { + a.setParam(x); + return a; + }); + + + spyOn(view.collection, "findWhere").andReturn( + g + ); + + spyOn(arangoHelper, "arangoError"); + + view.createNewGraph(); + + expect(arangoHelper.arangoError).toHaveBeenCalledWith( + "A name for the graph has to be provided."); + + + + }); describe("creating a new graph", function () { it("should create a new empty graph", function () { diff --git a/js/apps/system/gharial/gharial.js b/js/apps/system/gharial/gharial.js index 46e039023c..7012011a44 100644 --- a/js/apps/system/gharial/gharial.js +++ b/js/apps/system/gharial/gharial.js @@ -168,14 +168,19 @@ * well. */ controller.del("/:graph", function(req, res) { - var name = req.params("graph"); - Graph._drop(name); + var name = req.params("graph"), + drop = req.params("dropCollections") || false; + Graph._drop(name, Boolean(drop)); setResponse(res); }) .pathParam("graph", { type: "string", description: "Name of the graph." }) + .queryParam("dropCollections", { + type: "boolean", + description: "flag to drop collections as well" + }) .errorResponse( ArangoError, actions.HTTP_NOT_FOUND, "The graph does not exist.", function(e) { return { @@ -316,7 +321,8 @@ var name = req.params("graph"); var def_name = req.params("collection"); var g = Graph._graph(name); - g._removeVertexCollection(def_name); + var drop = req.params("dropCollections") || false; + g._removeVertexCollection(def_name, Boolean(drop)); setGraphResponse(res, g); }) .pathParam("graph", { @@ -327,6 +333,10 @@ type: "string", description: "Name of the vertex collection." }) + .queryParam("dropCollection", { + type: "boolean", + description: "flag to drop collection as well" + }) .errorResponse( ArangoError, actions.HTTP_BAD, "The collection is not found or part of an edge definition." @@ -511,7 +521,8 @@ var name = req.params("graph"); var def_name = req.params("definition"); var g = Graph._graph(name); - g._deleteEdgeDefinition(def_name); + var drop = req.params("dropCollections") || false; + g._deleteEdgeDefinition(def_name, Boolean(drop)); setGraphResponse(res, g); }) .pathParam("graph", { @@ -522,6 +533,10 @@ type: "string", description: "Name of the edge collection in the definition." }) + .queryParam("dropCollection", { + type: "boolean", + description: "flag to drop collection as well" + }) .errorResponse( ArangoError, actions.HTTP_NOT_FOUND, "The edge definition is invalid.", function(e) { return { diff --git a/js/common/modules/org/arangodb/general-graph.js b/js/common/modules/org/arangodb/general-graph.js index 6963e8ca6f..610d93a88f 100644 --- a/js/common/modules/org/arangodb/general-graph.js +++ b/js/common/modules/org/arangodb/general-graph.js @@ -3874,11 +3874,16 @@ var changeEdgeDefinitionsForGraph = function(graph, edgeDefinition, newCollectio var graphCollections = []; var graphObj = _graph(graph._key); var eDs = graph.edgeDefinitions; + var gotAHit = false; + require("internal").print("Graph: " + graph._key); //replace edgeDefintion eDs.forEach( function(eD, id) { if(eD.collection === edgeDefinition.collection) { + require("internal").print("eD.collection"); + require("internal").print(eD.collection); + gotAHit = true; oldCollections = _.union(oldCollections, eD.from); oldCollections = _.union(oldCollections, eD.to); eDs[id].from = edgeDefinition.from; @@ -3915,7 +3920,11 @@ var changeEdgeDefinitionsForGraph = function(graph, edgeDefinition, newCollectio //move unused collections to orphanage possibleOrphans.forEach( function(po) { - if (graphCollections.indexOf(po) === -1) { + require("internal").print(po); + require("internal").print(graphCollections.indexOf(po)); + require("internal").print(gotAHit); + if (graphCollections.indexOf(po) === -1 && gotAHit) { + require("internal").print("B I N D R I N ! ! !"); delete graphObj.__vertexCollections[po]; graphObj._addVertexCollection(po); } diff --git a/js/common/modules/org/arangodb/graph-common.js b/js/common/modules/org/arangodb/graph-common.js index 21700886ff..7f5c3bf8e5 100644 --- a/js/common/modules/org/arangodb/graph-common.js +++ b/js/common/modules/org/arangodb/graph-common.js @@ -388,12 +388,9 @@ Edge.prototype.getOutVertex = function () { /// @EXAMPLE_ARANGOSH_OUTPUT{edgeGetPeerVertex} /// ~ db._create("example"); /// v1 = example.addVertex("1"); -/// /// v2 = g.addVertex("2"); -/// -/// e = g.addEdge(v1, v2, "1->2", "knows"); -/// -/// e.getPeerVertex(v1); +/// e = g.addEdge(v1, v2, "1->2", "knows"); +/// e.getPeerVertex(v1); /// ~ db._drop("example"); /// @END_EXAMPLE_ARANGOSH_OUTPUT /// @endDocuBlock diff --git a/js/common/tests/shell-database.js b/js/common/tests/shell-database.js index ff822d48d4..22ac7d5ae6 100644 --- a/js/common/tests/shell-database.js +++ b/js/common/tests/shell-database.js @@ -44,7 +44,7 @@ function DatabaseSuite () { setUp : function () { internal.db._useDatabase("_system"); }, - + tearDown : function () { // always go back to system database internal.db._useDatabase("_system"); @@ -110,15 +110,15 @@ function DatabaseSuite () { //////////////////////////////////////////////////////////////////////////////// testExecuteTransaction1 : function () { - var result = internal.db._executeTransaction({ - collections: { }, + var result = internal.db._executeTransaction({ + collections: { }, action: function (params) { return params.v1 + params.v2; }, - params: { - "v1": 1, + params: { + "v1": 1, "v2": 2 - } + } }); assertEqual(3, result); @@ -129,12 +129,12 @@ function DatabaseSuite () { //////////////////////////////////////////////////////////////////////////////// testExecuteTransaction2 : function () { - var result = internal.db._executeTransaction({ - collections: { }, + var result = internal.db._executeTransaction({ + collections: { }, action: "function () { return params.v1[0] - params.v1[1]; }", - params: { - "v1": [ 10, 4 ], - } + params: { + "v1": [ 10, 4 ], + } }); assertEqual(6, result); @@ -146,16 +146,16 @@ function DatabaseSuite () { testListDatabases : function () { var actual, n; - + assertEqual("_system", internal.db._name()); actual = internal.db._listDatabases(); assertTrue(Array.isArray(actual)); n = actual.length; assertTrue(n > 0); - assertTrue(function () { - for (var i = 0; i < actual.length; ++i) { - if (actual[i] === "_system") { + assertTrue(function () { + for (var i = 0; i < actual.length; ++i) { + if (actual[i] === "_system") { return true; } } @@ -169,13 +169,13 @@ function DatabaseSuite () { } internal.db._createDatabase("UnitTestsDatabase0"); - + actual = internal.db._listDatabases(); assertTrue(Array.isArray(actual)); assertEqual(n + 1, actual.length); - assertTrue(function () { - for (var i = 0; i < actual.length; ++i) { - if (actual[i] === "UnitTestsDatabase0") { + assertTrue(function () { + for (var i = 0; i < actual.length; ++i) { + if (actual[i] === "UnitTestsDatabase0") { return true; } } @@ -197,7 +197,7 @@ function DatabaseSuite () { } catch (err1) { } - + try { internal.db._dropDatabase("UnitTestsDatabase1"); } @@ -206,7 +206,7 @@ function DatabaseSuite () { assertTrue(internal.db._createDatabase("UnitTestsDatabase0")); assertTrue(internal.db._createDatabase("UnitTestsDatabase1")); - + assertTrue(internal.db._dropDatabase("UnitTestsDatabase0")); assertTrue(internal.db._dropDatabase("UnitTestsDatabase1")); }, @@ -226,7 +226,7 @@ function DatabaseSuite () { // empty users assertTrue(internal.db._createDatabase("UnitTestsDatabase0", { }, [ ])); - + assertTrue(internal.db._dropDatabase("UnitTestsDatabase0")); }, @@ -243,7 +243,7 @@ function DatabaseSuite () { catch (err1) { } - var users = [ + var users = [ { username: "admin", passwd: "secret", extra: { gender: "m" } }, { username: "foo", active: false, extra: { gender: "f" } } ]; @@ -257,14 +257,14 @@ function DatabaseSuite () { assertEqual("admin", user.user); assertTrue(user.active); assertEqual("m", user.extra.gender); - + user = m.document("foo"); assertEqual("foo", user.user); assertFalse(user.active); assertEqual("f", user.extra.gender); internal.db._useDatabase("_system"); - + assertTrue(internal.db._dropDatabase("UnitTestsDatabase0")); }, @@ -281,9 +281,9 @@ function DatabaseSuite () { catch (err1) { } - var users = [ - { username: "admin", passwd: "secret", active: true, extra: { gender: "m" } }, - { username: "admin", passwd: "", active: false, extra: { gender: "m" } }, + var users = [ + { username: "admin", passwd: "secret", active: true, extra: { gender: "m" } }, + { username: "admin", passwd: "", active: false, extra: { gender: "m" } }, ]; assertTrue(internal.db._createDatabase("UnitTestsDatabase0", { }, users)); @@ -295,7 +295,7 @@ function DatabaseSuite () { assertEqual("m", user.extra.gender); internal.db._useDatabase("_system"); - + assertTrue(internal.db._dropDatabase("UnitTestsDatabase0")); }, @@ -342,7 +342,7 @@ function DatabaseSuite () { catch (err2) { assertEqual(ERRORS.ERROR_ARANGO_USE_SYSTEM_DATABASE.code, err2.errorNum); } - + // removing a database should fail here try { internal.db._dropDatabase("UnitTestsDatabase1"); @@ -351,7 +351,7 @@ function DatabaseSuite () { catch (err3) { assertEqual(ERRORS.ERROR_ARANGO_USE_SYSTEM_DATABASE.code, err3.errorNum); } - + internal.db._useDatabase("_system"); internal.db._dropDatabase("UnitTestsDatabase0"); }, @@ -378,7 +378,7 @@ function DatabaseSuite () { catch (err2) { assertEqual(ERRORS.ERROR_ARANGO_DUPLICATE_NAME.code, err2.errorNum); } - + internal.db._dropDatabase("UnitTestsDatabase0"); }, @@ -393,7 +393,7 @@ function DatabaseSuite () { var result = [ ]; internal.db._collections().forEach(function (c) { - if (c.name()[0] !== '_') { + if (c.name()[0] !== "_") { result.push(c.name()); } }); @@ -407,7 +407,7 @@ function DatabaseSuite () { } catch (err1) { } - + try { internal.db._dropDatabase("UNITTESTSDATABASE0"); } @@ -425,7 +425,7 @@ function DatabaseSuite () { assertEqual(1, internal.db._collection("test1").count()); assertEqual(1, c1.count()); - + internal.db._useDatabase("UNITTESTSDATABASE0"); assertEqual("UNITTESTSDATABASE0", internal.db._name()); var c2 = internal.db._create("test1"); @@ -440,7 +440,7 @@ function DatabaseSuite () { assertEqual(0, c1.count()); assertEqual(3, c2.count()); assertEqual(3, internal.db._collection("test1").count()); - + internal.db._useDatabase("UnitTestsDatabase0"); assertEqual(0, c1.count()); assertEqual(3, c2.count()); @@ -472,36 +472,36 @@ function DatabaseSuite () { } catch (err1) { } - + internal.db._createDatabase("UnitTestsDatabase0"); internal.db._useDatabase("UnitTestsDatabase0"); assertEqual("UnitTestsDatabase0", internal.db._name()); - + internal.db._useDatabase("UnitTestsDatabase0"); assertEqual("UnitTestsDatabase0", internal.db._name()); - + internal.db._useDatabase("_system"); assertEqual("_system", internal.db._name()); - + assertTrue(internal.db._dropDatabase("UnitTestsDatabase0")); - + try { internal.db._useDatabase("UnitTestsDatabase0"); fail(); } catch (err2) { - assertTrue(err2.errorNum === ERRORS.ERROR_ARANGO_DATABASE_NOT_FOUND.code || + assertTrue(err2.errorNum === ERRORS.ERROR_ARANGO_DATABASE_NOT_FOUND.code || err2.errorNum === ERRORS.ERROR_HTTP_NOT_FOUND.code); } - + assertEqual("_system", internal.db._name()); - + try { internal.db._useDatabase("THISDATABASEDOESNOTEXIST"); fail(); } catch (err3) { - assertTrue(err3.errorNum === ERRORS.ERROR_ARANGO_DATABASE_NOT_FOUND.code || + assertTrue(err3.errorNum === ERRORS.ERROR_ARANGO_DATABASE_NOT_FOUND.code || err3.errorNum === ERRORS.ERROR_HTTP_NOT_FOUND.code); } }, @@ -518,7 +518,7 @@ function DatabaseSuite () { } catch (err1) { } - + var isContained = function (name) { var l = internal.db._listDatabases(); for (var i = 0; i < l.length; ++i) { @@ -528,7 +528,7 @@ function DatabaseSuite () { } return false; }; - + internal.db._createDatabase("UnitTestsDatabase0"); assertTrue(isContained("UnitTestsDatabase0")); assertTrue(isContained("_system")); @@ -546,7 +546,7 @@ function DatabaseSuite () { var db = internal.db; var name = "UnitTestsCollectionCache"; - db._drop(name); + db._drop(name); db._create(name); @@ -555,20 +555,20 @@ function DatabaseSuite () { assertEqual(name, db[name].name()); assertEqual(1, db[name].count()); assertEqual(1, db[name].document("test").value); - + // remove the collection and re-create a new one with the same name db._drop(name); db._create(name); db[name].save({ _key: "foo", value: 1 }); db[name].save({ _key: "test", value: 2 }); - + assertNotEqual(cid, db[name]._id); assertEqual(name, db[name].name()); assertEqual(2, db[name].count()); assertEqual(1, db[name].document("foo").value); assertEqual(2, db[name].document("test").value); - + db._drop(name); try { @@ -591,18 +591,18 @@ function DatabaseSuite () { assertTrue("_system", db._name()); - db._drop(name); + db._drop(name); db._create(name); db[name].save({ _key: "foo", value: 1 }); var cid = db[name]._id; assertEqual(name, db[name].name()); assertEqual(1, db[name].count()); - + // switch the database db._createDatabase("UnitTestsDatabase0"); db._useDatabase("UnitTestsDatabase0"); - + // collection should not yet exist in other database try { db[name].save({ _key: "foo", value: 1 }); @@ -624,7 +624,7 @@ function DatabaseSuite () { db._useDatabase("_system"); assertEqual(1, db[name].count()); - + db._dropDatabase("UnitTestsDatabase0"); } diff --git a/js/common/tests/shell-users.js b/js/common/tests/shell-users.js index de15c55fc1..a060a90a06 100644 --- a/js/common/tests/shell-users.js +++ b/js/common/tests/shell-users.js @@ -54,6 +54,7 @@ function UsersSuite () { users.remove(username); } catch (e1) { + // nope } } @@ -61,6 +62,7 @@ function UsersSuite () { users.remove("hackers@arangodb.org"); } catch (e2) { + // nope } }; @@ -71,7 +73,7 @@ function UsersSuite () { //////////////////////////////////////////////////////////////////////////////// setUp : function () { - clearGarbage(); + clearGarbage(); }, //////////////////////////////////////////////////////////////////////////////// @@ -79,11 +81,11 @@ function UsersSuite () { //////////////////////////////////////////////////////////////////////////////// tearDown : function () { - clearGarbage(); + clearGarbage(); }, //////////////////////////////////////////////////////////////////////////////// -/// @brief test invalid names +/// @brief test invalid names //////////////////////////////////////////////////////////////////////////////// testInvalidNames : function () { @@ -92,7 +94,7 @@ function UsersSuite () { for (var i = 0; i < usernames.length; ++i) { var username = usernames[i]; var passwd = "passwd-" + i; - + try { users.save(username, passwd); fail(); diff --git a/js/server/modules/org/arangodb/foxx/authentication.js b/js/server/modules/org/arangodb/foxx/authentication.js index 6d8fd40dce..1d37ad720d 100644 --- a/js/server/modules/org/arangodb/foxx/authentication.js +++ b/js/server/modules/org/arangodb/foxx/authentication.js @@ -821,7 +821,7 @@ Sessions.prototype._toObject = function (session) { if (!this._changed) { oldExpires = this.expires; - newExpires = internal.time() + that._options.lifetime; + newExpires = internal.time() + that._options.sessionLifetime; if (newExpires - oldExpires > that._options.minUpdateResolution) { this.expires = newExpires; @@ -917,8 +917,8 @@ Sessions.prototype.generate = function (identifier, data) { throw new TypeError("invalid type for 'identifier'"); } - if (!this._options.hasOwnProperty("lifetime")) { - throw new Error("no value specified for 'lifetime'"); + if (!this._options.hasOwnProperty("sessionLifetime")) { + throw new Error("no value specified for 'sessionLifetime'"); } storage = this.storage(); @@ -934,7 +934,7 @@ Sessions.prototype.generate = function (identifier, data) { token = generateToken(); session = { _key: token, - expires: internal.time() + this._options.lifetime, + expires: internal.time() + this._options.sessionLifetime, identifier: identifier, data: data || {} }; @@ -963,7 +963,7 @@ Sessions.prototype.update = function (token, data) { 'use strict'; this.storage().update(token, { - expires: internal.time() + this._options.lifetime, + expires: internal.time() + this._options.sessionLifetime, data: data }, true, false); }; @@ -990,7 +990,7 @@ Sessions.prototype.get = function (token) { 'use strict'; var storage = this.storage(), session, - lifetime; + sessionLifetime; try { session = storage.document(token); @@ -998,7 +998,7 @@ Sessions.prototype.get = function (token) { if (session.expires >= internal.time()) { // session still valid - lifetime = this._options.lifetime; + sessionLifetime = this._options.sessionLifetime; return { errorNum: internal.errors.ERROR_NO_ERROR, @@ -1049,7 +1049,7 @@ CookieAuthentication = function (applicationContext, options) { this._options = { name: options.name || this._applicationContext.name + "-session", - lifetime: options.lifetime || 3600, + cookieLifetime: options.cookieLifetime || 3600, path: options.path || "/", domain: options.path || undefined, secure: options.secure || false, @@ -1105,7 +1105,7 @@ CookieAuthentication.prototype.setCookie = function (res, value) { cookie = { name: name, value: value, - lifeTime: (value === null || value === "") ? 0 : this._options.lifetime, + lifeTime: (value === null || value === "") ? 0 : this._options.cookieLifetime, path: this._options.path, secure: this._options.secure, domain: this._options.domain, diff --git a/js/server/modules/org/arangodb/foxx/base_middleware.js b/js/server/modules/org/arangodb/foxx/base_middleware.js index d1cce8e7a2..a0fada33c7 100644 --- a/js/server/modules/org/arangodb/foxx/base_middleware.js +++ b/js/server/modules/org/arangodb/foxx/base_middleware.js @@ -144,7 +144,6 @@ BaseMiddleware = function () { /// "Content-Type": "text/plain" /// }); /// ``` -/// @endcode /// @endDocuBlock //////////////////////////////////////////////////////////////////////////////// diff --git a/js/server/modules/org/arangodb/testing.js b/js/server/modules/org/arangodb/testing.js index 788bed42c7..b26d22f660 100644 --- a/js/server/modules/org/arangodb/testing.js +++ b/js/server/modules/org/arangodb/testing.js @@ -754,25 +754,29 @@ testFuncs.foxx_manager = function (options) { }; testFuncs.dump = function (options) { + var cluster; + if (options.cluster) { - print("Skipped because of cluster."); - return {"ok":true, "skipped":0}; + cluster = "-cluster"; + } + else { + cluster = ""; } print("dump tests..."); var instanceInfo = startInstance("tcp",options); var results = {}; results.setup = runInArangosh(options, instanceInfo, - makePath("js/server/tests/dump-setup.js")); + makePath("js/server/tests/dump-setup"+cluster+".js")); if (results.setup === 0) { results.dump = runArangoDumpRestore(options, instanceInfo, "dump", "UnitTestsDumpSrc"); results.restore = runArangoDumpRestore(options, instanceInfo, "restore", "UnitTestsDumpDst"); results.test = runInArangosh(options, instanceInfo, - makePath("js/server/tests/dump.js"), - [ "--server.database", "UnitTestsDumpDst" ]); + makePath("js/server/tests/dump"+cluster+".js"), + [ "--server.database", "UnitTestsDumpDst" ]); results.tearDown = runInArangosh(options, instanceInfo, - makePath("js/server/tests/dump-teardown.js")); + makePath("js/server/tests/dump-teardown"+cluster+".js")); } print("Shutting down..."); shutdownInstance(instanceInfo,options); diff --git a/js/server/tests/dump-cluster.js b/js/server/tests/dump-cluster.js new file mode 100644 index 0000000000..e65e343bc4 --- /dev/null +++ b/js/server/tests/dump-cluster.js @@ -0,0 +1,344 @@ +//////////////////////////////////////////////////////////////////////////////// +/// @brief tests for dump/reload +/// +/// @file +/// +/// DISCLAIMER +/// +/// Copyright 2010-2012 triagens GmbH, Cologne, Germany +/// +/// Licensed under the Apache License, Version 2.0 (the "License"); +/// you may not use this file except in compliance with the License. +/// You may obtain a copy of the License at +/// +/// http://www.apache.org/licenses/LICENSE-2.0 +/// +/// Unless required by applicable law or agreed to in writing, software +/// distributed under the License is distributed on an "AS IS" BASIS, +/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +/// See the License for the specific language governing permissions and +/// limitations under the License. +/// +/// Copyright holder is triAGENS GmbH, Cologne, Germany +/// +/// @author Jan Steemann +/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany +//////////////////////////////////////////////////////////////////////////////// + +var internal = require("internal"); +var jsunity = require("jsunity"); + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test suite +//////////////////////////////////////////////////////////////////////////////// + +function dumpTestSuite () { + var db = internal.db; + + return { + +//////////////////////////////////////////////////////////////////////////////// +/// @brief set up +//////////////////////////////////////////////////////////////////////////////// + + setUp : function () { + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief tear down +//////////////////////////////////////////////////////////////////////////////// + + tearDown : function () { + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test the empty collection +//////////////////////////////////////////////////////////////////////////////// + + testEmpty : function () { + var c = db._collection("UnitTestsDumpEmpty"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertTrue(p.waitForSync); + assertFalse(p.isVolatile); + + assertEqual(1, c.getIndexes().length); // just primary index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual(0, c.count()); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test the collection with many documents +//////////////////////////////////////////////////////////////////////////////// + + testMany : function () { + var c = db._collection("UnitTestsDumpMany"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertFalse(p.waitForSync); + assertFalse(p.isVolatile); + + assertEqual(1, c.getIndexes().length); // just primary index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual(100000, c.count()); + + var doc; + var i; + + // test all documents + for (i = 0; i < 100000; ++i) { + doc = c.document("test" + i); + assertEqual(i, doc.value1); + assertEqual("this is a test", doc.value2); + assertEqual("test" + i, doc.value3); + } + + doc = c.first(); + assertEqual("test0", doc._key); + assertEqual(0, doc.value1); + assertEqual("this is a test", doc.value2); + assertEqual("test0", doc.value3); + + doc = c.last(); + assertEqual("test99999", doc._key); + assertEqual(99999, doc.value1); + assertEqual("this is a test", doc.value2); + assertEqual("test99999", doc.value3); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test the edges collection +//////////////////////////////////////////////////////////////////////////////// + + testEdges : function () { + var c = db._collection("UnitTestsDumpEdges"); + var p = c.properties(); + + assertEqual(3, c.type()); // edges + assertFalse(p.waitForSync); + assertFalse(p.isVolatile); + + assertEqual(2, c.getIndexes().length); // primary index + edges index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual("edge", c.getIndexes()[1].type); + assertEqual(10, c.count()); + + var doc; + var i; + + // test all documents + for (i = 0; i < 10; ++i) { + doc = c.document("test" + i); + assertEqual("test" + i, doc._key); + assertEqual("UnitTestsDumpMany/test" + i, doc._from); + assertEqual("UnitTestsDumpMany/test" + (i + 1), doc._to); + assertEqual(i + "->" + (i + 1), doc.what); + } + + doc = c.first(); + assertEqual("test0", doc._key); + assertEqual("UnitTestsDumpMany/test0", doc._from); + assertEqual("UnitTestsDumpMany/test1", doc._to); + assertEqual("0->1", doc.what); + + doc = c.last(); + assertEqual("test9", doc._key); + assertEqual("UnitTestsDumpMany/test9", doc._from); + assertEqual("UnitTestsDumpMany/test10", doc._to); + assertEqual("9->10", doc.what); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test the order of documents +//////////////////////////////////////////////////////////////////////////////// + + testOrder : function () { + var c = db._collection("UnitTestsDumpOrder"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertFalse(p.waitForSync); + assertFalse(p.isVolatile); + + assertEqual(1, c.getIndexes().length); // just primary index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual(3, c.count()); + + var doc; + + doc = c.first(); + assertEqual("three", doc._key); + assertEqual(3, doc.value); + assertEqual(123, doc.value2); + + doc = c.first(2)[1]; + assertEqual("two", doc._key); + assertEqual(2, doc.value); + assertEqual(456, doc.value2); + + doc = c.first(3)[2]; + assertEqual("one", doc._key); + assertEqual(1, doc.value); + assertEqual(789, doc.value2); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test document removal & update +//////////////////////////////////////////////////////////////////////////////// + + testRemoved : function () { + var c = db._collection("UnitTestsDumpRemoved"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertFalse(p.waitForSync); + assertFalse(p.isVolatile); + + assertEqual(1, c.getIndexes().length); // just primary index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual(9000, c.count()); + + var i; + for (i = 0; i < 10000; ++i) { + if (i % 10 === 0) { + assertFalse(c.exists("test" + i)); + } + else { + var doc = c.document("test" + i); + assertEqual(i, doc.value1); + + if (i < 1000) { + assertEqual(i + 1, doc.value2); + } + } + } + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test indexes +//////////////////////////////////////////////////////////////////////////////// + + testIndexes : function () { + var c = db._collection("UnitTestsDumpIndexes"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertFalse(p.waitForSync); + assertFalse(p.isVolatile); + + assertEqual(6, c.getIndexes().length); + assertEqual("primary", c.getIndexes()[0].type); + assertEqual("hash", c.getIndexes()[1].type); + assertTrue(c.getIndexes()[1].unique); + assertEqual([ "a_uc" ], c.getIndexes()[1].fields); + assertEqual("skiplist", c.getIndexes()[2].type); + assertFalse(c.getIndexes()[2].unique); + assertEqual([ "a_s1", "a_s2" ], c.getIndexes()[2].fields); + assertFalse(c.getIndexes()[3].unique); + assertEqual("fulltext", c.getIndexes()[3].type); + assertEqual([ "a_f" ], c.getIndexes()[3].fields); + assertEqual("geo2", c.getIndexes()[4].type); + assertEqual([ "a_la", "a_lo" ], c.getIndexes()[4].fields); + assertFalse(c.getIndexes()[4].unique); + assertEqual("cap", c.getIndexes()[5].type); + assertEqual(1000, c.getIndexes()[5].size); + assertEqual(1048576, c.getIndexes()[5].byteSize); + + assertEqual(0, c.count()); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test truncate +//////////////////////////////////////////////////////////////////////////////// + + testTruncated : function () { + var c = db._collection("UnitTestsDumpTruncated"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertFalse(p.waitForSync); + assertTrue(p.isVolatile); + + assertEqual(1, c.getIndexes().length); // just primary index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual(0, c.count()); + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test shards +//////////////////////////////////////////////////////////////////////////////// + + testShards : function () { + var c = db._collection("UnitTestsDumpShards"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertFalse(p.waitForSync); + assertFalse(p.isVolatile); + assertEqual(9, p.numberOfShards); + + assertEqual(1, c.getIndexes().length); // just primary index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual(1000, c.count()); + + for (var i = 0; i < 1000; ++i) { + var doc = c.document(String(7 + (i * 42))); + + assertEqual(String(7 + (i * 42)), doc._key); + assertEqual(i, doc.value); + assertEqual({ value: [ i, i ] }, doc.more); + } + }, + +//////////////////////////////////////////////////////////////////////////////// +/// @brief test strings +//////////////////////////////////////////////////////////////////////////////// + + testStrings : function () { + var c = db._collection("UnitTestsDumpStrings"); + var p = c.properties(); + + assertEqual(2, c.type()); // document + assertFalse(p.waitForSync); + assertFalse(p.isVolatile); + + assertEqual(1, c.getIndexes().length); // just primary index + assertEqual("primary", c.getIndexes()[0].type); + assertEqual(8, c.count()); + + var texts = [ + "big. Really big. He moment. Magrathea! - insisted Arthur, - I do you can sense no further because it doesn't fit properly. In my the denies faith, and the atmosphere beneath You are not cheap He was was his satchel. He throughout Magrathea. - He pushed a tore the ecstatic crowd. Trillian sat down the time, the existence is it? And he said, - What they don't want this airtight hatchway. - it's we you shooting people would represent their Poet Master Grunthos is in his mind.", + "Ultimo cadere chi sedete uso chiuso voluto ora. Scotendosi portartela meraviglia ore eguagliare incessante allegrezza per. Pensava maestro pungeva un le tornano ah perduta. Fianco bearmi storia soffio prende udi poteva una. Cammino fascino elisire orecchi pollici mio cui sai sul. Chi egli sino sei dita ben. Audace agonie groppa afa vai ultima dentro scossa sii. Alcuni mia blocco cerchi eterno andare pagine poi. Ed migliore di sommesso oh ai angoscia vorresti.", + "Νέο βάθος όλα δομές της χάσει. Μέτωπο εγώ συνάμα τρόπος και ότι όσο εφόδιο κόσμου. Προτίμηση όλη διάφορους του όλο εύθραυστη συγγραφής. Στα άρα ένα μία οποία άλλων νόημα. Ένα αποβαίνει ρεαλισμού μελετητές θεόσταλτο την. Ποντιακών και rites κοριτσάκι παπούτσια παραμύθια πει κυρ.", + "Mody laty mnie ludu pole rury Białopiotrowiczowi. Domy puer szczypię jemy pragnął zacność czytając ojca lasy Nowa wewnątrz klasztoru. Chce nóg mego wami. Zamku stał nogą imion ludzi ustaw Białopiotrowiczem. Kwiat Niesiołowskiemu nierostrzygniony Staje brał Nauka dachu dumę Zamku Kościuszkowskie zagon. Jakowaś zapytać dwie mój sama polu uszakach obyczaje Mój. Niesiołowski książkowéj zimny mały dotychczasowa Stryj przestraszone Stolnikównie wdał śmiertelnego. Stanisława charty kapeluszach mięty bratem każda brząknął rydwan.", + "Мелких против летают хижину тмится. Чудесам возьмет звездна Взжигай. . Податель сельские мучитель сверкает очищаясь пламенем. Увы имя меч Мое сия. Устранюсь воздушных Им от До мысленные потушатся Ко Ея терпеньем.", + "dotyku. Výdech spalin bude položen záplavový detekční kabely 1x UPS Newave Conceptpower DPA 5x 40kVA bude ukončen v samostatné strojovně. Samotné servery mají pouze lokalita Ústí nad zdvojenou podlahou budou zakončené GateWayí HiroLink - Monitoring rozvaděče RTN na jednotlivých záplavových zón na soustrojí resp. technologie jsou označeny SA-MKx.y. Jejich výstupem je zajištěn přestupem dat z jejich provoz. Na dveřích vylepené výstražné tabulky. Kabeláž z okruhů zálohovaných obvodů v R.MON-I. Monitoring EZS, EPS, ... možno zajistit funkčností FireWallů na strukturovanou kabeláží vedenou v měrných jímkách zapuštěných v každém racku budou zakončeny v R.MON-NrNN. Monitoring motorgenerátorů: řídící systém bude zakončena v modulu", + "ramien mu zrejme vôbec niekto je už presne čo mám tendenciu prispôsobiť dych jej páčil, čo chce. Hmm... Včera sa mi pozdava, len dočkali, ale keďže som na uz boli u jej nezavrela. Hlava jej to ve městě nepotká, hodně mi to tí vedci pri hre, keď je tu pre Designiu. Pokiaľ viete o odbornejšie texty. Prvým z tmavých uličiek, každý to niekedy, zrovnávať krok s obrovským batohom na okraj vane a temné úmysly, tak rozmýšľam, aký som si hromady mailov, čo chcem a neraz sa pokúšal o filmovém klubu v budúcnosti rozhodne uniesť mladú maliarku (Linda Rybová), ktorú so", + " 復讐者」. 復讐者」. 伯母さん 復讐者」. 復讐者」. 復讐者」. 復讐者」. 第九章 第五章 第六章 第七章 第八章. 復讐者」 伯母さん. 復讐者」 伯母さん. 第十一章 第十九章 第十四章 第十八章 第十三章 第十五章. 復讐者」 . 第十四章 第十一章 第十二章 第十五章 第十七章 手配書. 第十四章 手配書 第十八章 第十七章 第十六章 第十三章. 第十一章 第十三章 第十八章 第十四章 手配書. 復讐者」." + ]; + + texts.forEach(function (t, i) { + var doc = c.document("text" + i); + + assertEqual(t, doc.value); + }); + + } + + }; +} + +//////////////////////////////////////////////////////////////////////////////// +/// @brief executes the test suite +//////////////////////////////////////////////////////////////////////////////// + +jsunity.run(dumpTestSuite); + +return jsunity.done(); + +// Local Variables: +// mode: outline-minor +// outline-regexp: "^\\(/// @brief\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @}\\)" +// End: diff --git a/js/server/tests/dump-setup-cluster.js b/js/server/tests/dump-setup-cluster.js new file mode 100644 index 0000000000..a3b5d51168 --- /dev/null +++ b/js/server/tests/dump-setup-cluster.js @@ -0,0 +1,143 @@ +//////////////////////////////////////////////////////////////////////////////// +/// @brief setup collections for dump/reload tests +/// +/// @file +/// +/// DISCLAIMER +/// +/// Copyright 2010-2012 triagens GmbH, Cologne, Germany +/// +/// Licensed under the Apache License, Version 2.0 (the "License"); +/// you may not use this file except in compliance with the License. +/// You may obtain a copy of the License at +/// +/// http://www.apache.org/licenses/LICENSE-2.0 +/// +/// Unless required by applicable law or agreed to in writing, software +/// distributed under the License is distributed on an "AS IS" BASIS, +/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +/// See the License for the specific language governing permissions and +/// limitations under the License. +/// +/// Copyright holder is triAGENS GmbH, Cologne, Germany +/// +/// @author Jan Steemann +/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany +//////////////////////////////////////////////////////////////////////////////// + +(function () { + var db = require("org/arangodb").db; + var i, c; + + try { + db._dropDatabase("UnitTestsDumpSrc"); + } + catch (err1) { + } + db._createDatabase("UnitTestsDumpSrc"); + + try { + db._dropDatabase("UnitTestsDumpDst"); + } + catch (err2) { + } + db._createDatabase("UnitTestsDumpDst"); + + + db._useDatabase("UnitTestsDumpSrc"); + + // clean up first + db._drop("UnitTestsDumpEmpty"); + db._drop("UnitTestsDumpMany"); + db._drop("UnitTestsDumpEdges"); + db._drop("UnitTestsDumpOrder"); + db._drop("UnitTestsDumpRemoved"); + db._drop("UnitTestsDumpIndexes"); + db._drop("UnitTestsDumpTruncated"); + db._drop("UnitTestsDumpShards"); + db._drop("UnitTestsDumpStrings"); + + // this remains empty + db._create("UnitTestsDumpEmpty", { waitForSync: true }); + + // create lots of documents + c = db._create("UnitTestsDumpMany"); + for (i = 0; i < 100000; ++i) { + c.save({ _key: "test" + i, value1: i, value2: "this is a test", value3: "test" + i }); + } + + c = db._createEdgeCollection("UnitTestsDumpEdges"); + for (i = 0; i < 10; ++i) { + c.save("UnitTestsDumpMany/test" + i, "UnitTestsDumpMany/test" + (i + 1), { _key: "test" + i, what: i + "->" + (i + 1) }); + } + + // we update & modify the order + c = db._create("UnitTestsDumpOrder"); + c.save({ _key: "one", value: 1 }); + c.save({ _key: "two", value: 2 }); + c.save({ _key: "three", value: 3 }); + c.save({ _key: "four", value: 4 }); + + c.update("three", { value: 3, value2: 123 }); + c.update("two", { value: 2, value2: 456 }); + c.update("one", { value: 1, value2: 789 }); + c.remove("four"); + + // we apply a series of updates & removals here + c = db._create("UnitTestsDumpRemoved"); + for (i = 0; i < 10000; ++i) { + c.save({ _key: "test" + i, value1: i }); + } + for (i = 0; i < 1000; ++i) { + c.update("test" + i, { value2: i + 1 }); + } + for (i = 0; i < 10000; i += 10) { + c.remove("test" + i); + } + + // we create a lot of (meaningless) indexes here + c = db._create("UnitTestsDumpIndexes"); + c.ensureUniqueConstraint("a_uc"); + c.ensureSkiplist("a_s1", "a_s2"); + c.ensureFulltextIndex("a_f"); + c.ensureGeoIndex("a_la", "a_lo"); + c.ensureCapConstraint(1000, 1048576); + + // we insert data and remove it + c = db._create("UnitTestsDumpTruncated", { isVolatile: true }); + for (i = 0; i < 10000; ++i) { + c.save({ _key: "test" + i, value1: i, value2: "this is a test", value3: "test" + i }); + } + c.truncate(); + + // more than one shard: + c = db._create("UnitTestsDumpShards", { numberOfShards : 9 }); + for (i = 0; i < 1000; ++i) { + c.save({ _key : String(7 + (i*42)), value: i, more: { value: [ i, i ] } }); + } + + // strings + c = db._create("UnitTestsDumpStrings"); + var texts = [ + "big. Really big. He moment. Magrathea! - insisted Arthur, - I do you can sense no further because it doesn't fit properly. In my the denies faith, and the atmosphere beneath You are not cheap He was was his satchel. He throughout Magrathea. - He pushed a tore the ecstatic crowd. Trillian sat down the time, the existence is it? And he said, - What they don't want this airtight hatchway. - it's we you shooting people would represent their Poet Master Grunthos is in his mind.", + "Ultimo cadere chi sedete uso chiuso voluto ora. Scotendosi portartela meraviglia ore eguagliare incessante allegrezza per. Pensava maestro pungeva un le tornano ah perduta. Fianco bearmi storia soffio prende udi poteva una. Cammino fascino elisire orecchi pollici mio cui sai sul. Chi egli sino sei dita ben. Audace agonie groppa afa vai ultima dentro scossa sii. Alcuni mia blocco cerchi eterno andare pagine poi. Ed migliore di sommesso oh ai angoscia vorresti.", + "Νέο βάθος όλα δομές της χάσει. Μέτωπο εγώ συνάμα τρόπος και ότι όσο εφόδιο κόσμου. Προτίμηση όλη διάφορους του όλο εύθραυστη συγγραφής. Στα άρα ένα μία οποία άλλων νόημα. Ένα αποβαίνει ρεαλισμού μελετητές θεόσταλτο την. Ποντιακών και rites κοριτσάκι παπούτσια παραμύθια πει κυρ.", + "Mody laty mnie ludu pole rury Białopiotrowiczowi. Domy puer szczypię jemy pragnął zacność czytając ojca lasy Nowa wewnątrz klasztoru. Chce nóg mego wami. Zamku stał nogą imion ludzi ustaw Białopiotrowiczem. Kwiat Niesiołowskiemu nierostrzygniony Staje brał Nauka dachu dumę Zamku Kościuszkowskie zagon. Jakowaś zapytać dwie mój sama polu uszakach obyczaje Mój. Niesiołowski książkowéj zimny mały dotychczasowa Stryj przestraszone Stolnikównie wdał śmiertelnego. Stanisława charty kapeluszach mięty bratem każda brząknął rydwan.", + "Мелких против летают хижину тмится. Чудесам возьмет звездна Взжигай. . Податель сельские мучитель сверкает очищаясь пламенем. Увы имя меч Мое сия. Устранюсь воздушных Им от До мысленные потушатся Ко Ея терпеньем.", + "dotyku. Výdech spalin bude položen záplavový detekční kabely 1x UPS Newave Conceptpower DPA 5x 40kVA bude ukončen v samostatné strojovně. Samotné servery mají pouze lokalita Ústí nad zdvojenou podlahou budou zakončené GateWayí HiroLink - Monitoring rozvaděče RTN na jednotlivých záplavových zón na soustrojí resp. technologie jsou označeny SA-MKx.y. Jejich výstupem je zajištěn přestupem dat z jejich provoz. Na dveřích vylepené výstražné tabulky. Kabeláž z okruhů zálohovaných obvodů v R.MON-I. Monitoring EZS, EPS, ... možno zajistit funkčností FireWallů na strukturovanou kabeláží vedenou v měrných jímkách zapuštěných v každém racku budou zakončeny v R.MON-NrNN. Monitoring motorgenerátorů: řídící systém bude zakončena v modulu", + "ramien mu zrejme vôbec niekto je už presne čo mám tendenciu prispôsobiť dych jej páčil, čo chce. Hmm... Včera sa mi pozdava, len dočkali, ale keďže som na uz boli u jej nezavrela. Hlava jej to ve městě nepotká, hodně mi to tí vedci pri hre, keď je tu pre Designiu. Pokiaľ viete o odbornejšie texty. Prvým z tmavých uličiek, každý to niekedy, zrovnávať krok s obrovským batohom na okraj vane a temné úmysly, tak rozmýšľam, aký som si hromady mailov, čo chcem a neraz sa pokúšal o filmovém klubu v budúcnosti rozhodne uniesť mladú maliarku (Linda Rybová), ktorú so", + " 復讐者」. 復讐者」. 伯母さん 復讐者」. 復讐者」. 復讐者」. 復讐者」. 第九章 第五章 第六章 第七章 第八章. 復讐者」 伯母さん. 復讐者」 伯母さん. 第十一章 第十九章 第十四章 第十八章 第十三章 第十五章. 復讐者」 . 第十四章 第十一章 第十二章 第十五章 第十七章 手配書. 第十四章 手配書 第十八章 第十七章 第十六章 第十三章. 第十一章 第十三章 第十八章 第十四章 手配書. 復讐者」." + ]; + + texts.forEach(function (t, i) { + c.save({ _key: "text" + i, value: t }); + }); + +})(); + +return true; + +// Local Variables: +// mode: outline-minor +// outline-regexp: "^\\(/// @brief\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @}\\)" +// End: diff --git a/js/server/tests/dump-teardown-cluster.js b/js/server/tests/dump-teardown-cluster.js new file mode 100644 index 0000000000..16b98f2022 --- /dev/null +++ b/js/server/tests/dump-teardown-cluster.js @@ -0,0 +1,40 @@ +//////////////////////////////////////////////////////////////////////////////// +/// @brief teardown for dump/reload tests +/// +/// @file +/// +/// DISCLAIMER +/// +/// Copyright 2010-2012 triagens GmbH, Cologne, Germany +/// +/// Licensed under the Apache License, Version 2.0 (the "License"); +/// you may not use this file except in compliance with the License. +/// You may obtain a copy of the License at +/// +/// http://www.apache.org/licenses/LICENSE-2.0 +/// +/// Unless required by applicable law or agreed to in writing, software +/// distributed under the License is distributed on an "AS IS" BASIS, +/// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +/// See the License for the specific language governing permissions and +/// limitations under the License. +/// +/// Copyright holder is triAGENS GmbH, Cologne, Germany +/// +/// @author Jan Steemann +/// @author Copyright 2012, triAGENS GmbH, Cologne, Germany +//////////////////////////////////////////////////////////////////////////////// + +(function () { + var db = require("org/arangodb").db; + + db._dropDatabase("UnitTestsDumpSrc"); + db._dropDatabase("UnitTestsDumpDst"); +})(); + +return true; + +// Local Variables: +// mode: outline-minor +// outline-regexp: "^\\(/// @brief\\|/// @addtogroup\\|// --SECTION--\\|/// @page\\|/// @}\\)" +// End: diff --git a/js/server/version-check.js b/js/server/version-check.js index 8887a1939a..b1951b8c0d 100755 --- a/js/server/version-check.js +++ b/js/server/version-check.js @@ -5,7 +5,7 @@ /// @brief version check at the start of the server /// /// @file -/// +/// /// Version check at the start of the server, will optionally perform necessary /// upgrades. /// @@ -78,7 +78,7 @@ var activeTasks = []; var lastVersion = null; var lastTasks = {}; - + function getCollection (name) { return db._collection(name); } @@ -102,7 +102,7 @@ return collectionExists(name); } - + // helper function to define a task function addTask (name, description, fn, always) { // "description" is a textual description of the task that will be printed out on screen @@ -164,12 +164,12 @@ // we assume that we are initialising a new, empty database isInitialisation = true; } - + var procedure = isInitialisation ? "initialisation" : "upgrade"; - + if (upgradeRun) { - if (! isInitialisation) { - logger.log("starting upgrade from version " + (lastVersion || "unknown") + if (! isInitialisation) { + logger.log("starting upgrade from version " + (lastVersion || "unknown") + " to " + internal.db._version()); } } @@ -178,7 +178,7 @@ // -------------------------------------------------------------------------- // the actual upgrade tasks. all tasks defined here should be "re-entrant" // -------------------------------------------------------------------------- - + //////////////////////////////////////////////////////////////////////////////// /// @brief moveProductionApps //////////////////////////////////////////////////////////////////////////////// @@ -197,7 +197,7 @@ } if (! module.basePaths().appPath) { - logger.error("no app-path has been specified."); + logger.error("no app-path has been specified."); return false; } @@ -206,9 +206,9 @@ for (i = 0; i < n; ++i) { var found = files[i]; - if (found === '' || - found === 'system' || - found === 'databases' || + if (found === '' || + found === 'system' || + found === 'databases' || found === 'aardvark' || found[0] === '.') { continue; @@ -230,13 +230,13 @@ return true; }); - + //////////////////////////////////////////////////////////////////////////////// /// @brief moveDevApps //////////////////////////////////////////////////////////////////////////////// if (internal.developmentMode) { - addUpgradeTask("moveDevApps", + addUpgradeTask("moveDevApps", "move Foxx development apps into per-database directory", function () { var dir = module.devAppPath(); @@ -244,14 +244,14 @@ logger.error("dev apps directory '" + dir + "' does not exist."); return false; } - + // we only need to move apps in the _system database if (db._name() !== '_system') { return true; } if (! module.basePaths().devAppPath) { - logger.error("no dev-app-path has been specified."); + logger.error("no dev-app-path has been specified."); return false; } @@ -259,10 +259,10 @@ for (i = 0; i < n; ++i) { var found = files[i]; - if (found === '' || - found === 'system' || - found === 'databases' || - found === 'aardvark' || + if (found === '' || + found === 'system' || + found === 'databases' || + found === 'aardvark' || found[0] === '.') { continue; } @@ -330,9 +330,8 @@ foundUser = true; try { userManager.save(user.username, user.passwd, user.active, user.extra || {}); - } - catch (err) { - logger.warn("could not add database user '" + user.username + "': " + + } catch (err) { + logger.warn("could not add database user '" + user.username + "': " + String(err.stack || err)); } }); @@ -352,12 +351,12 @@ // set up the collection _graphs addTask("setupGraphs", "setup _graphs collection", function () { - return createSystemCollection("_graphs", { + return createSystemCollection("_graphs", { waitForSync : true, - journalSize: 1024 * 1024 + journalSize: 1024 * 1024 }); }); - + //////////////////////////////////////////////////////////////////////////////// /// @brief addCollectionVersion //////////////////////////////////////////////////////////////////////////////// @@ -420,7 +419,7 @@ return true; } ); - + //////////////////////////////////////////////////////////////////////////////// /// @brief createModules //////////////////////////////////////////////////////////////////////////////// @@ -428,10 +427,10 @@ // create the _modules collection addTask("createModules", "setup _modules collection", function () { return createSystemCollection("_modules", { - journalSize: 1024 * 1024 + journalSize: 1024 * 1024 }); }); - + //////////////////////////////////////////////////////////////////////////////// /// @brief _routing //////////////////////////////////////////////////////////////////////////////// @@ -439,8 +438,8 @@ // create the _routing collection addTask("createRouting", "setup _routing collection", function () { // needs to be big enough for assets - return createSystemCollection("_routing", { - journalSize: 32 * 1024 * 1024 + return createSystemCollection("_routing", { + journalSize: 32 * 1024 * 1024 }); }); @@ -453,7 +452,7 @@ "setup _cluster_kickstarter_plans collection", function () { //TODO add check if this is the main dispatcher return createSystemCollection("_cluster_kickstarter_plans", { - journalSize: 4 * 1024 * 1024 + journalSize: 4 * 1024 * 1024 }); }); @@ -473,7 +472,7 @@ routing.toArray().forEach(function (doc) { // check for specific redirects if (doc.url && doc.action && doc.action.options && doc.action.options.destination) { - if (doc.url.match(/^\/(_admin\/(html|aardvark))?/) && + if (doc.url.match(/^\/(_admin\/(html|aardvark))?/) && doc.action.options.destination.match(/_admin\/(html|aardvark)/)) { // remove old, non-working redirect routing.remove(doc); @@ -498,7 +497,7 @@ return true; }); - + //////////////////////////////////////////////////////////////////////////////// /// @brief upgradeGraphs //////////////////////////////////////////////////////////////////////////////// @@ -534,7 +533,7 @@ ); } ); - } + } catch (e) { logger.error("could not upgrade _graphs"); return false; @@ -548,12 +547,12 @@ // set up the collection _aal addTask("setupAal", "setup _aal collection", function () { - return createSystemCollection("_aal", { - waitForSync : true, - shardKeys: [ "name", "version" ] + return createSystemCollection("_aal", { + waitForSync : true, + shardKeys: [ "name", "version" ] }); }); - + //////////////////////////////////////////////////////////////////////////////// /// @brief createAalIndex //////////////////////////////////////////////////////////////////////////////// @@ -572,7 +571,7 @@ return true; }); - + //////////////////////////////////////////////////////////////////////////////// /// @brief setupAqlFunctions //////////////////////////////////////////////////////////////////////////////// @@ -580,7 +579,7 @@ // set up the collection _aqlfunctions addTask("setupAqlFunctions", "setup _aqlfunctions collection", function () { return createSystemCollection("_aqlfunctions", { - journalSize: 4 * 1024 * 1024 + journalSize: 4 * 1024 * 1024 }); }); @@ -614,13 +613,13 @@ if (oldKey !== newKey) { try { - var doc = { - _key: newKey.toUpperCase(), - name: newKey, - code: f.code, - isDeterministic: f.isDeterministic + var doc = { + _key: newKey.toUpperCase(), + name: newKey, + code: f.code, + isDeterministic: f.isDeterministic }; - + funcs.save(doc); funcs.remove(oldKey); } @@ -683,18 +682,40 @@ // create the _statistics collection addTask("createConfiguration", "setup _configuration collection", function () { var name = "_configuration"; - var result = createSystemCollection(name, { - waitForSync: true, - journalSize: 1024 * 1024 + var result = createSystemCollection(name, { + waitForSync: true, + journalSize: 1024 * 1024 }); return result; }); +//////////////////////////////////////////////////////////////////////////////// +/// @brief mount system apps on correct endpoints +//////////////////////////////////////////////////////////////////////////////// + + // move all _api apps to _api and all system apps to system + addTask("systemAppEndpoints", "mount system apps on correct endpoints", function () { + var didWork = true; + db._aal.byExample( + { + type: "mount", + isSystem: true + } + ).toArray().forEach(function(app) { + try { + db._aal.remove(app._key); + } catch (e) { + didWork = false; + } + }); + return didWork; + }); + //////////////////////////////////////////////////////////////////////////////// /// @brief executes the upgrade tasks //////////////////////////////////////////////////////////////////////////////// - + // loop through all tasks and execute them if (upgradeRun || 0 < activeTasks.length) { logger.log("Found " + allTasks.length + " defined task(s), " @@ -719,7 +740,7 @@ result = task.func(); } catch (err) { - logger.error("Executing " + taskName + " failed with exception: " + + logger.error("Executing " + taskName + " failed with exception: " + String(err.stack || err)); } @@ -768,9 +789,9 @@ logger.error("Unexpected ArangoDB server version: " + internal.db._version()); return false; } - + var currentVersion = parseFloat(currentServerVersion[1]); - + if (cluster.isCoordinator()) { var result = runUpgrade(currentVersion, true); internal.initializeFoxx(); @@ -792,7 +813,7 @@ lastVersion = parseFloat(versionValues.version); } } - + if (lastVersion === null) { logger.info("No VERSION file found in database directory."); return runUpgrade(currentVersion, true); @@ -812,7 +833,7 @@ // downgrade?? if (lastVersion > currentVersion) { - logger.error("Database directory version (" + lastVersion + logger.error("Database directory version (" + lastVersion + ") is higher than server version (" + currentVersion + ")."); logger.error("It seems like you are running ArangoDB on a database directory"