From 2b62569d3c44761e71d48272c99080c50ce7827c Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 24 Jun 2025 08:43:51 +0200 Subject: [PATCH 01/13] HTTP API: Add some missing defaults/enums --- site/content/3.11/develop/http-api/databases.md | 10 ++++++++-- site/content/3.11/develop/http-api/documents.md | 6 ++++++ site/content/3.12/develop/http-api/databases.md | 10 ++++++++-- site/content/3.12/develop/http-api/documents.md | 6 ++++++ site/content/3.13/develop/http-api/databases.md | 10 ++++++++-- site/content/3.13/develop/http-api/documents.md | 6 ++++++ 6 files changed, 42 insertions(+), 6 deletions(-) diff --git a/site/content/3.11/develop/http-api/databases.md b/site/content/3.11/develop/http-api/databases.md index 0e449df6df..4a54f906dd 100644 --- a/site/content/3.11/develop/http-api/databases.md +++ b/site/content/3.11/develop/http-api/databases.md @@ -241,9 +241,15 @@ paths: properties: sharding: description: | - The sharding method to use for new collections in this database. Valid values - are: "", "flexible", or "single". The first two are equivalent. _(cluster only)_ + The sharding method to use for new collections in this database. _(cluster only)_ + Valid values are: + - `""` or `"flexible"`: Create a database where collections can have any + number of shards and the shards can reside on different DB-Servers. + - `"single"`: Create a OneShard database where all collections have a + single shard and the shards are placed on the same DB-Server. type: string + enum: ["", flexible, single] + default: "" replicationFactor: description: | Default replication factor for new collections created in this database. diff --git a/site/content/3.11/develop/http-api/documents.md b/site/content/3.11/develop/http-api/documents.md index 5c9e7dfbd5..a359ed0673 100644 --- a/site/content/3.11/develop/http-api/documents.md +++ b/site/content/3.11/develop/http-api/documents.md @@ -475,6 +475,7 @@ paths: therefore they can only be performed on collections sharded by `_key`. schema: type: boolean + default: false - name: overwriteMode in: query required: false @@ -499,6 +500,8 @@ paths: not set, and the `overwrite` flag is `false` or not set either. schema: type: string + enum: [ignore, replace, update, conflict] + default: conflict - name: keepNull in: query required: false @@ -1946,6 +1949,7 @@ paths: therefore they can only be performed on collections sharded by `_key`. schema: type: boolean + default: false - name: overwriteMode in: query required: false @@ -1970,6 +1974,8 @@ paths: not set, and the `overwrite` flag is `false` or not set either. schema: type: string + enum: [ignore, replace, update, conflict] + default: conflict - name: keepNull in: query required: false diff --git a/site/content/3.12/develop/http-api/databases.md b/site/content/3.12/develop/http-api/databases.md index 129ba1887e..7cf6c7ad76 100644 --- a/site/content/3.12/develop/http-api/databases.md +++ b/site/content/3.12/develop/http-api/databases.md @@ -241,9 +241,15 @@ paths: properties: sharding: description: | - The sharding method to use for new collections in this database. Valid values - are: "", "flexible", or "single". The first two are equivalent. _(cluster only)_ + The sharding method to use for new collections in this database. _(cluster only)_ + Valid values are: + - `""` or `"flexible"`: Create a database where collections can have any + number of shards and the shards can reside on different DB-Servers. + - `"single"`: Create a OneShard database where all collections have a + single shard and the shards are placed on the same DB-Server. type: string + enum: ["", flexible, single] + default: "" replicationFactor: description: | Default replication factor for new collections created in this database. diff --git a/site/content/3.12/develop/http-api/documents.md b/site/content/3.12/develop/http-api/documents.md index 715760330b..ea7d55f4c9 100644 --- a/site/content/3.12/develop/http-api/documents.md +++ b/site/content/3.12/develop/http-api/documents.md @@ -465,6 +465,7 @@ paths: therefore they can only be performed on collections sharded by `_key`. schema: type: boolean + default: false - name: overwriteMode in: query required: false @@ -489,6 +490,8 @@ paths: not set, and the `overwrite` flag is `false` or not set either. schema: type: string + enum: [ignore, replace, update, conflict] + default: conflict - name: keepNull in: query required: false @@ -2004,6 +2007,7 @@ paths: therefore they can only be performed on collections sharded by `_key`. schema: type: boolean + default: false - name: overwriteMode in: query required: false @@ -2028,6 +2032,8 @@ paths: not set, and the `overwrite` flag is `false` or not set either. schema: type: string + enum: [ignore, replace, update, conflict] + default: conflict - name: keepNull in: query required: false diff --git a/site/content/3.13/develop/http-api/databases.md b/site/content/3.13/develop/http-api/databases.md index 129ba1887e..7cf6c7ad76 100644 --- a/site/content/3.13/develop/http-api/databases.md +++ b/site/content/3.13/develop/http-api/databases.md @@ -241,9 +241,15 @@ paths: properties: sharding: description: | - The sharding method to use for new collections in this database. Valid values - are: "", "flexible", or "single". The first two are equivalent. _(cluster only)_ + The sharding method to use for new collections in this database. _(cluster only)_ + Valid values are: + - `""` or `"flexible"`: Create a database where collections can have any + number of shards and the shards can reside on different DB-Servers. + - `"single"`: Create a OneShard database where all collections have a + single shard and the shards are placed on the same DB-Server. type: string + enum: ["", flexible, single] + default: "" replicationFactor: description: | Default replication factor for new collections created in this database. diff --git a/site/content/3.13/develop/http-api/documents.md b/site/content/3.13/develop/http-api/documents.md index 715760330b..ea7d55f4c9 100644 --- a/site/content/3.13/develop/http-api/documents.md +++ b/site/content/3.13/develop/http-api/documents.md @@ -465,6 +465,7 @@ paths: therefore they can only be performed on collections sharded by `_key`. schema: type: boolean + default: false - name: overwriteMode in: query required: false @@ -489,6 +490,8 @@ paths: not set, and the `overwrite` flag is `false` or not set either. schema: type: string + enum: [ignore, replace, update, conflict] + default: conflict - name: keepNull in: query required: false @@ -2004,6 +2007,7 @@ paths: therefore they can only be performed on collections sharded by `_key`. schema: type: boolean + default: false - name: overwriteMode in: query required: false @@ -2028,6 +2032,8 @@ paths: not set, and the `overwrite` flag is `false` or not set either. schema: type: string + enum: [ignore, replace, update, conflict] + default: conflict - name: keepNull in: query required: false From bc56f4a02fa09da24ce6199ee9e1f1c9878a81bc Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 24 Jun 2025 17:03:16 +0200 Subject: [PATCH 02/13] More defaults, formatting, rev parameter in Gharial vertex/edge ops, mention startup options, add missing slowStreamingQueryThreshold option --- .../3.11/develop/http-api/collections.md | 2 + .../3.11/develop/http-api/databases.md | 16 +- .../3.11/develop/http-api/documents.md | 90 +++-- .../3.11/develop/http-api/graphs/edges.md | 13 +- .../develop/http-api/graphs/named-graphs.md | 228 +++++++---- .../develop/http-api/queries/aql-queries.md | 141 ++++--- site/content/3.11/develop/http-api/users.md | 28 +- .../3.12/develop/http-api/collections.md | 2 + .../3.12/develop/http-api/databases.md | 14 +- .../3.12/develop/http-api/documents.md | 90 +++-- .../3.12/develop/http-api/graphs/edges.md | 13 +- .../develop/http-api/graphs/named-graphs.md | 228 +++++++---- .../develop/http-api/queries/aql-queries.md | 139 ++++--- site/content/3.12/develop/http-api/users.md | 28 +- .../3.13/develop/http-api/collections.md | 380 +----------------- .../3.13/develop/http-api/databases.md | 14 +- .../3.13/develop/http-api/documents.md | 90 +++-- .../3.13/develop/http-api/graphs/edges.md | 13 +- .../develop/http-api/graphs/named-graphs.md | 228 +++++++---- .../develop/http-api/queries/aql-queries.md | 139 ++++--- site/content/3.13/develop/http-api/users.md | 28 +- 21 files changed, 1014 insertions(+), 910 deletions(-) diff --git a/site/content/3.11/develop/http-api/collections.md b/site/content/3.11/develop/http-api/collections.md index 4af33b0aef..dbae42838f 100644 --- a/site/content/3.11/develop/http-api/collections.md +++ b/site/content/3.11/develop/http-api/collections.md @@ -2830,6 +2830,7 @@ paths: keys are generated on the leader DB-Server, which has full control over the key sequence. type: string + default: traditional allowUserKeys: description: | If set to `true`, then you are allowed to supply own key values in the @@ -2845,6 +2846,7 @@ paths: auto-generate keys in this case are not aware of all keys which are already used. {{}} type: boolean + default: true increment: description: | The increment value for the `autoincrement` key generator. diff --git a/site/content/3.11/develop/http-api/databases.md b/site/content/3.11/develop/http-api/databases.md index 4a54f906dd..bfece540b9 100644 --- a/site/content/3.11/develop/http-api/databases.md +++ b/site/content/3.11/develop/http-api/databases.md @@ -243,10 +243,10 @@ paths: description: | The sharding method to use for new collections in this database. _(cluster only)_ Valid values are: - - `""` or `"flexible"`: Create a database where collections can have any - number of shards and the shards can reside on different DB-Servers. + - `""` or `"flexible"`: Create a database where collections can + be sharded independently. - `"single"`: Create a OneShard database where all collections have a - single shard and the shards are placed on the same DB-Server. + single shard and all leader shards are co-located on the same DB-Server. type: string enum: ["", flexible, single] default: "" @@ -266,7 +266,7 @@ paths: up-to-date copies succeed at the same time, however. The value of `writeConcern` cannot be greater than `replicationFactor`. - If `distributeShardsLike` is set, the `writeConcern` + If `distributeShardsLike` is set, the default `writeConcern` is that of the prototype collection. For SatelliteCollections, the `writeConcern` is automatically controlled to equal the number of DB-Servers and has a value of `0`. @@ -298,11 +298,11 @@ paths: type: string active: description: | - A flag indicating whether the user account should be activated or not. - The default value is `true`. If set to `false`, then the user won't be able to - log into the database. The default is `true`. The attribute is ignored for users - that already exist. + Whether the user account should be able to log in to the database system. + + The attribute is ignored for users that already exist. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface diff --git a/site/content/3.11/develop/http-api/documents.md b/site/content/3.11/develop/http-api/documents.md index a359ed0673..f5af92e827 100644 --- a/site/content/3.11/develop/http-api/documents.md +++ b/site/content/3.11/develop/http-api/documents.md @@ -120,7 +120,7 @@ paths: in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one + If the `If-Match` header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a *HTTP 412* is returned. schema: @@ -284,7 +284,7 @@ paths: in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one + If the `If-Match` header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a *HTTP 412* is returned. schema: @@ -445,6 +445,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -453,6 +454,7 @@ paths: in the result. Only available if the overwrite option is used. schema: type: boolean + default: false - name: silent in: query required: false @@ -464,6 +466,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -507,13 +510,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the update-insert - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only. schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -521,10 +525,11 @@ paths: Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to `false`, the value in the patch document overwrites the existing document's value. If set to `true`, - objects are merged. The default is `true`. + objects are merged. This option controls the update-insert behavior only. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -533,6 +538,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -870,13 +876,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given document is ignored. If this is set to `false`, then the `_rev` attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -885,6 +892,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -893,6 +901,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -904,6 +913,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -912,12 +922,13 @@ paths: replacements affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: If-Match in: header required: false description: | 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. schema: type: string - name: x-arango-trx-id @@ -1174,13 +1185,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the patch - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -1188,10 +1200,10 @@ paths: Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to `false`, the value in the patch document overwrites the existing document's - value. If set to `true`, objects are merged. The default is - `true`. + value. If set to `true`, objects are merged. schema: type: boolean + default: true - name: waitForSync in: query required: false @@ -1203,13 +1215,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given document is ignored. If this is set to `false`, then the `_rev` attribute given in the body document is taken as a precondition. The document is only updated if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -1218,6 +1231,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -1226,6 +1240,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1237,6 +1252,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1245,12 +1261,13 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: If-Match in: header required: false description: | You can conditionally update a document based on a target revision id by - using the `if-match` HTTP header. + using the `If-Match` HTTP header. schema: type: string - name: x-arango-trx-id @@ -1471,6 +1488,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1482,6 +1500,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1490,12 +1509,13 @@ paths: if document removals affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: If-Match in: header required: false description: | You can conditionally remove a document based on a target revision id by - using the `if-match` HTTP header. + using the `If-Match` HTTP header. schema: type: string - name: x-arango-trx-id @@ -1741,12 +1761,12 @@ paths: in: query required: false description: | - Should the value be `true` (the default): - If a search document contains a value for the `_rev` field, - then the document is only returned if it has the same revision value. - Otherwise a precondition failed error is returned. + If set to `false` and a `_rev` attribute is included in the request, + then the document is only returned if it has the same revision. + Otherwise, a precondition failed error is returned for the document. schema: type: string + default: true - name: x-arango-allow-dirty-read in: header required: false @@ -1918,6 +1938,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -1926,6 +1947,7 @@ paths: in the result. Only available if the overwrite option is used. schema: type: boolean + default: false - name: silent in: query required: false @@ -1938,6 +1960,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -1981,13 +2004,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the update-insert - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only. schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -1995,10 +2019,11 @@ paths: Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to `false`, the value in the patch document overwrites the existing document's value. If set to `true`, - objects are merged. The default is `true`. + objects are merged. This option controls the update-insert behavior only. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -2007,6 +2032,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -2234,13 +2260,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given documents are ignored. If this is set to `false`, then any `_rev` attribute given in a body document is taken as a precondition. The document is only replaced if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -2249,6 +2276,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2257,6 +2285,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2269,6 +2298,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2277,6 +2307,7 @@ paths: replacements affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -2439,13 +2470,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the patch - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -2453,10 +2485,10 @@ paths: Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to `false`, the value in the patch document overwrites the existing document's - value. If set to `true`, objects are merged. The default is - `true`. + value. If set to `true`, objects are merged. schema: type: boolean + default: true - name: waitForSync in: query required: false @@ -2468,13 +2500,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given documents are ignored. If this is set to `false`, then any `_rev` attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -2483,6 +2516,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2491,6 +2525,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2503,6 +2538,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2511,6 +2547,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -2674,11 +2711,11 @@ paths: in: query required: false description: | - If set to `true`, ignore any `_rev` attribute in the selectors. No - revision check is performed. If set to `false` then revisions are checked. - The default is `true`. + If set to `true`, ignore any `_rev` attribute included in the request. No + revision check is performed. If set to `false`, then revisions are checked. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -2687,6 +2724,7 @@ paths: if document removals affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false diff --git a/site/content/3.11/develop/http-api/graphs/edges.md b/site/content/3.11/develop/http-api/graphs/edges.md index 84174885c8..7daeaca862 100644 --- a/site/content/3.11/develop/http-api/graphs/edges.md +++ b/site/content/3.11/develop/http-api/graphs/edges.md @@ -29,7 +29,7 @@ for details. ```openapi paths: - /_db/{database-name}/_api/edges/{collection-id}: + /_db/{database-name}/_api/edges/{collection}: get: operationId: getVertexEdges description: | @@ -44,11 +44,11 @@ paths: The name of the database. schema: type: string - - name: collection-id + - name: collection in: path required: true description: | - The id of the collection. + The name of the edge collection you want to retrieve edges from. schema: type: string - name: vertex @@ -62,10 +62,13 @@ paths: in: query required: false description: | - Selects `in` or `out` direction for edges. If not set, any edges are - returned. + - `"in"`: Return edges that reference the `vertex` in the `_to` attribute. + - `"out"`: Return edges that reference the `vertex` in the `_from` attribute. + - `"any"`: Return edges that reference the `vertex` in the `_from` or `_to` attribute. schema: type: string + enum: [any, in, out] + default: any - name: x-arango-allow-dirty-read in: header required: false diff --git a/site/content/3.11/develop/http-api/graphs/named-graphs.md b/site/content/3.11/develop/http-api/graphs/named-graphs.md index be0afc9d77..e6feb4cd31 100644 --- a/site/content/3.11/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.11/develop/http-api/graphs/named-graphs.md @@ -282,11 +282,13 @@ paths: description: | Define if the created graph should be smart (Enterprise Edition only). type: boolean + default: false isDisjoint: description: | Whether to create a Disjoint SmartGraph instead of a regular SmartGraph (Enterprise Edition only). type: boolean + default: false options: description: | a JSON object to define options for creating collections within this graph. @@ -295,7 +297,7 @@ paths: properties: smartGraphAttribute: description: | - Only has effect in Enterprise Edition and it is required if isSmart is true. + Only has effect in Enterprise Edition and it is required if `isSmart` is `true`. The attribute name that is used to smartly shard the vertices of a graph. Every vertex in this SmartGraph has to have this attribute. Cannot be modified later. @@ -1171,6 +1173,7 @@ paths: dropped if they are not used in other graphs. schema: type: boolean + default: false responses: '202': description: | @@ -2877,6 +2880,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false requestBody: content: application/json: @@ -3342,6 +3346,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false responses: '201': description: | @@ -3732,6 +3737,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -3744,14 +3750,9 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to store as a vertex document. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to be the JSON object to be stored. - type: object responses: '201': description: | @@ -4057,22 +4058,23 @@ paths: in: query required: false description: | - Must contain a revision. - If this is set a document is only returned if - it has exactly this revision. - Also see if-match header as an alternative to this. + If set, the document is only returned if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. schema: type: string - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an query parameter `rev`. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is returned if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - - name: if-none-match + - name: If-None-Match in: header required: false description: | @@ -4134,7 +4136,7 @@ paths: type: string '304': description: | - Returned if the if-none-match header is given and the + Returned if the `If-None-Match` header is given and the currently stored vertex still has this revision value. So there was no update between the last time the vertex was fetched by the caller. @@ -4272,7 +4274,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -4362,6 +4364,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only updated if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -4380,6 +4391,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4388,6 +4400,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4396,13 +4409,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -4417,14 +4433,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object containing exactly the attributes + that should be overwritten. All other attributes remain unchanged. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged. - type: object responses: '200': description: | @@ -4712,7 +4724,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -4805,6 +4817,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only replaced if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -4823,6 +4844,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4831,6 +4853,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4839,13 +4862,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -4860,14 +4886,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to replace the existing + vertex document with. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to be the JSON object to be stored. - type: object responses: '200': description: | @@ -5155,7 +5177,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -5250,6 +5272,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only deleted if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -5265,11 +5296,12 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, + If the `If-Match` header is given, then it must contain exactly one ETag. The document is updated, if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative you can supply the ETag in an attribute rev in the URL. schema: @@ -5487,7 +5519,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -5589,6 +5621,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -5601,6 +5634,8 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to store as an edge document. type: object required: - _from @@ -6000,22 +6035,23 @@ paths: in: query required: false description: | - Must contain a revision. - If this is set a document is only returned if - it has exactly this revision. - Also see if-match header as an alternative to this. + If set, the document is only returned if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. schema: type: string - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is returned if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - - name: if-none-match + - name: If-None-Match in: header required: false description: | @@ -6087,7 +6123,7 @@ paths: type: string '304': description: | - Returned if the if-none-match header is given and the + Returned if the `If-None-Match` header is given and the currently stored edge still has this revision value. So there was no update between the last time the edge was fetched by the caller. @@ -6225,7 +6261,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -6316,6 +6352,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only updated if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -6350,13 +6395,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -6371,14 +6419,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object containing exactly the attributes + that should be overwritten. All other attributes remain unchanged. type: object - required: - - edge - properties: - edge: - description: | - The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged. - type: object responses: '200': description: | @@ -6727,7 +6771,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -6820,6 +6864,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only replaced if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -6854,13 +6907,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is replaced if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -6875,6 +6931,9 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to replace an existing + edge document with. type: object required: - _from @@ -7238,7 +7297,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -7335,6 +7394,15 @@ paths: The `_key` attribute of the edge. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only deleted if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -7350,13 +7418,15 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is deleted if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -7592,7 +7662,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: diff --git a/site/content/3.11/develop/http-api/queries/aql-queries.md b/site/content/3.11/develop/http-api/queries/aql-queries.md index 4dd2d7a9ef..b16bfe21ce 100644 --- a/site/content/3.11/develop/http-api/queries/aql-queries.md +++ b/site/content/3.11/develop/http-api/queries/aql-queries.md @@ -324,19 +324,21 @@ paths: type: string count: description: | - indicates whether the number of documents in the result set should be returned in - the "count" attribute of the result. - Calculating the "count" attribute might have a performance impact for some queries - in the future so this option is turned off by default, and "count" + Whether the number of documents in the result set should be returned in + the `count` attribute of the result. + Calculating this count might have a performance impact for some queries + in the future, so this option is turned off by default and `count` is only returned when requested. type: boolean + default: false batchSize: description: | - maximum number of result documents to be transferred from + The maximum number of result documents to be transferred from the server to the client in one roundtrip. If this attribute is not set, a server-controlled default value will be used. A `batchSize` value of `0` is disallowed. type: integer + default: 1000 ttl: description: | The time-to-live for the cursor (in seconds). If the result set is small enough @@ -344,15 +346,26 @@ paths: Otherwise they are stored in memory and will be accessible via the cursor with respect to the `ttl`. The cursor will be removed on the server automatically after the specified amount of time. This is useful to ensure garbage collection - of cursors that are not fully fetched by clients. If not set, a server-defined - value will be used (default: 30 seconds). + of cursors that are not fully fetched by clients. + + You can configure a default TTL with the `--query.registry-ttl` startup option. + If not set, the defaults are 30 seconds for single servers and 600 seconds for + Coordinators of a cluster deployment. + + The time-to-live is renewed upon every access to the cursor. type: integer memoryLimit: description: | - the maximum number of memory (measured in bytes) that the query is allowed to - use. If set, then the query will fail with error "resource limit exceeded" in - case it allocates too much memory. A value of `0` indicates that there is no - memory limit. + The maximum amount of memory (in bytes) that the query is allowed to + use. If set, then the query fails with error "resource limit exceeded" in + case it allocates too much memory. A value of `0` indicates that there is + no memory limit, but the `--query.global-memory-limit` startup option + may still limit it. + + You can configure a default per-query memory limit with the + `--query.memory-limit` startup option. You can only increase + this default memory limit if `--query.memory-limit-override` + is enabled. type: integer bindVars: description: | @@ -368,7 +381,7 @@ paths: properties: fullCount: description: | - if set to `true` and the query contains a `LIMIT` clause, then the + If set to `true` and the query contains a `LIMIT` clause, then the result will have an `extra` attribute with the sub-attributes `stats` and `fullCount`, `{ ... , "extra": { "stats": { "fullCount": 123 } } }`. The `fullCount` attribute will contain the number of documents in the result before the @@ -380,16 +393,18 @@ paths: be present in the result if the query has a top-level LIMIT clause and the LIMIT clause is actually used in the query. type: boolean + default: false fillBlockCache: description: | - if set to `true` or not specified, this will make the query store the data it + If set to `true`, then the query stores the data it reads via the RocksDB storage engine in the RocksDB block cache. This is usually the desired behavior. The option can be set to `false` for queries that are known to either read a lot of data which would thrash the block cache, or for queries that read data which are known to be outside of the hot set. By setting the option - to `false`, data read by the query will not make it into the RocksDB block cache if + to `false`, data read by the query does not make it into the RocksDB block cache if not already in there, thus leaving more room for the actual hot set. type: boolean + default: true maxNumberOfPlans: description: | Limits the maximum number of plans that are created by the AQL query optimizer. @@ -405,23 +420,23 @@ paths: type: integer maxWarningCount: description: | - Limits the maximum number of warnings a query will return. The number of warnings - a query will return is limited to 10 by default, but that number can be increased - or decreased by setting this attribute. + Limits the number of warnings a query can return. + You can increased or decreased the number with this option. type: integer + default: 10 failOnWarning: description: | - When set to `true`, the query will throw an exception and abort instead of producing + If set to `true`, the query throws an exception and aborts instead of producing a warning. This option should be used during development to catch potential issues - early. When the attribute is set to `false`, warnings will not be propagated to - exceptions and will be returned with the query result. - There is also a server configuration option `--query.fail-on-warning` for setting the - default value for `failOnWarning` so it does not need to be set on a per-query level. + early. When the attribute is set to `false`, warnings are not propagated to + exceptions and are returned with the query result. + There is also a `--query.fail-on-warning` startup option for setting the + default value for `failOnWarning`, so it does not need to be set on a per-query basis. type: boolean allowRetry: description: | Set this option to `true` to make it possible to retry - fetching the latest batch from a cursor. The default is `false`. + fetching the latest batch from a cursor. If retrieving a result batch fails because of a connection issue, you can ask for that batch again using the `POST /_api/cursor//` @@ -452,6 +467,7 @@ paths: server doesn't unnecessarily keep the batch until the cursor times out (`ttl` query option). type: boolean + default: false stream: description: | Can be enabled to execute the query lazily. If set to `true`, then the query is @@ -480,12 +496,13 @@ paths: - Query statistics, profiling data and warnings are delivered as part of the last batch. - If the `stream` option is `false` (default), then the complete result of the + If the `stream` option is `false`, then the complete result of the query is calculated before any of it is returned to the client. The server stores the full result in memory (on the contacted Coordinator if in a cluster). All other resources are freed immediately (locks, RocksDB snapshots). The query will fail before it returns results in case of a conflict. type: boolean + default: false cache: description: | Whether the [AQL query results cache](../../../aql/execution-and-performance/caching-query-results.md) @@ -499,7 +516,10 @@ paths: If you set the `cache` option to `false`, then any query cache lookup is skipped for the query. If you set it to `true`, the query cache is checked for a cached result **if** the query cache mode is either set to `on` or `demand`. + + You can configure a default mode with the `--query.cache-mode` startup option. type: boolean + spillOverThresholdMemoryUsage: description: | This option allows queries to store intermediate and final results temporarily @@ -511,7 +531,9 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: 128MB. + Default value: 128 MiB, respectively the value of the + `--temp.intermediate-results-spillover-threshold-memory-usage` + startup option. {{}} Spilling data from RAM onto disk is an experimental feature and is turned off @@ -534,7 +556,9 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: `5000000` rows. + Default value: 5 million rows, respectively the value of the + `--temp.intermediate-results-spillover-threshold-num-rows` + startup option. {{}} Spilling data from RAM onto disk is an experimental feature and is turned off @@ -572,11 +596,13 @@ paths: The default value is `60.0` seconds. When the maximal time is reached, the query is stopped. type: number + default: 60.0 maxRuntime: description: | The query has to be executed within the given runtime or it is killed. The value is specified in seconds. The default value is `0.0` (no timeout). type: number + default: 0.0 maxDNFConditionMembers: description: | A threshold for the maximum number of `OR` sub-nodes in the internal @@ -599,16 +625,22 @@ paths: maxTransactionSize: description: | The transaction size limit in bytes. + + You can configure the default with the `--rocksdb.max-transaction-size` startup option. type: integer intermediateCommitSize: description: | The maximum total size of operations after which an intermediate commit is performed automatically. + + You can configure the default with the `--rocksdb.intermediate-commit-size` startup option. type: integer intermediateCommitCount: description: | The maximum number of operations after which an intermediate commit is performed automatically. + + You can configure the default with the `--rocksdb.intermediate-commit-count` startup option. type: integer skipInaccessibleCollections: description: | @@ -2561,43 +2593,52 @@ paths: application/json: schema: type: object - required: - - enabled - - trackSlowQueries - - trackBindVars - - maxSlowQueries - - slowQueryThreshold - - maxQueryStringLength properties: enabled: description: | - If set to `true`, then queries will be tracked. If set to - `false`, neither queries nor slow queries will be tracked. + If set to `true`, then queries are tracked. If set to + `false`, neither regular queries nor slow queries are tracked. + + You can configure the default value with the `--query.tracking` startup option. type: boolean trackSlowQueries: description: | - If set to `true`, then slow queries will be tracked + If set to `true`, then slow queries are tracked in the list of slow queries if their runtime exceeds the value set in `slowQueryThreshold`. In order for slow queries to be tracked, the `enabled` property must also be set to `true`. + + You can configure the default value with the `--query.tracking-slow-queries` startup option. type: boolean trackBindVars: description: | - If set to `true`, then the bind variables used in queries will be tracked + If set to `true`, then the bind variables used in queries are tracked along with queries. + + You can configure the default value with the `--query.tracking-with-bindvars` startup option. type: boolean maxSlowQueries: description: | The maximum number of slow queries to keep in the list - of slow queries. If the list of slow queries is full, the oldest entry in - it will be discarded when additional slow queries occur. + of slow queries. If the list of slow queries is full, the oldest entry + is discarded when additional slow queries occur. type: integer slowQueryThreshold: description: | - The threshold value for treating a query as slow. A - query with a runtime greater or equal to this threshold value will be - put into the list of slow queries when slow query tracking is enabled. - The value for `slowQueryThreshold` is specified in seconds. + The threshold value for treating a query as slow (in seconds). + A query with a runtime greater or equal to this threshold value is + put into the list of slow queries if slow query tracking is enabled. + + You can configure the default value with the `--query.slow-threshold` startup option. + type: integer + slowStreamingQueryThreshold: + description: | + The threshold value for treating a streaming query as slow (in seconds). + A query with `"stream"` set to `true` and a runtime greater or equal to this + threshold value is put into the list of slow queries if slow query tracking + is enabled. + + You can configure the default value with the `--query.slow-streaming-threshold` startup option. type: integer maxQueryStringLength: description: | @@ -2605,7 +2646,11 @@ paths: Query strings can have arbitrary lengths, and this property can be used to save memory in case very long query strings are used. The value is specified in bytes. + + You can disable the tracking of query strings with the + `--query.tracking-with-querystring` startup option. type: integer + default: 4096 responses: '200': description: | @@ -2841,12 +2886,13 @@ paths: in: query required: false description: | - If set to `true`, will attempt to kill the specified query in all databases, + If set to `true`, attempt to kill the specified query in all databases, not just the selected one. Using the parameter is only allowed in the `_system` database and with superuser privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2964,6 +3010,7 @@ paths: if set to `true`, all possible execution plans will be returned. The default is `false`, meaning only the optimal plan will be returned. type: boolean + default: false maxNumberOfPlans: description: | The maximum number of plans that the optimizer is allowed to @@ -2977,6 +3024,7 @@ paths: were not applied. This option generally leads to different execution plans. type: boolean + default: false profile: description: | Whether to include additional query profiling information. @@ -2994,9 +3042,10 @@ paths: type: integer maxWarningCount: description: | - Limits the number of warnings a query can return. The maximum number of warnings - is `10` by default but you can increase or decrease the limit. + Limits the number of warnings a query can return. + You can increased or decreased the number with this option. type: integer + default: 10 failOnWarning: description: | If set to `true`, the query throws an exception and aborts instead of producing diff --git a/site/content/3.11/develop/http-api/users.md b/site/content/3.11/develop/http-api/users.md index 561aa5bc38..37b6407ad3 100644 --- a/site/content/3.11/develop/http-api/users.md +++ b/site/content/3.11/develop/http-api/users.md @@ -68,9 +68,9 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. If not - specified, this will default to `true`. + Whether the user account should be able to log in to the database system. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface @@ -161,9 +161,9 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. If not - specified, this will default to *true*. + Whether the user account should be able to log in to the database system. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface @@ -255,7 +255,7 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. + Whether the user account should be able to log in to the database system. type: boolean extra: description: | @@ -455,7 +455,7 @@ paths: attributes on success: - `user`: The name of the user as a string. - - `active`: An optional flag that specifies whether the user is active. + - `active`: Whether the user account is able to log in to the database system. - `extra`: A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. parameters: @@ -522,10 +522,11 @@ paths: properties: grant: description: | - - Use "rw" to set the database access level to *Administrate*. - - Use "ro" to set the database access level to *Access*. - - Use "none" to set the database access level to *No access*. + - `"rw"`: Set the database access level to *Administrate*. + - `"ro"`: Set the database access level to *Access*. + - `"none"`: Set the database access level to *No access*. type: string + enum: [rw, ro, none] parameters: - name: database-name in: path @@ -612,12 +613,11 @@ paths: properties: grant: description: | - Use "rw" to set the collection level access to *Read/Write*. - - Use "ro" to set the collection level access to *Read Only*. - - Use "none" to set the collection level access to *No access*. + - `"rw"`: Set the collection access level to *Read/Write*. + - `"ro"`: Set the collection access level to *Read Only*. + - `"none"`: Set the collection access level to *No access*. type: string + enum: [rw, ro, none] parameters: - name: database-name in: path diff --git a/site/content/3.12/develop/http-api/collections.md b/site/content/3.12/develop/http-api/collections.md index 369c836fbd..073a1ebc93 100644 --- a/site/content/3.12/develop/http-api/collections.md +++ b/site/content/3.12/develop/http-api/collections.md @@ -2888,6 +2888,7 @@ paths: keys are generated on the leader DB-Server, which has full control over the key sequence. type: string + default: traditional allowUserKeys: description: | If set to `true`, then you are allowed to supply own key values in the @@ -2903,6 +2904,7 @@ paths: auto-generate keys in this case are not aware of all keys which are already used. {{}} type: boolean + default: true increment: description: | The increment value for the `autoincrement` key generator. diff --git a/site/content/3.12/develop/http-api/databases.md b/site/content/3.12/develop/http-api/databases.md index 7cf6c7ad76..098a39053e 100644 --- a/site/content/3.12/develop/http-api/databases.md +++ b/site/content/3.12/develop/http-api/databases.md @@ -243,10 +243,10 @@ paths: description: | The sharding method to use for new collections in this database. _(cluster only)_ Valid values are: - - `""` or `"flexible"`: Create a database where collections can have any - number of shards and the shards can reside on different DB-Servers. + - `""` or `"flexible"`: Create a database where collections can + be sharded independently. - `"single"`: Create a OneShard database where all collections have a - single shard and the shards are placed on the same DB-Server. + single shard and all leader shards are co-located on the same DB-Server. type: string enum: ["", flexible, single] default: "" @@ -296,11 +296,11 @@ paths: type: string active: description: | - A flag indicating whether the user account should be activated or not. - The default value is `true`. If set to `false`, then the user won't be able to - log into the database. The default is `true`. The attribute is ignored for users - that already exist. + Whether the user account should be able to log in to the database system. + + The attribute is ignored for users that already exist. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface diff --git a/site/content/3.12/develop/http-api/documents.md b/site/content/3.12/develop/http-api/documents.md index ea7d55f4c9..1c0d9352a6 100644 --- a/site/content/3.12/develop/http-api/documents.md +++ b/site/content/3.12/develop/http-api/documents.md @@ -120,7 +120,7 @@ paths: in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one + If the `If-Match` header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a *HTTP 412* is returned. schema: @@ -284,7 +284,7 @@ paths: in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one + If the `If-Match` header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a *HTTP 412* is returned. schema: @@ -435,6 +435,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -443,6 +444,7 @@ paths: in the result. Only available if the overwrite option is used. schema: type: boolean + default: false - name: silent in: query required: false @@ -454,6 +456,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -497,13 +500,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the update-insert - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only. schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -511,10 +515,11 @@ paths: Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to `false`, the value in the patch document overwrites the existing document's value. If set to `true`, - objects are merged. The default is `true`. + objects are merged. This option controls the update-insert behavior only. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -523,6 +528,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -888,13 +894,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given document is ignored. If this is set to `false`, then the `_rev` attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -903,6 +910,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -911,6 +919,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -922,6 +931,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -930,6 +940,7 @@ paths: replacements affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -960,7 +971,7 @@ paths: required: false description: | 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. schema: type: string - name: x-arango-trx-id @@ -1217,13 +1228,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the patch - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -1231,10 +1243,10 @@ paths: Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to `false`, the value in the patch document overwrites the existing document's - value. If set to `true`, objects are merged. The default is - `true`. + value. If set to `true`, objects are merged. schema: type: boolean + default: true - name: waitForSync in: query required: false @@ -1246,13 +1258,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given document is ignored. If this is set to `false`, then the `_rev` attribute given in the body document is taken as a precondition. The document is only updated if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -1261,6 +1274,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -1269,6 +1283,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1280,6 +1295,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1288,6 +1304,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -1318,7 +1335,7 @@ paths: required: false description: | You can conditionally update a document based on a target revision id by - using the `if-match` HTTP header. + using the `If-Match` HTTP header. schema: type: string - name: x-arango-trx-id @@ -1539,6 +1556,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1550,6 +1568,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1558,12 +1577,13 @@ paths: if document removals affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: If-Match in: header required: false description: | You can conditionally remove a document based on a target revision id by - using the `if-match` HTTP header. + using the `If-Match` HTTP header. schema: type: string - name: x-arango-trx-id @@ -1809,12 +1829,12 @@ paths: in: query required: false description: | - Should the value be `true` (the default): - If a search document contains a value for the `_rev` field, - then the document is only returned if it has the same revision value. - Otherwise a precondition failed error is returned. + If set to `false` and a `_rev` attribute is included in the request, + then the document is only returned if it has the same revision. + Otherwise, a precondition failed error is returned for the document. schema: type: string + default: true - name: x-arango-allow-dirty-read in: header required: false @@ -1976,6 +1996,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -1984,6 +2005,7 @@ paths: in the result. Only available if the overwrite option is used. schema: type: boolean + default: false - name: silent in: query required: false @@ -1996,6 +2018,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -2039,13 +2062,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the update-insert - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only. schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -2053,10 +2077,11 @@ paths: Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to `false`, the value in the patch document overwrites the existing document's value. If set to `true`, - objects are merged. The default is `true`. + objects are merged. This option controls the update-insert behavior only. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -2065,6 +2090,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2320,13 +2346,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given documents are ignored. If this is set to `false`, then any `_rev` attribute given in a body document is taken as a precondition. The document is only replaced if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -2335,6 +2362,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2343,6 +2371,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2355,6 +2384,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2363,6 +2393,7 @@ paths: replacements affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2550,13 +2581,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the patch - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -2564,10 +2596,10 @@ paths: Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to `false`, the value in the patch document overwrites the existing document's - value. If set to `true`, objects are merged. The default is - `true`. + value. If set to `true`, objects are merged. schema: type: boolean + default: true - name: waitForSync in: query required: false @@ -2579,13 +2611,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given documents are ignored. If this is set to `false`, then any `_rev` attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -2594,6 +2627,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2602,6 +2636,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2614,6 +2649,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2622,6 +2658,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2810,11 +2847,11 @@ paths: in: query required: false description: | - If set to `true`, ignore any `_rev` attribute in the selectors. No - revision check is performed. If set to `false` then revisions are checked. - The default is `true`. + If set to `true`, ignore any `_rev` attribute included in the request. No + revision check is performed. If set to `false`, then revisions are checked. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -2823,6 +2860,7 @@ paths: if document removals affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false diff --git a/site/content/3.12/develop/http-api/graphs/edges.md b/site/content/3.12/develop/http-api/graphs/edges.md index 84174885c8..7daeaca862 100644 --- a/site/content/3.12/develop/http-api/graphs/edges.md +++ b/site/content/3.12/develop/http-api/graphs/edges.md @@ -29,7 +29,7 @@ for details. ```openapi paths: - /_db/{database-name}/_api/edges/{collection-id}: + /_db/{database-name}/_api/edges/{collection}: get: operationId: getVertexEdges description: | @@ -44,11 +44,11 @@ paths: The name of the database. schema: type: string - - name: collection-id + - name: collection in: path required: true description: | - The id of the collection. + The name of the edge collection you want to retrieve edges from. schema: type: string - name: vertex @@ -62,10 +62,13 @@ paths: in: query required: false description: | - Selects `in` or `out` direction for edges. If not set, any edges are - returned. + - `"in"`: Return edges that reference the `vertex` in the `_to` attribute. + - `"out"`: Return edges that reference the `vertex` in the `_from` attribute. + - `"any"`: Return edges that reference the `vertex` in the `_from` or `_to` attribute. schema: type: string + enum: [any, in, out] + default: any - name: x-arango-allow-dirty-read in: header required: false diff --git a/site/content/3.12/develop/http-api/graphs/named-graphs.md b/site/content/3.12/develop/http-api/graphs/named-graphs.md index be0afc9d77..e6feb4cd31 100644 --- a/site/content/3.12/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.12/develop/http-api/graphs/named-graphs.md @@ -282,11 +282,13 @@ paths: description: | Define if the created graph should be smart (Enterprise Edition only). type: boolean + default: false isDisjoint: description: | Whether to create a Disjoint SmartGraph instead of a regular SmartGraph (Enterprise Edition only). type: boolean + default: false options: description: | a JSON object to define options for creating collections within this graph. @@ -295,7 +297,7 @@ paths: properties: smartGraphAttribute: description: | - Only has effect in Enterprise Edition and it is required if isSmart is true. + Only has effect in Enterprise Edition and it is required if `isSmart` is `true`. The attribute name that is used to smartly shard the vertices of a graph. Every vertex in this SmartGraph has to have this attribute. Cannot be modified later. @@ -1171,6 +1173,7 @@ paths: dropped if they are not used in other graphs. schema: type: boolean + default: false responses: '202': description: | @@ -2877,6 +2880,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false requestBody: content: application/json: @@ -3342,6 +3346,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false responses: '201': description: | @@ -3732,6 +3737,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -3744,14 +3750,9 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to store as a vertex document. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to be the JSON object to be stored. - type: object responses: '201': description: | @@ -4057,22 +4058,23 @@ paths: in: query required: false description: | - Must contain a revision. - If this is set a document is only returned if - it has exactly this revision. - Also see if-match header as an alternative to this. + If set, the document is only returned if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. schema: type: string - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an query parameter `rev`. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is returned if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - - name: if-none-match + - name: If-None-Match in: header required: false description: | @@ -4134,7 +4136,7 @@ paths: type: string '304': description: | - Returned if the if-none-match header is given and the + Returned if the `If-None-Match` header is given and the currently stored vertex still has this revision value. So there was no update between the last time the vertex was fetched by the caller. @@ -4272,7 +4274,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -4362,6 +4364,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only updated if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -4380,6 +4391,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4388,6 +4400,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4396,13 +4409,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -4417,14 +4433,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object containing exactly the attributes + that should be overwritten. All other attributes remain unchanged. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged. - type: object responses: '200': description: | @@ -4712,7 +4724,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -4805,6 +4817,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only replaced if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -4823,6 +4844,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4831,6 +4853,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4839,13 +4862,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -4860,14 +4886,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to replace the existing + vertex document with. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to be the JSON object to be stored. - type: object responses: '200': description: | @@ -5155,7 +5177,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -5250,6 +5272,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only deleted if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -5265,11 +5296,12 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, + If the `If-Match` header is given, then it must contain exactly one ETag. The document is updated, if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative you can supply the ETag in an attribute rev in the URL. schema: @@ -5487,7 +5519,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -5589,6 +5621,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -5601,6 +5634,8 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to store as an edge document. type: object required: - _from @@ -6000,22 +6035,23 @@ paths: in: query required: false description: | - Must contain a revision. - If this is set a document is only returned if - it has exactly this revision. - Also see if-match header as an alternative to this. + If set, the document is only returned if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. schema: type: string - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is returned if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - - name: if-none-match + - name: If-None-Match in: header required: false description: | @@ -6087,7 +6123,7 @@ paths: type: string '304': description: | - Returned if the if-none-match header is given and the + Returned if the `If-None-Match` header is given and the currently stored edge still has this revision value. So there was no update between the last time the edge was fetched by the caller. @@ -6225,7 +6261,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -6316,6 +6352,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only updated if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -6350,13 +6395,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -6371,14 +6419,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object containing exactly the attributes + that should be overwritten. All other attributes remain unchanged. type: object - required: - - edge - properties: - edge: - description: | - The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged. - type: object responses: '200': description: | @@ -6727,7 +6771,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -6820,6 +6864,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only replaced if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -6854,13 +6907,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is replaced if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -6875,6 +6931,9 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to replace an existing + edge document with. type: object required: - _from @@ -7238,7 +7297,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -7335,6 +7394,15 @@ paths: The `_key` attribute of the edge. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only deleted if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -7350,13 +7418,15 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is deleted if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -7592,7 +7662,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: diff --git a/site/content/3.12/develop/http-api/queries/aql-queries.md b/site/content/3.12/develop/http-api/queries/aql-queries.md index b795b42fd3..734fefdb1f 100644 --- a/site/content/3.12/develop/http-api/queries/aql-queries.md +++ b/site/content/3.12/develop/http-api/queries/aql-queries.md @@ -324,19 +324,21 @@ paths: type: string count: description: | - indicates whether the number of documents in the result set should be returned in - the "count" attribute of the result. - Calculating the "count" attribute might have a performance impact for some queries - in the future so this option is turned off by default, and "count" + Whether the number of documents in the result set should be returned in + the `count` attribute of the result. + Calculating this count might have a performance impact for some queries + in the future, so this option is turned off by default and `count` is only returned when requested. type: boolean + default: false batchSize: description: | - maximum number of result documents to be transferred from + The maximum number of result documents to be transferred from the server to the client in one roundtrip. If this attribute is not set, a server-controlled default value will be used. A `batchSize` value of `0` is disallowed. type: integer + default: 1000 ttl: description: | The time-to-live for the cursor (in seconds). If the result set is small enough @@ -344,16 +346,26 @@ paths: Otherwise they are stored in memory and will be accessible via the cursor with respect to the `ttl`. The cursor will be removed on the server automatically after the specified amount of time. This is useful to ensure garbage collection - of cursors that are not fully fetched by clients. If not set, a server-defined - value will be used (default: 30 seconds). + of cursors that are not fully fetched by clients. + + You can configure a default TTL with the `--query.registry-ttl` startup option. + If not set, the defaults are 30 seconds for single servers and 600 seconds for + Coordinators of a cluster deployment. + The time-to-live is renewed upon every access to the cursor. type: integer memoryLimit: description: | - the maximum number of memory (measured in bytes) that the query is allowed to - use. If set, then the query will fail with error "resource limit exceeded" in - case it allocates too much memory. A value of `0` indicates that there is no - memory limit. + The maximum amount of memory (in bytes) that the query is allowed to + use. If set, then the query fails with error "resource limit exceeded" in + case it allocates too much memory. A value of `0` indicates that there is + no memory limit, but the `--query.global-memory-limit` startup option + may still limit it. + + You can configure a default per-query memory limit with the + `--query.memory-limit` startup option. You can only increase + this default memory limit if `--query.memory-limit-override` + is enabled. type: integer bindVars: description: | @@ -369,7 +381,7 @@ paths: properties: fullCount: description: | - if set to `true` and the query contains a `LIMIT` clause, then the + If set to `true` and the query contains a `LIMIT` clause, then the result will have an `extra` attribute with the sub-attributes `stats` and `fullCount`, `{ ... , "extra": { "stats": { "fullCount": 123 } } }`. The `fullCount` attribute will contain the number of documents in the result before the @@ -381,16 +393,18 @@ paths: be present in the result if the query has a top-level LIMIT clause and the LIMIT clause is actually used in the query. type: boolean + default: false fillBlockCache: description: | - if set to `true` or not specified, this will make the query store the data it + If set to `true`, then the query stores the data it reads via the RocksDB storage engine in the RocksDB block cache. This is usually the desired behavior. The option can be set to `false` for queries that are known to either read a lot of data which would thrash the block cache, or for queries that read data which are known to be outside of the hot set. By setting the option - to `false`, data read by the query will not make it into the RocksDB block cache if + to `false`, data read by the query does not make it into the RocksDB block cache if not already in there, thus leaving more room for the actual hot set. type: boolean + default: true maxNumberOfPlans: description: | Limits the maximum number of plans that are created by the AQL query optimizer. @@ -406,23 +420,23 @@ paths: type: integer maxWarningCount: description: | - Limits the maximum number of warnings a query will return. The number of warnings - a query will return is limited to 10 by default, but that number can be increased - or decreased by setting this attribute. + Limits the number of warnings a query can return. + You can increased or decreased the number with this option. type: integer + default: 10 failOnWarning: description: | - When set to `true`, the query will throw an exception and abort instead of producing + If set to `true`, the query throws an exception and aborts instead of producing a warning. This option should be used during development to catch potential issues - early. When the attribute is set to `false`, warnings will not be propagated to - exceptions and will be returned with the query result. - There is also a server configuration option `--query.fail-on-warning` for setting the - default value for `failOnWarning` so it does not need to be set on a per-query level. + early. When the attribute is set to `false`, warnings are not propagated to + exceptions and are returned with the query result. + There is also a `--query.fail-on-warning` startup option for setting the + default value for `failOnWarning`, so it does not need to be set on a per-query basis. type: boolean allowRetry: description: | Set this option to `true` to make it possible to retry - fetching the latest batch from a cursor. The default is `false`. + fetching the latest batch from a cursor. If retrieving a result batch fails because of a connection issue, you can ask for that batch again using the `POST /_api/cursor//` @@ -453,6 +467,7 @@ paths: server doesn't unnecessarily keep the batch until the cursor times out (`ttl` query option). type: boolean + default: false stream: description: | Can be enabled to execute the query lazily. If set to `true`, then the query is @@ -481,12 +496,13 @@ paths: - Query statistics, profiling data and warnings are delivered as part of the last batch. - If the `stream` option is `false` (default), then the complete result of the + If the `stream` option is `false`, then the complete result of the query is calculated before any of it is returned to the client. The server stores the full result in memory (on the contacted Coordinator if in a cluster). All other resources are freed immediately (locks, RocksDB snapshots). The query will fail before it returns results in case of a conflict. type: boolean + default: false cache: description: | Whether the [AQL query results cache](../../../aql/execution-and-performance/caching-query-results.md) @@ -500,6 +516,8 @@ paths: If you set the `cache` option to `false`, then any query cache lookup is skipped for the query. If you set it to `true`, the query cache is checked for a cached result **if** the query cache mode is either set to `on` or `demand`. + + You can configure a default mode with the `--query.cache-mode` startup option. type: boolean usePlanCache: description: | @@ -527,7 +545,9 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: 128MB. + Default value: 128 MiB, respectively the value of the + `--temp.intermediate-results-spillover-threshold-memory-usage` + startup option. {{}} Spilling data from RAM onto disk is an experimental feature and is turned off @@ -550,7 +570,9 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: `5000000` rows. + Default value: 5 million rows, respectively the value of the + `--temp.intermediate-results-spillover-threshold-num-rows` + startup option. {{}} Spilling data from RAM onto disk is an experimental feature and is turned off @@ -588,11 +610,13 @@ paths: The default value is `60.0` seconds. When the maximal time is reached, the query is stopped. type: number + default: 60.0 maxRuntime: description: | The query has to be executed within the given runtime or it is killed. The value is specified in seconds. The default value is `0.0` (no timeout). type: number + default: 0.0 maxDNFConditionMembers: description: | A threshold for the maximum number of `OR` sub-nodes in the internal @@ -615,16 +639,22 @@ paths: maxTransactionSize: description: | The transaction size limit in bytes. + + You can configure the default with the `--rocksdb.max-transaction-size` startup option. type: integer intermediateCommitSize: description: | The maximum total size of operations after which an intermediate commit is performed automatically. + + You can configure the default with the `--rocksdb.intermediate-commit-size` startup option. type: integer intermediateCommitCount: description: | The maximum number of operations after which an intermediate commit is performed automatically. + + You can configure the default with the `--rocksdb.intermediate-commit-count` startup option. type: integer skipInaccessibleCollections: description: | @@ -2642,43 +2672,52 @@ paths: application/json: schema: type: object - required: - - enabled - - trackSlowQueries - - trackBindVars - - maxSlowQueries - - slowQueryThreshold - - maxQueryStringLength properties: enabled: description: | - If set to `true`, then queries will be tracked. If set to - `false`, neither queries nor slow queries will be tracked. + If set to `true`, then queries are tracked. If set to + `false`, neither regular queries nor slow queries are tracked. + + You can configure the default value with the `--query.tracking` startup option. type: boolean trackSlowQueries: description: | - If set to `true`, then slow queries will be tracked + If set to `true`, then slow queries are tracked in the list of slow queries if their runtime exceeds the value set in `slowQueryThreshold`. In order for slow queries to be tracked, the `enabled` property must also be set to `true`. + + You can configure the default value with the `--query.tracking-slow-queries` startup option. type: boolean trackBindVars: description: | - If set to `true`, then the bind variables used in queries will be tracked + If set to `true`, then the bind variables used in queries are tracked along with queries. + + You can configure the default value with the `--query.tracking-with-bindvars` startup option. type: boolean maxSlowQueries: description: | The maximum number of slow queries to keep in the list - of slow queries. If the list of slow queries is full, the oldest entry in - it will be discarded when additional slow queries occur. + of slow queries. If the list of slow queries is full, the oldest entry + is discarded when additional slow queries occur. type: integer slowQueryThreshold: description: | - The threshold value for treating a query as slow. A - query with a runtime greater or equal to this threshold value will be - put into the list of slow queries when slow query tracking is enabled. - The value for `slowQueryThreshold` is specified in seconds. + The threshold value for treating a query as slow (in seconds). + A query with a runtime greater or equal to this threshold value is + put into the list of slow queries if slow query tracking is enabled. + + You can configure the default value with the `--query.slow-threshold` startup option. + type: integer + slowStreamingQueryThreshold: + description: | + The threshold value for treating a streaming query as slow (in seconds). + A query with `"stream"` set to `true` and a runtime greater or equal to this + threshold value is put into the list of slow queries if slow query tracking + is enabled. + + You can configure the default value with the `--query.slow-streaming-threshold` startup option. type: integer maxQueryStringLength: description: | @@ -2686,7 +2725,11 @@ paths: Query strings can have arbitrary lengths, and this property can be used to save memory in case very long query strings are used. The value is specified in bytes. + + You can disable the tracking of query strings with the + `--query.tracking-with-querystring` startup option. type: integer + default: 4096 responses: '200': description: | @@ -2922,12 +2965,13 @@ paths: in: query required: false description: | - If set to `true`, will attempt to kill the specified query in all databases, + If set to `true`, attempt to kill the specified query in all databases, not just the selected one. Using the parameter is only allowed in the `_system` database and with superuser privileges. schema: type: boolean + default: false responses: '200': description: | @@ -3045,6 +3089,7 @@ paths: if set to `true`, all possible execution plans will be returned. The default is `false`, meaning only the optimal plan will be returned. type: boolean + default: false maxNumberOfPlans: description: | The maximum number of plans that the optimizer is allowed to @@ -3058,6 +3103,7 @@ paths: were not applied. This option generally leads to different execution plans. type: boolean + default: false profile: description: | Whether to include additional query profiling information. @@ -3075,9 +3121,10 @@ paths: type: integer maxWarningCount: description: | - Limits the number of warnings a query can return. The maximum number of warnings - is `10` by default but you can increase or decrease the limit. + Limits the number of warnings a query can return. + You can increased or decreased the number with this option. type: integer + default: 10 failOnWarning: description: | If set to `true`, the query throws an exception and aborts instead of producing diff --git a/site/content/3.12/develop/http-api/users.md b/site/content/3.12/develop/http-api/users.md index 561aa5bc38..37b6407ad3 100644 --- a/site/content/3.12/develop/http-api/users.md +++ b/site/content/3.12/develop/http-api/users.md @@ -68,9 +68,9 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. If not - specified, this will default to `true`. + Whether the user account should be able to log in to the database system. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface @@ -161,9 +161,9 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. If not - specified, this will default to *true*. + Whether the user account should be able to log in to the database system. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface @@ -255,7 +255,7 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. + Whether the user account should be able to log in to the database system. type: boolean extra: description: | @@ -455,7 +455,7 @@ paths: attributes on success: - `user`: The name of the user as a string. - - `active`: An optional flag that specifies whether the user is active. + - `active`: Whether the user account is able to log in to the database system. - `extra`: A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. parameters: @@ -522,10 +522,11 @@ paths: properties: grant: description: | - - Use "rw" to set the database access level to *Administrate*. - - Use "ro" to set the database access level to *Access*. - - Use "none" to set the database access level to *No access*. + - `"rw"`: Set the database access level to *Administrate*. + - `"ro"`: Set the database access level to *Access*. + - `"none"`: Set the database access level to *No access*. type: string + enum: [rw, ro, none] parameters: - name: database-name in: path @@ -612,12 +613,11 @@ paths: properties: grant: description: | - Use "rw" to set the collection level access to *Read/Write*. - - Use "ro" to set the collection level access to *Read Only*. - - Use "none" to set the collection level access to *No access*. + - `"rw"`: Set the collection access level to *Read/Write*. + - `"ro"`: Set the collection access level to *Read Only*. + - `"none"`: Set the collection access level to *No access*. type: string + enum: [rw, ro, none] parameters: - name: database-name in: path diff --git a/site/content/3.13/develop/http-api/collections.md b/site/content/3.13/develop/http-api/collections.md index d49d4cb066..01a3e978f0 100644 --- a/site/content/3.13/develop/http-api/collections.md +++ b/site/content/3.13/develop/http-api/collections.md @@ -2824,6 +2824,7 @@ paths: keys are generated on the leader DB-Server, which has full control over the key sequence. type: string + default: traditional allowUserKeys: description: | If set to `true`, then you are allowed to supply own key values in the @@ -2839,6 +2840,7 @@ paths: auto-generate keys in this case are not aware of all keys which are already used. {{}} type: boolean + default: true increment: description: | The increment value for the `autoincrement` key generator. @@ -5183,381 +5185,3 @@ logJsonResponse(response); db._drop(cn); ``` - -### Load a collection - -```openapi -paths: - /_db/{database-name}/_api/collection/{collection-name}/load: - put: - operationId: loadCollection - description: | - {{}} - The load function is deprecated from version 3.8.0 onwards and is a no-op - from version 3.9.0 onwards. It should no longer be used, as it may be removed - in a future version of ArangoDB. - {{}} - - Since ArangoDB version 3.9.0 this API does nothing. Previously, it used to - load a collection into memory. - parameters: - - name: database-name - in: path - required: true - example: _system - description: | - The name of the database. - schema: - type: string - - name: collection-name - in: path - required: true - description: | - The name of the collection. - - {{}} - Accessing collections by their numeric ID is deprecated from version 3.4.0 on. - You should reference them via their names instead. - {{}} - schema: - type: string - responses: - '200': - description: | - Returns the basic collection properties for compatibility reasons. - content: - application/json: - schema: - type: object - required: - - error - - code - - name - - type - - isSystem - - status - - id - - globallyUniqueId - properties: - error: - description: | - A flag indicating that no error occurred. - type: boolean - example: false - code: - description: | - The HTTP response status code. - type: integer - example: 200 - name: - description: | - The name of the collection. - type: string - example: coll - type: - description: | - The type of the collection: - - `0`: "unknown" - - `2`: regular document collection - - `3`: edge collection - type: integer - example: 2 - isSystem: - description: | - Whether the collection is a system collection. Collection names that starts with - an underscore are usually system collections. - type: boolean - example: false - status: - description: | - The status of the collection. - - `3`: loaded - - `5`: deleted - - Every other status indicates a corrupted collection. - type: integer - example: 3 - id: - description: | - A unique identifier of the collection (deprecated). - type: string - globallyUniqueId: - description: | - A unique identifier of the collection. This is an internal property. - type: string - count: - description: | - The number of documents currently present in the collection. - type: integer - '400': - description: | - The `collection-name` parameter or the `name` attribute is missing. - content: - application/json: - schema: - type: object - required: - - error - - code - - errorNum - - errorMessage - properties: - error: - description: | - A flag indicating that an error occurred. - type: boolean - example: true - code: - description: | - The HTTP response status code. - type: integer - example: 400 - errorNum: - description: | - ArangoDB error number for the error that occurred. - type: integer - errorMessage: - description: | - A descriptive error message. - type: string - '404': - description: | - A collection called `collection-name` could not be found. - content: - application/json: - schema: - type: object - required: - - error - - code - - errorNum - - errorMessage - properties: - error: - description: | - A flag indicating that an error occurred. - type: boolean - example: true - code: - description: | - The HTTP response status code. - type: integer - example: 404 - errorNum: - description: | - ArangoDB error number for the error that occurred. - type: integer - errorMessage: - description: | - A descriptive error message. - type: string - tags: - - Collections -``` - -**Examples** - -```curl ---- -description: '' -name: RestCollectionIdentifierLoad ---- -var cn = "products"; -db._drop(cn); -var coll = db._create(cn, { waitForSync: true }); -var url = "/_api/collection/"+ coll.name() + "/load"; - -var response = logCurlRequest('PUT', url, ''); - -assert(response.code === 200); - -logJsonResponse(response); -db._drop(cn); -``` - -### Unload a collection - -```openapi -paths: - /_db/{database-name}/_api/collection/{collection-name}/unload: - put: - operationId: unloadCollection - description: | - {{}} - The unload function is deprecated from version 3.8.0 onwards and is a no-op - from version 3.9.0 onwards. It should no longer be used, as it may be removed - in a future version of ArangoDB. - {{}} - - Since ArangoDB version 3.9.0 this API does nothing. Previously it used to - unload a collection from memory, while preserving all documents. - parameters: - - name: database-name - in: path - required: true - example: _system - description: | - The name of the database. - schema: - type: string - - name: collection-name - in: path - required: true - description: | - The name of the collection. - - {{}} - Accessing collections by their numeric ID is deprecated from version 3.4.0 on. - You should reference them via their names instead. - {{}} - schema: - type: string - responses: - '200': - description: | - Returns the basic collection properties for compatibility reasons. - content: - application/json: - schema: - type: object - required: - - error - - code - - name - - type - - isSystem - - status - - id - - globallyUniqueId - properties: - error: - description: | - A flag indicating that no error occurred. - type: boolean - example: false - code: - description: | - The HTTP response status code. - type: integer - example: 200 - name: - description: | - The name of the collection. - type: string - example: coll - type: - description: | - The type of the collection: - - `0`: "unknown" - - `2`: regular document collection - - `3`: edge collection - type: integer - example: 2 - isSystem: - description: | - Whether the collection is a system collection. Collection names that starts with - an underscore are usually system collections. - type: boolean - example: false - status: - description: | - The status of the collection. - - `3`: loaded - - `5`: deleted - - Every other status indicates a corrupted collection. - type: integer - example: 3 - id: - description: | - A unique identifier of the collection (deprecated). - type: string - globallyUniqueId: - description: | - A unique identifier of the collection. This is an internal property. - type: string - '400': - description: | - The `collection-name` parameter or the `name` attribute is missing. - content: - application/json: - schema: - type: object - required: - - error - - code - - errorNum - - errorMessage - properties: - error: - description: | - A flag indicating that an error occurred. - type: boolean - example: true - code: - description: | - The HTTP response status code. - type: integer - example: 400 - errorNum: - description: | - ArangoDB error number for the error that occurred. - type: integer - errorMessage: - description: | - A descriptive error message. - type: string - '404': - description: | - A collection called `collection-name` could not be found. - content: - application/json: - schema: - type: object - required: - - error - - code - - errorNum - - errorMessage - properties: - error: - description: | - A flag indicating that an error occurred. - type: boolean - example: true - code: - description: | - The HTTP response status code. - type: integer - example: 404 - errorNum: - description: | - ArangoDB error number for the error that occurred. - type: integer - errorMessage: - description: | - A descriptive error message. - type: string - tags: - - Collections -``` - -**Examples** - -```curl ---- -description: '' -name: RestCollectionIdentifierUnload ---- -var cn = "products"; -db._drop(cn); -var coll = db._create(cn, { waitForSync: true }); -var url = "/_api/collection/"+ coll.name() + "/unload"; - -var response = logCurlRequest('PUT', url, ''); - -assert(response.code === 200); - -logJsonResponse(response); -db._drop(cn); -``` diff --git a/site/content/3.13/develop/http-api/databases.md b/site/content/3.13/develop/http-api/databases.md index 7cf6c7ad76..098a39053e 100644 --- a/site/content/3.13/develop/http-api/databases.md +++ b/site/content/3.13/develop/http-api/databases.md @@ -243,10 +243,10 @@ paths: description: | The sharding method to use for new collections in this database. _(cluster only)_ Valid values are: - - `""` or `"flexible"`: Create a database where collections can have any - number of shards and the shards can reside on different DB-Servers. + - `""` or `"flexible"`: Create a database where collections can + be sharded independently. - `"single"`: Create a OneShard database where all collections have a - single shard and the shards are placed on the same DB-Server. + single shard and all leader shards are co-located on the same DB-Server. type: string enum: ["", flexible, single] default: "" @@ -296,11 +296,11 @@ paths: type: string active: description: | - A flag indicating whether the user account should be activated or not. - The default value is `true`. If set to `false`, then the user won't be able to - log into the database. The default is `true`. The attribute is ignored for users - that already exist. + Whether the user account should be able to log in to the database system. + + The attribute is ignored for users that already exist. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface diff --git a/site/content/3.13/develop/http-api/documents.md b/site/content/3.13/develop/http-api/documents.md index ea7d55f4c9..1c0d9352a6 100644 --- a/site/content/3.13/develop/http-api/documents.md +++ b/site/content/3.13/develop/http-api/documents.md @@ -120,7 +120,7 @@ paths: in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one + If the `If-Match` header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a *HTTP 412* is returned. schema: @@ -284,7 +284,7 @@ paths: in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one + If the `If-Match` header is given, then it must contain exactly one ETag. The document is returned, if it has the same revision as the given ETag. Otherwise a *HTTP 412* is returned. schema: @@ -435,6 +435,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -443,6 +444,7 @@ paths: in the result. Only available if the overwrite option is used. schema: type: boolean + default: false - name: silent in: query required: false @@ -454,6 +456,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -497,13 +500,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the update-insert - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only. schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -511,10 +515,11 @@ paths: Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to `false`, the value in the patch document overwrites the existing document's value. If set to `true`, - objects are merged. The default is `true`. + objects are merged. This option controls the update-insert behavior only. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -523,6 +528,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -888,13 +894,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given document is ignored. If this is set to `false`, then the `_rev` attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -903,6 +910,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -911,6 +919,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -922,6 +931,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -930,6 +940,7 @@ paths: replacements affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -960,7 +971,7 @@ paths: required: false description: | 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. schema: type: string - name: x-arango-trx-id @@ -1217,13 +1228,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the patch - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -1231,10 +1243,10 @@ paths: Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to `false`, the value in the patch document overwrites the existing document's - value. If set to `true`, objects are merged. The default is - `true`. + value. If set to `true`, objects are merged. schema: type: boolean + default: true - name: waitForSync in: query required: false @@ -1246,13 +1258,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given document is ignored. If this is set to `false`, then the `_rev` attribute given in the body document is taken as a precondition. The document is only updated if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -1261,6 +1274,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -1269,6 +1283,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1280,6 +1295,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1288,6 +1304,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -1318,7 +1335,7 @@ paths: required: false description: | You can conditionally update a document based on a target revision id by - using the `if-match` HTTP header. + using the `If-Match` HTTP header. schema: type: string - name: x-arango-trx-id @@ -1539,6 +1556,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1550,6 +1568,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1558,12 +1577,13 @@ paths: if document removals affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: If-Match in: header required: false description: | You can conditionally remove a document based on a target revision id by - using the `if-match` HTTP header. + using the `If-Match` HTTP header. schema: type: string - name: x-arango-trx-id @@ -1809,12 +1829,12 @@ paths: in: query required: false description: | - Should the value be `true` (the default): - If a search document contains a value for the `_rev` field, - then the document is only returned if it has the same revision value. - Otherwise a precondition failed error is returned. + If set to `false` and a `_rev` attribute is included in the request, + then the document is only returned if it has the same revision. + Otherwise, a precondition failed error is returned for the document. schema: type: string + default: true - name: x-arango-allow-dirty-read in: header required: false @@ -1976,6 +1996,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -1984,6 +2005,7 @@ paths: in the result. Only available if the overwrite option is used. schema: type: boolean + default: false - name: silent in: query required: false @@ -1996,6 +2018,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -2039,13 +2062,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the update-insert - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). This option controls the update-insert behavior only. schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -2053,10 +2077,11 @@ paths: Controls whether objects (not arrays) are merged if present in both, the existing and the update-insert document. If set to `false`, the value in the patch document overwrites the existing document's value. If set to `true`, - objects are merged. The default is `true`. + objects are merged. This option controls the update-insert behavior only. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -2065,6 +2090,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2320,13 +2346,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given documents are ignored. If this is set to `false`, then any `_rev` attribute given in a body document is taken as a precondition. The document is only replaced if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -2335,6 +2362,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2343,6 +2371,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2355,6 +2384,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2363,6 +2393,7 @@ paths: replacements affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2550,13 +2581,14 @@ paths: required: false description: | If the intention is to delete existing attributes with the patch - command, set the `keepNull` URL query parameter to `false`. This modifies the + command, set the `keepNull` query parameter to `false`. This modifies the behavior of the patch command to remove top-level attributes and sub-attributes from the existing document that are contained in the patch document with an attribute value of `null` (but not attributes of objects that are nested inside of arrays). schema: type: boolean + default: true - name: mergeObjects in: query required: false @@ -2564,10 +2596,10 @@ paths: Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to `false`, the value in the patch document overwrites the existing document's - value. If set to `true`, objects are merged. The default is - `true`. + value. If set to `true`, objects are merged. schema: type: boolean + default: true - name: waitForSync in: query required: false @@ -2579,13 +2611,14 @@ paths: in: query required: false description: | - By default, or if this is set to `true`, the `_rev` attributes in + If set to `true`, the `_rev` attributes in the given documents are ignored. If this is set to `false`, then any `_rev` attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified. schema: type: boolean + default: true - name: returnOld in: query required: false @@ -2594,6 +2627,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2602,6 +2636,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2614,6 +2649,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2622,6 +2658,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2810,11 +2847,11 @@ paths: in: query required: false description: | - If set to `true`, ignore any `_rev` attribute in the selectors. No - revision check is performed. If set to `false` then revisions are checked. - The default is `true`. + If set to `true`, ignore any `_rev` attribute included in the request. No + revision check is performed. If set to `false`, then revisions are checked. schema: type: boolean + default: true - name: refillIndexCaches in: query required: false @@ -2823,6 +2860,7 @@ paths: if document removals affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false diff --git a/site/content/3.13/develop/http-api/graphs/edges.md b/site/content/3.13/develop/http-api/graphs/edges.md index 84174885c8..7daeaca862 100644 --- a/site/content/3.13/develop/http-api/graphs/edges.md +++ b/site/content/3.13/develop/http-api/graphs/edges.md @@ -29,7 +29,7 @@ for details. ```openapi paths: - /_db/{database-name}/_api/edges/{collection-id}: + /_db/{database-name}/_api/edges/{collection}: get: operationId: getVertexEdges description: | @@ -44,11 +44,11 @@ paths: The name of the database. schema: type: string - - name: collection-id + - name: collection in: path required: true description: | - The id of the collection. + The name of the edge collection you want to retrieve edges from. schema: type: string - name: vertex @@ -62,10 +62,13 @@ paths: in: query required: false description: | - Selects `in` or `out` direction for edges. If not set, any edges are - returned. + - `"in"`: Return edges that reference the `vertex` in the `_to` attribute. + - `"out"`: Return edges that reference the `vertex` in the `_from` attribute. + - `"any"`: Return edges that reference the `vertex` in the `_from` or `_to` attribute. schema: type: string + enum: [any, in, out] + default: any - name: x-arango-allow-dirty-read in: header required: false diff --git a/site/content/3.13/develop/http-api/graphs/named-graphs.md b/site/content/3.13/develop/http-api/graphs/named-graphs.md index be0afc9d77..e6feb4cd31 100644 --- a/site/content/3.13/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.13/develop/http-api/graphs/named-graphs.md @@ -282,11 +282,13 @@ paths: description: | Define if the created graph should be smart (Enterprise Edition only). type: boolean + default: false isDisjoint: description: | Whether to create a Disjoint SmartGraph instead of a regular SmartGraph (Enterprise Edition only). type: boolean + default: false options: description: | a JSON object to define options for creating collections within this graph. @@ -295,7 +297,7 @@ paths: properties: smartGraphAttribute: description: | - Only has effect in Enterprise Edition and it is required if isSmart is true. + Only has effect in Enterprise Edition and it is required if `isSmart` is `true`. The attribute name that is used to smartly shard the vertices of a graph. Every vertex in this SmartGraph has to have this attribute. Cannot be modified later. @@ -1171,6 +1173,7 @@ paths: dropped if they are not used in other graphs. schema: type: boolean + default: false responses: '202': description: | @@ -2877,6 +2880,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false requestBody: content: application/json: @@ -3342,6 +3346,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false responses: '201': description: | @@ -3732,6 +3737,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -3744,14 +3750,9 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to store as a vertex document. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to be the JSON object to be stored. - type: object responses: '201': description: | @@ -4057,22 +4058,23 @@ paths: in: query required: false description: | - Must contain a revision. - If this is set a document is only returned if - it has exactly this revision. - Also see if-match header as an alternative to this. + If set, the document is only returned if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. schema: type: string - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an query parameter `rev`. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is returned if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - - name: if-none-match + - name: If-None-Match in: header required: false description: | @@ -4134,7 +4136,7 @@ paths: type: string '304': description: | - Returned if the if-none-match header is given and the + Returned if the `If-None-Match` header is given and the currently stored vertex still has this revision value. So there was no update between the last time the vertex was fetched by the caller. @@ -4272,7 +4274,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -4362,6 +4364,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only updated if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -4380,6 +4391,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4388,6 +4400,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4396,13 +4409,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -4417,14 +4433,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object containing exactly the attributes + that should be overwritten. All other attributes remain unchanged. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged. - type: object responses: '200': description: | @@ -4712,7 +4724,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -4805,6 +4817,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only replaced if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -4823,6 +4844,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4831,6 +4853,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4839,13 +4862,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -4860,14 +4886,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to replace the existing + vertex document with. type: object - required: - - vertex - properties: - vertex: - description: | - The body has to be the JSON object to be stored. - type: object responses: '200': description: | @@ -5155,7 +5177,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -5250,6 +5272,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only deleted if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -5265,11 +5296,12 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, + If the `If-Match` header is given, then it must contain exactly one ETag. The document is updated, if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative you can supply the ETag in an attribute rev in the URL. schema: @@ -5487,7 +5519,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -5589,6 +5621,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -5601,6 +5634,8 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to store as an edge document. type: object required: - _from @@ -6000,22 +6035,23 @@ paths: in: query required: false description: | - Must contain a revision. - If this is set a document is only returned if - it has exactly this revision. - Also see if-match header as an alternative to this. + If set, the document is only returned if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. schema: type: string - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is returned, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is returned if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - - name: if-none-match + - name: If-None-Match in: header required: false description: | @@ -6087,7 +6123,7 @@ paths: type: string '304': description: | - Returned if the if-none-match header is given and the + Returned if the `If-None-Match` header is given and the currently stored edge still has this revision value. So there was no update between the last time the edge was fetched by the caller. @@ -6225,7 +6261,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -6316,6 +6352,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only updated if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -6350,13 +6395,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is updated if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -6371,14 +6419,10 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object containing exactly the attributes + that should be overwritten. All other attributes remain unchanged. type: object - required: - - edge - properties: - edge: - description: | - The body has to contain a JSON object containing exactly the attributes that should be overwritten, all other attributes remain unchanged. - type: object responses: '200': description: | @@ -6727,7 +6771,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -6820,6 +6864,15 @@ paths: The `_key` attribute of the vertex. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only replaced if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -6854,13 +6907,16 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + default: false + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is replaced if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -6875,6 +6931,9 @@ paths: content: application/json: schema: + description: | + The body has to be a JSON object you want to replace an existing + edge document with. type: object required: - _from @@ -7238,7 +7297,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: @@ -7335,6 +7394,15 @@ paths: The `_key` attribute of the edge. schema: type: string + - name: rev + in: query + required: false + description: | + If set, the document is only deleted if it has exactly this revision. + + As an alternative, you can use the `If-Match` header to specify the revision. + schema: + type: string - name: waitForSync in: query required: false @@ -7350,13 +7418,15 @@ paths: be returned within the response object. schema: type: boolean - - name: if-match + - name: If-Match in: header required: false description: | - If the "If-Match" header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If the `If-Match` header is given, then it must contain exactly one ETag. + The document is deleted if it has the same revision as the given ETag. + Otherwise, an error with an HTTP status code of 412 is returned. + + As an alternative, you can supply the ETag in the `rev` query parameter. schema: type: string - name: x-arango-trx-id @@ -7592,7 +7662,7 @@ paths: type: string '412': description: | - Returned if if-match header is given, but the stored documents revision is different. + Returned if the `If-Match` header is given, but the stored documents revision is different. content: application/json: schema: diff --git a/site/content/3.13/develop/http-api/queries/aql-queries.md b/site/content/3.13/develop/http-api/queries/aql-queries.md index b795b42fd3..734fefdb1f 100644 --- a/site/content/3.13/develop/http-api/queries/aql-queries.md +++ b/site/content/3.13/develop/http-api/queries/aql-queries.md @@ -324,19 +324,21 @@ paths: type: string count: description: | - indicates whether the number of documents in the result set should be returned in - the "count" attribute of the result. - Calculating the "count" attribute might have a performance impact for some queries - in the future so this option is turned off by default, and "count" + Whether the number of documents in the result set should be returned in + the `count` attribute of the result. + Calculating this count might have a performance impact for some queries + in the future, so this option is turned off by default and `count` is only returned when requested. type: boolean + default: false batchSize: description: | - maximum number of result documents to be transferred from + The maximum number of result documents to be transferred from the server to the client in one roundtrip. If this attribute is not set, a server-controlled default value will be used. A `batchSize` value of `0` is disallowed. type: integer + default: 1000 ttl: description: | The time-to-live for the cursor (in seconds). If the result set is small enough @@ -344,16 +346,26 @@ paths: Otherwise they are stored in memory and will be accessible via the cursor with respect to the `ttl`. The cursor will be removed on the server automatically after the specified amount of time. This is useful to ensure garbage collection - of cursors that are not fully fetched by clients. If not set, a server-defined - value will be used (default: 30 seconds). + of cursors that are not fully fetched by clients. + + You can configure a default TTL with the `--query.registry-ttl` startup option. + If not set, the defaults are 30 seconds for single servers and 600 seconds for + Coordinators of a cluster deployment. + The time-to-live is renewed upon every access to the cursor. type: integer memoryLimit: description: | - the maximum number of memory (measured in bytes) that the query is allowed to - use. If set, then the query will fail with error "resource limit exceeded" in - case it allocates too much memory. A value of `0` indicates that there is no - memory limit. + The maximum amount of memory (in bytes) that the query is allowed to + use. If set, then the query fails with error "resource limit exceeded" in + case it allocates too much memory. A value of `0` indicates that there is + no memory limit, but the `--query.global-memory-limit` startup option + may still limit it. + + You can configure a default per-query memory limit with the + `--query.memory-limit` startup option. You can only increase + this default memory limit if `--query.memory-limit-override` + is enabled. type: integer bindVars: description: | @@ -369,7 +381,7 @@ paths: properties: fullCount: description: | - if set to `true` and the query contains a `LIMIT` clause, then the + If set to `true` and the query contains a `LIMIT` clause, then the result will have an `extra` attribute with the sub-attributes `stats` and `fullCount`, `{ ... , "extra": { "stats": { "fullCount": 123 } } }`. The `fullCount` attribute will contain the number of documents in the result before the @@ -381,16 +393,18 @@ paths: be present in the result if the query has a top-level LIMIT clause and the LIMIT clause is actually used in the query. type: boolean + default: false fillBlockCache: description: | - if set to `true` or not specified, this will make the query store the data it + If set to `true`, then the query stores the data it reads via the RocksDB storage engine in the RocksDB block cache. This is usually the desired behavior. The option can be set to `false` for queries that are known to either read a lot of data which would thrash the block cache, or for queries that read data which are known to be outside of the hot set. By setting the option - to `false`, data read by the query will not make it into the RocksDB block cache if + to `false`, data read by the query does not make it into the RocksDB block cache if not already in there, thus leaving more room for the actual hot set. type: boolean + default: true maxNumberOfPlans: description: | Limits the maximum number of plans that are created by the AQL query optimizer. @@ -406,23 +420,23 @@ paths: type: integer maxWarningCount: description: | - Limits the maximum number of warnings a query will return. The number of warnings - a query will return is limited to 10 by default, but that number can be increased - or decreased by setting this attribute. + Limits the number of warnings a query can return. + You can increased or decreased the number with this option. type: integer + default: 10 failOnWarning: description: | - When set to `true`, the query will throw an exception and abort instead of producing + If set to `true`, the query throws an exception and aborts instead of producing a warning. This option should be used during development to catch potential issues - early. When the attribute is set to `false`, warnings will not be propagated to - exceptions and will be returned with the query result. - There is also a server configuration option `--query.fail-on-warning` for setting the - default value for `failOnWarning` so it does not need to be set on a per-query level. + early. When the attribute is set to `false`, warnings are not propagated to + exceptions and are returned with the query result. + There is also a `--query.fail-on-warning` startup option for setting the + default value for `failOnWarning`, so it does not need to be set on a per-query basis. type: boolean allowRetry: description: | Set this option to `true` to make it possible to retry - fetching the latest batch from a cursor. The default is `false`. + fetching the latest batch from a cursor. If retrieving a result batch fails because of a connection issue, you can ask for that batch again using the `POST /_api/cursor//` @@ -453,6 +467,7 @@ paths: server doesn't unnecessarily keep the batch until the cursor times out (`ttl` query option). type: boolean + default: false stream: description: | Can be enabled to execute the query lazily. If set to `true`, then the query is @@ -481,12 +496,13 @@ paths: - Query statistics, profiling data and warnings are delivered as part of the last batch. - If the `stream` option is `false` (default), then the complete result of the + If the `stream` option is `false`, then the complete result of the query is calculated before any of it is returned to the client. The server stores the full result in memory (on the contacted Coordinator if in a cluster). All other resources are freed immediately (locks, RocksDB snapshots). The query will fail before it returns results in case of a conflict. type: boolean + default: false cache: description: | Whether the [AQL query results cache](../../../aql/execution-and-performance/caching-query-results.md) @@ -500,6 +516,8 @@ paths: If you set the `cache` option to `false`, then any query cache lookup is skipped for the query. If you set it to `true`, the query cache is checked for a cached result **if** the query cache mode is either set to `on` or `demand`. + + You can configure a default mode with the `--query.cache-mode` startup option. type: boolean usePlanCache: description: | @@ -527,7 +545,9 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: 128MB. + Default value: 128 MiB, respectively the value of the + `--temp.intermediate-results-spillover-threshold-memory-usage` + startup option. {{}} Spilling data from RAM onto disk is an experimental feature and is turned off @@ -550,7 +570,9 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: `5000000` rows. + Default value: 5 million rows, respectively the value of the + `--temp.intermediate-results-spillover-threshold-num-rows` + startup option. {{}} Spilling data from RAM onto disk is an experimental feature and is turned off @@ -588,11 +610,13 @@ paths: The default value is `60.0` seconds. When the maximal time is reached, the query is stopped. type: number + default: 60.0 maxRuntime: description: | The query has to be executed within the given runtime or it is killed. The value is specified in seconds. The default value is `0.0` (no timeout). type: number + default: 0.0 maxDNFConditionMembers: description: | A threshold for the maximum number of `OR` sub-nodes in the internal @@ -615,16 +639,22 @@ paths: maxTransactionSize: description: | The transaction size limit in bytes. + + You can configure the default with the `--rocksdb.max-transaction-size` startup option. type: integer intermediateCommitSize: description: | The maximum total size of operations after which an intermediate commit is performed automatically. + + You can configure the default with the `--rocksdb.intermediate-commit-size` startup option. type: integer intermediateCommitCount: description: | The maximum number of operations after which an intermediate commit is performed automatically. + + You can configure the default with the `--rocksdb.intermediate-commit-count` startup option. type: integer skipInaccessibleCollections: description: | @@ -2642,43 +2672,52 @@ paths: application/json: schema: type: object - required: - - enabled - - trackSlowQueries - - trackBindVars - - maxSlowQueries - - slowQueryThreshold - - maxQueryStringLength properties: enabled: description: | - If set to `true`, then queries will be tracked. If set to - `false`, neither queries nor slow queries will be tracked. + If set to `true`, then queries are tracked. If set to + `false`, neither regular queries nor slow queries are tracked. + + You can configure the default value with the `--query.tracking` startup option. type: boolean trackSlowQueries: description: | - If set to `true`, then slow queries will be tracked + If set to `true`, then slow queries are tracked in the list of slow queries if their runtime exceeds the value set in `slowQueryThreshold`. In order for slow queries to be tracked, the `enabled` property must also be set to `true`. + + You can configure the default value with the `--query.tracking-slow-queries` startup option. type: boolean trackBindVars: description: | - If set to `true`, then the bind variables used in queries will be tracked + If set to `true`, then the bind variables used in queries are tracked along with queries. + + You can configure the default value with the `--query.tracking-with-bindvars` startup option. type: boolean maxSlowQueries: description: | The maximum number of slow queries to keep in the list - of slow queries. If the list of slow queries is full, the oldest entry in - it will be discarded when additional slow queries occur. + of slow queries. If the list of slow queries is full, the oldest entry + is discarded when additional slow queries occur. type: integer slowQueryThreshold: description: | - The threshold value for treating a query as slow. A - query with a runtime greater or equal to this threshold value will be - put into the list of slow queries when slow query tracking is enabled. - The value for `slowQueryThreshold` is specified in seconds. + The threshold value for treating a query as slow (in seconds). + A query with a runtime greater or equal to this threshold value is + put into the list of slow queries if slow query tracking is enabled. + + You can configure the default value with the `--query.slow-threshold` startup option. + type: integer + slowStreamingQueryThreshold: + description: | + The threshold value for treating a streaming query as slow (in seconds). + A query with `"stream"` set to `true` and a runtime greater or equal to this + threshold value is put into the list of slow queries if slow query tracking + is enabled. + + You can configure the default value with the `--query.slow-streaming-threshold` startup option. type: integer maxQueryStringLength: description: | @@ -2686,7 +2725,11 @@ paths: Query strings can have arbitrary lengths, and this property can be used to save memory in case very long query strings are used. The value is specified in bytes. + + You can disable the tracking of query strings with the + `--query.tracking-with-querystring` startup option. type: integer + default: 4096 responses: '200': description: | @@ -2922,12 +2965,13 @@ paths: in: query required: false description: | - If set to `true`, will attempt to kill the specified query in all databases, + If set to `true`, attempt to kill the specified query in all databases, not just the selected one. Using the parameter is only allowed in the `_system` database and with superuser privileges. schema: type: boolean + default: false responses: '200': description: | @@ -3045,6 +3089,7 @@ paths: if set to `true`, all possible execution plans will be returned. The default is `false`, meaning only the optimal plan will be returned. type: boolean + default: false maxNumberOfPlans: description: | The maximum number of plans that the optimizer is allowed to @@ -3058,6 +3103,7 @@ paths: were not applied. This option generally leads to different execution plans. type: boolean + default: false profile: description: | Whether to include additional query profiling information. @@ -3075,9 +3121,10 @@ paths: type: integer maxWarningCount: description: | - Limits the number of warnings a query can return. The maximum number of warnings - is `10` by default but you can increase or decrease the limit. + Limits the number of warnings a query can return. + You can increased or decreased the number with this option. type: integer + default: 10 failOnWarning: description: | If set to `true`, the query throws an exception and aborts instead of producing diff --git a/site/content/3.13/develop/http-api/users.md b/site/content/3.13/develop/http-api/users.md index 561aa5bc38..37b6407ad3 100644 --- a/site/content/3.13/develop/http-api/users.md +++ b/site/content/3.13/develop/http-api/users.md @@ -68,9 +68,9 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. If not - specified, this will default to `true`. + Whether the user account should be able to log in to the database system. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface @@ -161,9 +161,9 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. If not - specified, this will default to *true*. + Whether the user account should be able to log in to the database system. type: boolean + default: true extra: description: | A JSON object with extra user information. It is used by the web interface @@ -255,7 +255,7 @@ paths: type: string active: description: | - An optional flag that specifies whether the user is active. + Whether the user account should be able to log in to the database system. type: boolean extra: description: | @@ -455,7 +455,7 @@ paths: attributes on success: - `user`: The name of the user as a string. - - `active`: An optional flag that specifies whether the user is active. + - `active`: Whether the user account is able to log in to the database system. - `extra`: A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. parameters: @@ -522,10 +522,11 @@ paths: properties: grant: description: | - - Use "rw" to set the database access level to *Administrate*. - - Use "ro" to set the database access level to *Access*. - - Use "none" to set the database access level to *No access*. + - `"rw"`: Set the database access level to *Administrate*. + - `"ro"`: Set the database access level to *Access*. + - `"none"`: Set the database access level to *No access*. type: string + enum: [rw, ro, none] parameters: - name: database-name in: path @@ -612,12 +613,11 @@ paths: properties: grant: description: | - Use "rw" to set the collection level access to *Read/Write*. - - Use "ro" to set the collection level access to *Read Only*. - - Use "none" to set the collection level access to *No access*. + - `"rw"`: Set the collection access level to *Read/Write*. + - `"ro"`: Set the collection access level to *Read Only*. + - `"none"`: Set the collection access level to *No access*. type: string + enum: [rw, ro, none] parameters: - name: database-name in: path From 7d44cefb53b4776dfeaf896b618c2eeaa26ca7e9 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 26 Jun 2025 00:05:47 +0200 Subject: [PATCH 03/13] Named graphs: Remove docs for superfluous rev query param, some rewording --- .../develop/http-api/graphs/named-graphs.md | 199 ++++++------------ .../develop/http-api/graphs/named-graphs.md | 186 ++++++---------- .../develop/http-api/graphs/named-graphs.md | 186 ++++++---------- 3 files changed, 194 insertions(+), 377 deletions(-) diff --git a/site/content/3.11/develop/http-api/graphs/named-graphs.md b/site/content/3.11/develop/http-api/graphs/named-graphs.md index e6feb4cd31..61ae8c002e 100644 --- a/site/content/3.11/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.11/develop/http-api/graphs/named-graphs.md @@ -258,16 +258,19 @@ paths: type: string from: description: | - List of vertex collection names. - Edges in collection can only be inserted if their _from is in any of the collections here. + A list of vertex collection names. + Edges you later insert into `collection` can only reference vertices + from these collections in their `_from` attribute (if you use the + interface for named graphs). type: array items: type: string to: description: | - List of vertex collection names. - - Edges in collection can only be inserted if their _to is in any of the collections here. + A list of vertex collection names. + Edges you later insert into `collection` can only reference vertices + from these collections in their `_to` attribute (if you use the + interface for named graphs). type: array items: type: string @@ -4025,6 +4028,8 @@ paths: description: | Gets a vertex from the given collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4054,32 +4059,22 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only returned if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: If-Match in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is returned if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: If-None-Match in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one ETag. The document is returned, - only if it has a different revision as the given ETag. Otherwise a HTTP 304 is returned. + If you provide an `If-None-Match` header, it must contain exactly one ETag. + The document is returned if it has a different revision as the given ETag. + Otherwise, an error with HTTP status code 304 is returned. schema: type: string - name: x-arango-trx-id @@ -4136,10 +4131,9 @@ paths: type: string '304': description: | - Returned if the `If-None-Match` header is given and the - currently stored vertex still has this revision value. - So there was no update between the last time the vertex - was fetched by the caller. + The `If-None-Match` header has been specified and the currently + stored vertex still has this revision value. There was no update since + the last time the vertex was fetched by the caller. content: application/json: schema: @@ -4274,7 +4268,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -4335,6 +4330,8 @@ paths: description: | Updates the data of the specific vertex in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4364,15 +4361,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only updated if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -4414,11 +4402,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -4724,7 +4710,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -4788,6 +4775,8 @@ paths: description: | Replaces the data of a vertex in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4817,15 +4806,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only replaced if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -4867,11 +4847,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. - The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + If you provide an `If-Match` header, it must contain exactly one ETag. + The document is replaced if it has the same revision as the given ETag. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -5177,7 +5155,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -5243,6 +5222,8 @@ paths: Removes a vertex from a collection of the named graph. Additionally removes all incoming and outgoing edges of the vertex. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -5272,15 +5253,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only deleted if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -5301,9 +5273,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If you provide an `If-Match` header, it must contain exactly one ETag. + The document is deleted if it has the same revision as the given ETag. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -5519,7 +5491,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -6002,6 +5975,8 @@ paths: description: | Gets an edge from the given collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6031,32 +6006,22 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only returned if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: If-Match in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is returned if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: If-None-Match in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one ETag. The document is returned, - only if it has a different revision as the given ETag. Otherwise a HTTP 304 is returned. + If you provide an `If-None-Match` header, it must contain exactly one ETag. + The document is returned if it has a different revision as the given ETag. + Otherwise, an error with HTTP status code 304 is returned. schema: type: string - name: x-arango-trx-id @@ -6123,10 +6088,9 @@ paths: type: string '304': description: | - Returned if the `If-None-Match` header is given and the - currently stored edge still has this revision value. - So there was no update between the last time the edge - was fetched by the caller. + The `If-None-Match` header has been specified and the currently + stored edge still has this revision value. There was no update since + the last time the edge was fetched by the caller. content: application/json: schema: @@ -6261,7 +6225,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -6323,6 +6288,8 @@ paths: description: | Partially modify the data of the specific edge in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6352,15 +6319,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only updated if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -6400,11 +6358,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -6771,7 +6727,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -6835,6 +6792,8 @@ paths: description: | Replaces the data of an edge in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6864,15 +6823,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only replaced if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -6912,11 +6862,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is replaced if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -7297,7 +7245,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -7365,6 +7314,8 @@ paths: Removes an edge from an edge collection of the named graph. Any other edges that directly reference this edge like a vertex are removed, too. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -7394,15 +7345,6 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only deleted if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -7422,11 +7364,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is deleted if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -7662,7 +7602,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: diff --git a/site/content/3.12/develop/http-api/graphs/named-graphs.md b/site/content/3.12/develop/http-api/graphs/named-graphs.md index 77aed9bc53..52ba90ad4f 100644 --- a/site/content/3.12/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.12/develop/http-api/graphs/named-graphs.md @@ -4022,6 +4022,8 @@ paths: description: | Gets a vertex from the given collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4051,32 +4053,22 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only returned if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: If-Match in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is returned if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: If-None-Match in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one ETag. The document is returned, - only if it has a different revision as the given ETag. Otherwise a HTTP 304 is returned. + If you provide an `If-None-Match` header, it must contain exactly one ETag. + The document is returned if it has a different revision as the given ETag. + Otherwise, an error with HTTP status code 304 is returned. schema: type: string - name: x-arango-trx-id @@ -4133,10 +4125,9 @@ paths: type: string '304': description: | - Returned if the `If-None-Match` header is given and the - currently stored vertex still has this revision value. - So there was no update between the last time the vertex - was fetched by the caller. + The `If-None-Match` header has been specified and the currently + stored vertex still has this revision value. There was no update since + the last time the vertex was fetched by the caller. content: application/json: schema: @@ -4271,7 +4262,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -4332,6 +4324,8 @@ paths: description: | Updates the data of the specific vertex in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4361,15 +4355,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only updated if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -4411,11 +4396,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -4721,7 +4704,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -4785,6 +4769,8 @@ paths: description: | Replaces the data of a vertex in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4814,15 +4800,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only replaced if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -4864,11 +4841,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. - The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + If you provide an `If-Match` header, it must contain exactly one ETag. + The document is replaced if it has the same revision as the given ETag. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -5174,7 +5149,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -5240,6 +5216,8 @@ paths: Removes a vertex from a collection of the named graph. Additionally removes all incoming and outgoing edges of the vertex. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -5269,15 +5247,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only deleted if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -5298,9 +5267,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If you provide an `If-Match` header, it must contain exactly one ETag. + The document is deleted if it has the same revision as the given ETag. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -5516,7 +5485,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -5999,6 +5969,8 @@ paths: description: | Gets an edge from the given collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6028,32 +6000,22 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only returned if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: If-Match in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is returned if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: If-None-Match in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one ETag. The document is returned, - only if it has a different revision as the given ETag. Otherwise a HTTP 304 is returned. + If you provide an `If-None-Match` header, it must contain exactly one ETag. + The document is returned if it has a different revision as the given ETag. + Otherwise, an error with HTTP status code 304 is returned. schema: type: string - name: x-arango-trx-id @@ -6120,10 +6082,9 @@ paths: type: string '304': description: | - Returned if the `If-None-Match` header is given and the - currently stored edge still has this revision value. - So there was no update between the last time the edge - was fetched by the caller. + The `If-None-Match` header has been specified and the currently + stored edge still has this revision value. There was no update since + the last time the edge was fetched by the caller. content: application/json: schema: @@ -6258,7 +6219,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -6320,6 +6282,8 @@ paths: description: | Partially modify the data of the specific edge in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6349,15 +6313,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only updated if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -6397,11 +6352,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -6768,7 +6721,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -6832,6 +6786,8 @@ paths: description: | Replaces the data of an edge in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6861,15 +6817,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only replaced if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -6909,11 +6856,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is replaced if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -7294,7 +7239,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -7362,6 +7308,8 @@ paths: Removes an edge from an edge collection of the named graph. Any other edges that directly reference this edge like a vertex are removed, too. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -7391,15 +7339,6 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only deleted if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -7419,11 +7358,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is deleted if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -7659,7 +7596,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: diff --git a/site/content/3.13/develop/http-api/graphs/named-graphs.md b/site/content/3.13/develop/http-api/graphs/named-graphs.md index 77aed9bc53..52ba90ad4f 100644 --- a/site/content/3.13/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.13/develop/http-api/graphs/named-graphs.md @@ -4022,6 +4022,8 @@ paths: description: | Gets a vertex from the given collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4051,32 +4053,22 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only returned if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: If-Match in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is returned if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: If-None-Match in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one ETag. The document is returned, - only if it has a different revision as the given ETag. Otherwise a HTTP 304 is returned. + If you provide an `If-None-Match` header, it must contain exactly one ETag. + The document is returned if it has a different revision as the given ETag. + Otherwise, an error with HTTP status code 304 is returned. schema: type: string - name: x-arango-trx-id @@ -4133,10 +4125,9 @@ paths: type: string '304': description: | - Returned if the `If-None-Match` header is given and the - currently stored vertex still has this revision value. - So there was no update between the last time the vertex - was fetched by the caller. + The `If-None-Match` header has been specified and the currently + stored vertex still has this revision value. There was no update since + the last time the vertex was fetched by the caller. content: application/json: schema: @@ -4271,7 +4262,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -4332,6 +4324,8 @@ paths: description: | Updates the data of the specific vertex in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4361,15 +4355,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only updated if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -4411,11 +4396,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -4721,7 +4704,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -4785,6 +4769,8 @@ paths: description: | Replaces the data of a vertex in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -4814,15 +4800,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only replaced if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -4864,11 +4841,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. - The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + If you provide an `If-Match` header, it must contain exactly one ETag. + The document is replaced if it has the same revision as the given ETag. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -5174,7 +5149,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -5240,6 +5216,8 @@ paths: Removes a vertex from a collection of the named graph. Additionally removes all incoming and outgoing edges of the vertex. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -5269,15 +5247,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only deleted if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -5298,9 +5267,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. The document is updated, - if it has the same revision as the given ETag. Otherwise a HTTP 412 is returned. As an alternative - you can supply the ETag in an attribute rev in the URL. + If you provide an `If-Match` header, it must contain exactly one ETag. + The document is deleted if it has the same revision as the given ETag. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -5516,7 +5485,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -5999,6 +5969,8 @@ paths: description: | Gets an edge from the given collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6028,32 +6000,22 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only returned if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: If-Match in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is returned if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: If-None-Match in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one ETag. The document is returned, - only if it has a different revision as the given ETag. Otherwise a HTTP 304 is returned. + If you provide an `If-None-Match` header, it must contain exactly one ETag. + The document is returned if it has a different revision as the given ETag. + Otherwise, an error with HTTP status code 304 is returned. schema: type: string - name: x-arango-trx-id @@ -6120,10 +6082,9 @@ paths: type: string '304': description: | - Returned if the `If-None-Match` header is given and the - currently stored edge still has this revision value. - So there was no update between the last time the edge - was fetched by the caller. + The `If-None-Match` header has been specified and the currently + stored edge still has this revision value. There was no update since + the last time the edge was fetched by the caller. content: application/json: schema: @@ -6258,7 +6219,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -6320,6 +6282,8 @@ paths: description: | Partially modify the data of the specific edge in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6349,15 +6313,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only updated if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -6397,11 +6352,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is updated if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -6768,7 +6721,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -6832,6 +6786,8 @@ paths: description: | Replaces the data of an edge in the collection. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -6861,15 +6817,6 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only replaced if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -6909,11 +6856,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is replaced if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -7294,7 +7239,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: @@ -7362,6 +7308,8 @@ paths: Removes an edge from an edge collection of the named graph. Any other edges that directly reference this edge like a vertex are removed, too. parameters: + # Purposefully undocumented: + # rev (use If-Match header) - name: database-name in: path required: true @@ -7391,15 +7339,6 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - in: query - required: false - description: | - If set, the document is only deleted if it has exactly this revision. - - As an alternative, you can use the `If-Match` header to specify the revision. - schema: - type: string - name: waitForSync in: query required: false @@ -7419,11 +7358,9 @@ paths: in: header required: false description: | - If the `If-Match` header is given, then it must contain exactly one ETag. + If you provide an `If-Match` header, it must contain exactly one ETag. The document is deleted if it has the same revision as the given ETag. - Otherwise, an error with an HTTP status code of 412 is returned. - - As an alternative, you can supply the ETag in the `rev` query parameter. + Otherwise, an error with HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -7659,7 +7596,8 @@ paths: type: string '412': description: | - Returned if the `If-Match` header is given, but the stored documents revision is different. + The `If-Match` header has been specified but the stored document's + revision is different. content: application/json: schema: From 8269355693814f59f160d7d888964fb49f7e3933 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 26 Jun 2025 00:25:48 +0200 Subject: [PATCH 04/13] Rewording, missing defaults --- .../3.11/develop/http-api/databases.md | 21 +++++++++----- .../develop/http-api/queries/aql-queries.md | 5 +++- .../queries/aql-query-results-cache.md | 15 ++++++++++ .../queries/user-defined-aql-functions.md | 29 +++++++++++-------- site/content/3.11/develop/http-api/users.md | 1 + .../3.12/develop/http-api/databases.md | 21 +++++++++----- .../develop/http-api/queries/aql-queries.md | 5 +++- .../queries/aql-query-results-cache.md | 15 ++++++++++ .../queries/user-defined-aql-functions.md | 29 +++++++++++-------- site/content/3.12/develop/http-api/users.md | 1 + .../3.13/develop/http-api/databases.md | 21 +++++++++----- .../develop/http-api/queries/aql-queries.md | 5 +++- .../queries/aql-query-results-cache.md | 15 ++++++++++ .../queries/user-defined-aql-functions.md | 29 +++++++++++-------- site/content/3.13/develop/http-api/users.md | 1 + 15 files changed, 150 insertions(+), 63 deletions(-) diff --git a/site/content/3.11/develop/http-api/databases.md b/site/content/3.11/develop/http-api/databases.md index bfece540b9..6a7b2ecb20 100644 --- a/site/content/3.11/develop/http-api/databases.md +++ b/site/content/3.11/develop/http-api/databases.md @@ -232,7 +232,7 @@ paths: Has to contain a valid database name. The name must conform to the selected naming convention for databases. If the name contains Unicode characters, the name must be [NFC-normalized](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms). - Non-normalized names will be rejected by arangod. + Non-normalized names are rejected. type: string options: description: | @@ -253,9 +253,14 @@ paths: replicationFactor: description: | Default replication factor for new collections created in this database. - Special values include "satellite", which will replicate the collection to - every DB-Server (Enterprise Edition only), and 1, which disables replication. _(cluster only)_ + + Special values: + - `"satellite"`: Replicate the collection to every DB-Server (Enterprise Edition only) + - `1`: Disable replication + + You can configure the global default with the + `--cluster.default-replication-factor` startup option. type: integer writeConcern: description: | @@ -275,10 +280,10 @@ paths: type: number users: description: | - An array of user objects. The users will be granted *Administrate* permissions - for the new database. Users that do not exist yet will be created. + An array of user objects. The users is granted *Administrate* permissions + for the new database. Users that do not exist yet are created. If `users` is not specified or does not contain any users, the default user - `root` will be used to ensure that the new database will be accessible after it + `root` is used to ensure that the new database is accessible after it is created. The `root` user is created with an empty password should it not exist. Each user object can contain the following attributes: type: array @@ -293,7 +298,7 @@ paths: type: string passwd: description: | - The user password as a string. If not specified, it will default to an empty + The user password as a string. If not specified, it defaults to an empty string. The attribute is ignored for users that already exist. type: string active: @@ -307,7 +312,7 @@ paths: description: | A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. Should not be set or - modified by end users, as custom attributes will not be preserved. + modified by end users, as custom attributes are not preserved. type: object responses: '201': diff --git a/site/content/3.11/develop/http-api/queries/aql-queries.md b/site/content/3.11/develop/http-api/queries/aql-queries.md index b16bfe21ce..3a3b93e880 100644 --- a/site/content/3.11/develop/http-api/queries/aql-queries.md +++ b/site/content/3.11/develop/http-api/queries/aql-queries.md @@ -320,7 +320,7 @@ paths: # forceOneShardAttributeValue query: description: | - contains the query string to be executed + The AQL query string to execute. type: string count: description: | @@ -2724,6 +2724,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2795,6 +2796,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2838,6 +2840,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.11/develop/http-api/queries/aql-query-results-cache.md b/site/content/3.11/develop/http-api/queries/aql-query-results-cache.md index 670705ddbe..876e1bc835 100644 --- a/site/content/3.11/develop/http-api/queries/aql-query-results-cache.md +++ b/site/content/3.11/develop/http-api/queries/aql-query-results-cache.md @@ -225,6 +225,9 @@ paths: mode: description: | The mode the AQL query results cache operates in. + + You can configure the default value with the + `--query.cache-mode` startup option. type: string # Unquoted on and off are booleans in YAML 1.1! enum: ["off", "on", "demand"] @@ -232,20 +235,32 @@ paths: description: | The maximum number of query results that are stored per database-specific cache. + + You can configure the default value with the + `--query.cache-entries` startup option. type: integer maxResultsSize: description: | The maximum cumulated size of query results that are stored per database-specific cache (in bytes). + + You can configure the default value with the + `--query.cache-entries-max-size` startup option. type: integer maxEntrySize: description: | The maximum individual result size of queries that are stored per database-specific cache (in bytes). + + You can configure the default value with the + `--query.cache-entry-max-size` startup option. includeSystem: description: | Whether results of queries that involve system collections are stored in the query results cache. + + You can configure the default value with the + `--query.cache-include-system-collections` startup option. type: boolean '400': description: | diff --git a/site/content/3.11/develop/http-api/queries/user-defined-aql-functions.md b/site/content/3.11/develop/http-api/queries/user-defined-aql-functions.md index 44800a409b..cf497ebdf8 100644 --- a/site/content/3.11/develop/http-api/queries/user-defined-aql-functions.md +++ b/site/content/3.11/develop/http-api/queries/user-defined-aql-functions.md @@ -49,20 +49,23 @@ paths: properties: name: description: | - the fully qualified name of the user functions. + The fully qualified name of the user functions. type: string code: description: | - a string representation of the function body. + A string representation of the JavaScript function definition. type: string isDeterministic: description: | - an optional boolean value to indicate whether 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 optimizations. + Whether the function results are fully deterministic, i.e. + the function return value solely depends on the input value + and the return value is the same for repeated calls with same + input. + + This attribute is currently not used but may be used for + optimizations in the future. type: boolean + default: false responses: '200': description: | @@ -402,11 +405,13 @@ paths: type: string isDeterministic: description: | - an optional boolean value to indicate whether 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 optimizations. + Whether the function results are fully deterministic, i.e. + the function return value solely depends on the input value + and the return value is the same for repeated calls with same + input. + + This attribute is currently not used but may be used for + optimizations in the future. type: boolean '400': description: | diff --git a/site/content/3.11/develop/http-api/users.md b/site/content/3.11/develop/http-api/users.md index 37b6407ad3..38cd9d12e2 100644 --- a/site/content/3.11/develop/http-api/users.md +++ b/site/content/3.11/develop/http-api/users.md @@ -894,6 +894,7 @@ paths: Return the full set of access levels for all databases and all collections. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/databases.md b/site/content/3.12/develop/http-api/databases.md index 2a1386e6db..d3e1e2e807 100644 --- a/site/content/3.12/develop/http-api/databases.md +++ b/site/content/3.12/develop/http-api/databases.md @@ -232,7 +232,7 @@ paths: Has to contain a valid database name. The name must conform to the selected naming convention for databases. If the name contains Unicode characters, the name must be [NFC-normalized](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms). - Non-normalized names will be rejected by arangod. + Non-normalized names are rejected. type: string options: description: | @@ -253,9 +253,14 @@ paths: replicationFactor: description: | Default replication factor for new collections created in this database. - Special values include "satellite", which will replicate the collection to - every DB-Server, and 1, which disables replication. _(cluster only)_ + + Special values: + - `"satellite"`: Replicate the collection to every DB-Server + - `1`: Disable replication + + You can configure the global default with the + `--cluster.default-replication-factor` startup option. type: integer writeConcern: description: | @@ -273,10 +278,10 @@ paths: type: number users: description: | - An array of user objects. The users will be granted *Administrate* permissions - for the new database. Users that do not exist yet will be created. + An array of user objects. The users is granted *Administrate* permissions + for the new database. Users that do not exist yet are created. If `users` is not specified or does not contain any users, the default user - `root` will be used to ensure that the new database will be accessible after it + `root` is used to ensure that the new database is accessible after it is created. The `root` user is created with an empty password should it not exist. Each user object can contain the following attributes: type: array @@ -291,7 +296,7 @@ paths: type: string passwd: description: | - The user password as a string. If not specified, it will default to an empty + The user password as a string. If not specified, it defaults to an empty string. The attribute is ignored for users that already exist. type: string active: @@ -305,7 +310,7 @@ paths: description: | A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. Should not be set or - modified by end users, as custom attributes will not be preserved. + modified by end users, as custom attributes are not preserved. type: object responses: '201': diff --git a/site/content/3.12/develop/http-api/queries/aql-queries.md b/site/content/3.12/develop/http-api/queries/aql-queries.md index 200433633f..02a81cc341 100644 --- a/site/content/3.12/develop/http-api/queries/aql-queries.md +++ b/site/content/3.12/develop/http-api/queries/aql-queries.md @@ -320,7 +320,7 @@ paths: # forceOneShardAttributeValue query: description: | - contains the query string to be executed + The AQL query string to execute. type: string count: description: | @@ -2799,6 +2799,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2870,6 +2871,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2913,6 +2915,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md b/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md index 77325280a4..fd3fa6932c 100644 --- a/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md +++ b/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md @@ -225,6 +225,9 @@ paths: mode: description: | The mode the AQL query results cache operates in. + + You can configure the default value with the + `--query.cache-mode` startup option. type: string # Unquoted on and off are booleans in YAML 1.1! enum: ["off", "on", "demand"] @@ -232,20 +235,32 @@ paths: description: | The maximum number of query results that are stored per database-specific cache. + + You can configure the default value with the + `--query.cache-entries` startup option. type: integer maxResultsSize: description: | The maximum cumulated size of query results that are stored per database-specific cache (in bytes). + + You can configure the default value with the + `--query.cache-entries-max-size` startup option. type: integer maxEntrySize: description: | The maximum individual result size of queries that are stored per database-specific cache (in bytes). + + You can configure the default value with the + `--query.cache-entry-max-size` startup option. includeSystem: description: | Whether results of queries that involve system collections are stored in the query results cache. + + You can configure the default value with the + `--query.cache-include-system-collections` startup option. type: boolean '400': description: | diff --git a/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md b/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md index 44800a409b..cf497ebdf8 100644 --- a/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md +++ b/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md @@ -49,20 +49,23 @@ paths: properties: name: description: | - the fully qualified name of the user functions. + The fully qualified name of the user functions. type: string code: description: | - a string representation of the function body. + A string representation of the JavaScript function definition. type: string isDeterministic: description: | - an optional boolean value to indicate whether 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 optimizations. + Whether the function results are fully deterministic, i.e. + the function return value solely depends on the input value + and the return value is the same for repeated calls with same + input. + + This attribute is currently not used but may be used for + optimizations in the future. type: boolean + default: false responses: '200': description: | @@ -402,11 +405,13 @@ paths: type: string isDeterministic: description: | - an optional boolean value to indicate whether 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 optimizations. + Whether the function results are fully deterministic, i.e. + the function return value solely depends on the input value + and the return value is the same for repeated calls with same + input. + + This attribute is currently not used but may be used for + optimizations in the future. type: boolean '400': description: | diff --git a/site/content/3.12/develop/http-api/users.md b/site/content/3.12/develop/http-api/users.md index 37b6407ad3..38cd9d12e2 100644 --- a/site/content/3.12/develop/http-api/users.md +++ b/site/content/3.12/develop/http-api/users.md @@ -894,6 +894,7 @@ paths: Return the full set of access levels for all databases and all collections. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/databases.md b/site/content/3.13/develop/http-api/databases.md index 2a1386e6db..d3e1e2e807 100644 --- a/site/content/3.13/develop/http-api/databases.md +++ b/site/content/3.13/develop/http-api/databases.md @@ -232,7 +232,7 @@ paths: Has to contain a valid database name. The name must conform to the selected naming convention for databases. If the name contains Unicode characters, the name must be [NFC-normalized](https://en.wikipedia.org/wiki/Unicode_equivalence#Normal_forms). - Non-normalized names will be rejected by arangod. + Non-normalized names are rejected. type: string options: description: | @@ -253,9 +253,14 @@ paths: replicationFactor: description: | Default replication factor for new collections created in this database. - Special values include "satellite", which will replicate the collection to - every DB-Server, and 1, which disables replication. _(cluster only)_ + + Special values: + - `"satellite"`: Replicate the collection to every DB-Server + - `1`: Disable replication + + You can configure the global default with the + `--cluster.default-replication-factor` startup option. type: integer writeConcern: description: | @@ -273,10 +278,10 @@ paths: type: number users: description: | - An array of user objects. The users will be granted *Administrate* permissions - for the new database. Users that do not exist yet will be created. + An array of user objects. The users is granted *Administrate* permissions + for the new database. Users that do not exist yet are created. If `users` is not specified or does not contain any users, the default user - `root` will be used to ensure that the new database will be accessible after it + `root` is used to ensure that the new database is accessible after it is created. The `root` user is created with an empty password should it not exist. Each user object can contain the following attributes: type: array @@ -291,7 +296,7 @@ paths: type: string passwd: description: | - The user password as a string. If not specified, it will default to an empty + The user password as a string. If not specified, it defaults to an empty string. The attribute is ignored for users that already exist. type: string active: @@ -305,7 +310,7 @@ paths: description: | A JSON object with extra user information. It is used by the web interface to store graph viewer settings and saved queries. Should not be set or - modified by end users, as custom attributes will not be preserved. + modified by end users, as custom attributes are not preserved. type: object responses: '201': diff --git a/site/content/3.13/develop/http-api/queries/aql-queries.md b/site/content/3.13/develop/http-api/queries/aql-queries.md index 200433633f..02a81cc341 100644 --- a/site/content/3.13/develop/http-api/queries/aql-queries.md +++ b/site/content/3.13/develop/http-api/queries/aql-queries.md @@ -320,7 +320,7 @@ paths: # forceOneShardAttributeValue query: description: | - contains the query string to be executed + The AQL query string to execute. type: string count: description: | @@ -2799,6 +2799,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2870,6 +2871,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2913,6 +2915,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md b/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md index 77325280a4..fd3fa6932c 100644 --- a/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md +++ b/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md @@ -225,6 +225,9 @@ paths: mode: description: | The mode the AQL query results cache operates in. + + You can configure the default value with the + `--query.cache-mode` startup option. type: string # Unquoted on and off are booleans in YAML 1.1! enum: ["off", "on", "demand"] @@ -232,20 +235,32 @@ paths: description: | The maximum number of query results that are stored per database-specific cache. + + You can configure the default value with the + `--query.cache-entries` startup option. type: integer maxResultsSize: description: | The maximum cumulated size of query results that are stored per database-specific cache (in bytes). + + You can configure the default value with the + `--query.cache-entries-max-size` startup option. type: integer maxEntrySize: description: | The maximum individual result size of queries that are stored per database-specific cache (in bytes). + + You can configure the default value with the + `--query.cache-entry-max-size` startup option. includeSystem: description: | Whether results of queries that involve system collections are stored in the query results cache. + + You can configure the default value with the + `--query.cache-include-system-collections` startup option. type: boolean '400': description: | diff --git a/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md b/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md index 44800a409b..cf497ebdf8 100644 --- a/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md +++ b/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md @@ -49,20 +49,23 @@ paths: properties: name: description: | - the fully qualified name of the user functions. + The fully qualified name of the user functions. type: string code: description: | - a string representation of the function body. + A string representation of the JavaScript function definition. type: string isDeterministic: description: | - an optional boolean value to indicate whether 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 optimizations. + Whether the function results are fully deterministic, i.e. + the function return value solely depends on the input value + and the return value is the same for repeated calls with same + input. + + This attribute is currently not used but may be used for + optimizations in the future. type: boolean + default: false responses: '200': description: | @@ -402,11 +405,13 @@ paths: type: string isDeterministic: description: | - an optional boolean value to indicate whether 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 optimizations. + Whether the function results are fully deterministic, i.e. + the function return value solely depends on the input value + and the return value is the same for repeated calls with same + input. + + This attribute is currently not used but may be used for + optimizations in the future. type: boolean '400': description: | diff --git a/site/content/3.13/develop/http-api/users.md b/site/content/3.13/develop/http-api/users.md index 37b6407ad3..38cd9d12e2 100644 --- a/site/content/3.13/develop/http-api/users.md +++ b/site/content/3.13/develop/http-api/users.md @@ -894,6 +894,7 @@ paths: Return the full set of access levels for all databases and all collections. schema: type: boolean + default: false responses: '200': description: | From 6209ca50643ade35e3be6ad4225d6addb4c9ba2a Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 26 Jun 2025 00:26:44 +0200 Subject: [PATCH 05/13] Index API: Backport changes to 3.11 --- .../3.11/develop/http-api/indexes/_index.md | 6 ++--- .../3.11/develop/http-api/indexes/fulltext.md | 21 ++++++++------- .../develop/http-api/indexes/geo-spatial.md | 19 ++++++++------ .../3.11/develop/http-api/indexes/inverted.md | 16 +++++++----- .../http-api/indexes/multi-dimensional.md | 26 +++++++++---------- .../develop/http-api/indexes/persistent.md | 25 +++++++++--------- .../3.11/develop/http-api/indexes/ttl.md | 24 ++++++++--------- 7 files changed, 71 insertions(+), 66 deletions(-) diff --git a/site/content/3.11/develop/http-api/indexes/_index.md b/site/content/3.11/develop/http-api/indexes/_index.md index f43b17fcb5..479dfd2604 100644 --- a/site/content/3.11/develop/http-api/indexes/_index.md +++ b/site/content/3.11/develop/http-api/indexes/_index.md @@ -247,9 +247,9 @@ paths: `cacheEnabled` defaults to `false` and should only be used for indexes that are known to benefit from an extra layer of caching. - The optional attribute **inBackground** can be set to `true` to create the index - in the background, which will not write-lock the underlying collection for - as long as if the index is built in the foreground. + The optional attribute **inBackground** can be set to `true` to keep the + collection/shards available for write operations by not using an exclusive + write lock for the duration of the index creation. parameters: - name: database-name in: path diff --git a/site/content/3.11/develop/http-api/indexes/fulltext.md b/site/content/3.11/develop/http-api/indexes/fulltext.md index a782084656..687ca29230 100644 --- a/site/content/3.11/develop/http-api/indexes/fulltext.md +++ b/site/content/3.11/develop/http-api/indexes/fulltext.md @@ -49,6 +49,7 @@ paths: description: | Must be equal to `"fulltext"`. type: string + example: fulltext name: description: | An easy-to-remember name for the index to look it up or refer to it in index hints. @@ -58,9 +59,10 @@ paths: type: string fields: description: | - an array of attribute names. Currently, the array is limited - to exactly one attribute. + A list with exactly one attribute path. type: array + minItems: 1 + maxItems: 1 items: type: string minLength: @@ -71,22 +73,21 @@ paths: type: integer inBackground: description: | - You can set this option to `true` to create the index - in the background, which will not write-lock the underlying collection for - as long as if the index is built in the foreground. The default value is `false`. + Set this option to `true` to keep the collection/shards available for + write operations by not using an exclusive write lock for the duration + of the index creation. type: boolean + default: false responses: '200': description: | - If the index already exists, then a *HTTP 200* is - returned. + The index exists already. '201': description: | - If the index does not already exist and could be created, then a *HTTP 201* - is returned. + The index is created as there is no such existing index. '404': description: | - If the `collection-name` is unknown, then a *HTTP 404* is returned. + The collection is unknown. tags: - Indexes ``` diff --git a/site/content/3.11/develop/http-api/indexes/geo-spatial.md b/site/content/3.11/develop/http-api/indexes/geo-spatial.md index a910a3a39f..ad51599a94 100644 --- a/site/content/3.11/develop/http-api/indexes/geo-spatial.md +++ b/site/content/3.11/develop/http-api/indexes/geo-spatial.md @@ -13,7 +13,7 @@ paths: operationId: createIndexGeo description: | Creates a geo-spatial index in the collection `collection`, if - it does not already exist. Expects an object containing the index details. + it does not already exist. Geo indexes are always sparse, meaning that documents that do not contain the index attributes or have non-numeric values in the index attributes @@ -47,6 +47,7 @@ paths: description: | Must be equal to `"geo"`. type: string + example: geo name: description: | An easy-to-remember name for the index to look it up or refer to it in index hints. @@ -72,6 +73,8 @@ paths: All documents which do not have the attribute paths or which have values that are not suitable are ignored. type: array + minItems: 1 + maxItems: 2 items: type: string geoJson: @@ -98,21 +101,21 @@ paths: type: boolean inBackground: description: | - You can set this option to `true` to create the index - in the background, which will not write-lock the underlying collection for - as long as if the index is built in the foreground. The default value is `false`. + Set this option to `true` to keep the collection/shards available for + write operations by not using an exclusive write lock for the duration + of the index creation. type: boolean + default: false responses: '200': description: | - If the index already exists, then a *HTTP 200* is returned. + The index exists already. '201': description: | - If the index does not already exist and could be created, then a *HTTP 201* - is returned. + The index is created as there is no such existing index. '404': description: | - If the `collection` is unknown, then a *HTTP 404* is returned. + The collection is unknown. tags: - Indexes ``` diff --git a/site/content/3.11/develop/http-api/indexes/inverted.md b/site/content/3.11/develop/http-api/indexes/inverted.md index aef743e806..8b6f74520f 100644 --- a/site/content/3.11/develop/http-api/indexes/inverted.md +++ b/site/content/3.11/develop/http-api/indexes/inverted.md @@ -44,6 +44,7 @@ paths: description: | Must be equal to `"inverted"`. type: string + example: inverted name: description: | An easy-to-remember name for the index to look it up or refer to it in index hints. @@ -57,6 +58,7 @@ paths: default options, or objects to specify options for the fields (with the attribute path in the `name` property), or a mix of both. type: array + minItems: 1 items: type: object required: @@ -461,10 +463,11 @@ paths: type: integer inBackground: description: | - This attribute can be set to `true` to create the index - in the background, not write-locking the underlying collection for - as long as if the index is built in the foreground. The default value is `false`. + Set this option to `true` to keep the collection/shards available for + write operations by not using an exclusive write lock for the duration + of the index creation. type: boolean + default: false cleanupIntervalStep: description: | Wait at least this many commits between removing unused files in the @@ -599,14 +602,13 @@ paths: responses: '200': description: | - If the index already exists, then a *HTTP 200* is returned. + The index exists already. '201': description: | - If the index does not already exist and can be created, then a *HTTP 201* - is returned. + The index is created as there is no such existing index. '404': description: | - If the `collection-name` is unknown, then a *HTTP 404* is returned. + The collection is unknown. tags: - Indexes ``` diff --git a/site/content/3.11/develop/http-api/indexes/multi-dimensional.md b/site/content/3.11/develop/http-api/indexes/multi-dimensional.md index 91677ef35a..c8418ff588 100644 --- a/site/content/3.11/develop/http-api/indexes/multi-dimensional.md +++ b/site/content/3.11/develop/http-api/indexes/multi-dimensional.md @@ -13,8 +13,7 @@ paths: operationId: createIndexZkd description: | Creates a multi-dimensional index for the collection `collection-name`, if - it does not already exist. The call expects an object containing the index - details. + it does not already exist. parameters: - name: database-name in: path @@ -45,6 +44,7 @@ paths: description: | Must be equal to `"zkd"`. type: string + example: zkd name: description: | An easy-to-remember name for the index to look it up or refer to it in index hints. @@ -56,6 +56,7 @@ paths: description: | An array of attribute names used for each dimension. Array expansions are not allowed. type: array + minItems: 1 items: type: string fieldValueTypes: @@ -69,25 +70,24 @@ paths: default: false inBackground: description: | - You can set this option to `true` to create the index - in the background, which will not write-lock the underlying collection for - as long as if the index is built in the foreground. The default value is `false`. + Set this option to `true` to keep the collection/shards available for + write operations by not using an exclusive write lock for the duration + of the index creation. type: boolean + default: false responses: '200': description: | - If the index already exists, then a *HTTP 200* is - returned. + The index exists already. '201': description: | - If the index does not already exist and could be created, then a *HTTP 201* - is returned. - '404': - description: | - If the `collection-name` is unknown, then a *HTTP 404* is returned. + The index is created as there is no such existing index. '400': description: | - If the index definition is invalid, then a *HTTP 400* is returned. + The index definition is invalid. + '404': + description: | + The collection is unknown. tags: - Indexes ``` diff --git a/site/content/3.11/develop/http-api/indexes/persistent.md b/site/content/3.11/develop/http-api/indexes/persistent.md index 02e8e49b41..8ff78bebe9 100644 --- a/site/content/3.11/develop/http-api/indexes/persistent.md +++ b/site/content/3.11/develop/http-api/indexes/persistent.md @@ -19,8 +19,7 @@ paths: operationId: createIndexPersistent description: | Creates a persistent index for the collection `collection-name`, if - it does not already exist. The call expects an object containing the index - details. + it does not already exist. In a sparse index all documents will be excluded from the index that do not contain at least one of the specified index attributes (i.e. `fields`) or that @@ -64,6 +63,7 @@ paths: description: | Must be equal to `"persistent"`. type: string + example: persistent name: description: | An easy-to-remember name for the index to look it up or refer to it in index hints. @@ -81,6 +81,7 @@ paths: You can expand one array attribute with `[*]`. type: array + minItems: 1 items: type: string storedValues: @@ -158,27 +159,25 @@ paths: type: boolean inBackground: description: | - This attribute can be set to `true` to create the index - in the background, which will not write-lock the underlying collection for - as long as if the index is built in the foreground. The default value is `false`. + Set this option to `true` to keep the collection/shards available for + write operations by not using an exclusive write lock for the duration + of the index creation. type: boolean + default: false responses: '200': description: | - If the index already exists, then a *HTTP 200* is - returned. + The index exists already. '201': description: | - If the index does not already exist and could be created, then a *HTTP 201* - is returned. + The index is created as there is no such existing index. '400': description: | - If the collection already contains documents and you try to create a unique - persistent index in such a way that there are documents violating the - uniqueness, then a *HTTP 400* is returned. + You try to create a unique persistent index but there are already + documents in the collection that violate the uniqueness requirement. '404': description: | - If the `collection-name` is unknown, then a *HTTP 404* is returned. + The collection is unknown. tags: - Indexes ``` diff --git a/site/content/3.11/develop/http-api/indexes/ttl.md b/site/content/3.11/develop/http-api/indexes/ttl.md index 97c0642271..11fb88d96a 100644 --- a/site/content/3.11/develop/http-api/indexes/ttl.md +++ b/site/content/3.11/develop/http-api/indexes/ttl.md @@ -13,8 +13,7 @@ paths: operationId: createIndexTtl description: | Creates a time-to-live (TTL) index for the collection `collection-name` if it - does not already exist. The call expects an object containing the index - details. + does not already exist. parameters: - name: database-name in: path @@ -54,8 +53,10 @@ paths: type: string fields: description: | - an array with exactly one attribute path. + A list with exactly one attribute path. type: array + minItems: 1 + maxItems: 1 items: type: string expireAfter: @@ -67,25 +68,24 @@ paths: type: number inBackground: description: | - You can set this option to `true` to create the index - in the background, which will not write-lock the underlying collection for - as long as if the index is built in the foreground. The default value is `false`. + Set this option to `true` to keep the collection/shards available for + write operations by not using an exclusive write lock for the duration + of the index creation. type: boolean + default: false responses: '200': description: | - If the index already exists, then a *HTTP 200* is returned. + The index exists already. '201': description: | - If the index does not already exist and could be created, then a *HTTP 201* - is returned. + The index is created as there is no such existing index. '400': description: | - If the collection already contains another TTL index, then an *HTTP 400* is - returned, as there can be at most one TTL index per collection. + There is already a TTL index for the collection but there can only be one. '404': description: | - If the `collection-name` is unknown, then a *HTTP 404* is returned. + The collection is unknown. tags: - Indexes ``` From ba8466b50ae38a944fb8459412a999dccf609dd4 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Thu, 26 Jun 2025 00:38:01 +0200 Subject: [PATCH 06/13] Apply rewording to JS API docs --- .../develop/javascript-api/@arangodb/db-object.md | 11 +++++------ .../develop/javascript-api/@arangodb/db-object.md | 8 ++++---- .../develop/javascript-api/@arangodb/db-object.md | 8 ++++---- 3 files changed, 13 insertions(+), 14 deletions(-) diff --git a/site/content/3.11/develop/javascript-api/@arangodb/db-object.md b/site/content/3.11/develop/javascript-api/@arangodb/db-object.md index fd60bc1776..cf80f7a977 100644 --- a/site/content/3.11/develop/javascript-api/@arangodb/db-object.md +++ b/site/content/3.11/develop/javascript-api/@arangodb/db-object.md @@ -42,12 +42,11 @@ The `options` attribute can be used to set defaults for collections that will be created in the new database (_cluster only_): - `sharding`: The sharding method to use. Valid values are: `""` or `"single"`. - Setting this option to `"single"` will enable the OneShard feature in the - Enterprise Edition. -- `replicationFactor`: Default replication factor. Special values include - `"satellite"`, which will replicate the collection to every DB-Server, and - `1`, which disables replication. -- `writeConcern`: how many copies of each shard are required to be in sync on + Setting this option to `"single"` enables the OneShard feature. +- `replicationFactor`: Default replication factor. Special values: + - `"satellite"`: Replicate the collection to every DB-Server (Enterprise Edition only) + - `1`: Disable replication +- `writeConcern`: How many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. The value of `writeConcern` cannot be greater than `replicationFactor`. diff --git a/site/content/3.12/develop/javascript-api/@arangodb/db-object.md b/site/content/3.12/develop/javascript-api/@arangodb/db-object.md index 2d4eee8cdf..5998dcd909 100644 --- a/site/content/3.12/develop/javascript-api/@arangodb/db-object.md +++ b/site/content/3.12/develop/javascript-api/@arangodb/db-object.md @@ -43,10 +43,10 @@ be created in the new database (_cluster only_): - `sharding`: The sharding method to use. Valid values are: `""` or `"single"`. Setting this option to `"single"` enables the OneShard feature. -- `replicationFactor`: Default replication factor. Special values include - `"satellite"`, which will replicate the collection to every DB-Server, and - `1`, which disables replication. -- `writeConcern`: how many copies of each shard are required to be in sync on +- `replicationFactor`: Default replication factor. Special values: + - `"satellite"`: Replicate the collection to every DB-Server + - `1`: Disable replication +- `writeConcern`: How many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. The value of `writeConcern` cannot be greater than `replicationFactor`. diff --git a/site/content/3.13/develop/javascript-api/@arangodb/db-object.md b/site/content/3.13/develop/javascript-api/@arangodb/db-object.md index e9e83ebad1..1538c034b7 100644 --- a/site/content/3.13/develop/javascript-api/@arangodb/db-object.md +++ b/site/content/3.13/develop/javascript-api/@arangodb/db-object.md @@ -45,10 +45,10 @@ be created in the new database (_cluster only_): - `sharding`: The sharding method to use. Valid values are: `""` or `"single"`. Setting this option to `"single"` enables the OneShard feature. -- `replicationFactor`: Default replication factor. Special values include - `"satellite"`, which will replicate the collection to every DB-Server, and - `1`, which disables replication. -- `writeConcern`: how many copies of each shard are required to be in sync on +- `replicationFactor`: Default replication factor. Special values: + - `"satellite"`: Replicate the collection to every DB-Server + - `1`: Disable replication +- `writeConcern`: How many copies of each shard are required to be in sync on the different DB-Servers. If there are less then these many copies in the cluster a shard will refuse to write. The value of `writeConcern` cannot be greater than `replicationFactor`. From 0994f5dd144442318d046caab98837995852634a Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 15 Jul 2025 09:45:11 +0200 Subject: [PATCH 07/13] Rework concept page about key generators, add padded and uuid --- .../concepts/data-structure/collections.md | 59 +++++++++++-------- 1 file changed, 36 insertions(+), 23 deletions(-) diff --git a/site/content/3.12/concepts/data-structure/collections.md b/site/content/3.12/concepts/data-structure/collections.md index 892903ab72..8f8323bbc9 100644 --- a/site/content/3.12/concepts/data-structure/collections.md +++ b/site/content/3.12/concepts/data-structure/collections.md @@ -119,29 +119,42 @@ ArangoDB as opaque strings when they store or use them locally. ## Key generators -ArangoDB allows using key generators for each collection. Key generators -have the purpose of auto-generating values for the `_key` attribute of a document -if none was specified by the user. By default, ArangoDB uses the traditional -key generator. The traditional key generator auto-generates key values that -are strings with ever-increasing numbers. The increment values it uses are -non-deterministic. - -Contrary, the auto-increment key generator auto-generates deterministic key -values. Both the start value and the increment value can be defined when the -collection is created. The default start value is `0` and the default increment -is `1`, meaning the key values it creates 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, ... - -The auto-increment values are increased and handed out on each document insert -attempt. Even if an insert fails, the auto-increment value is never rolled back. -That means there may exist gaps in the sequence of assigned auto-increment values -if inserts fails. +ArangoDB allows you to use different key generators for each collection. +Key generators have the purpose of auto-generating a value for the `_key` +attribute of a document if none was specified by the user. + +- **traditional** (default): The `traditional` key generator auto-generates + key values that are strings with ever-increasing numbers. The increment values + it uses are non-deterministic (e.g. `"137"`, `"140"`, `"141"`, `"145"`, ...). + +- **autoincrement**: The `autoincrement` key generator auto-generates + deterministic key values. You can define both the start value (`offset`) and + the `increment` value when creating the collection. The default start value is + `0` and the default increment is `1` (`"1"`, `"2"`, `"3"`, `"4"`, `"5"`, ...). + With an `increment` of `5` and `offset` of `2`: `"2"`, `"7"`, `"12"`, `"17"`, `"22"`, ... + + The auto-increment values are increased and handed out on each document insert + attempt. Even if an insert fails, the auto-increment value is never rolled back. + That means there may exist gaps in the sequence of assigned auto-increment values + if inserts fail. + + The `autoincrement` key generator is only supported for collections with a + single shard. + +- **padded**: The `padded` key generator generates keys of a fixed length + (16 bytes) in ascending lexicographical sort order. This is ideal for the + RocksDB storage engine, which slightly benefits keys that are inserted in + lexicographically ascending order. The sequence of generated keys is not + guaranteed to be gap-free (e.g. `"00000000005bb4d9"`, `"00000000005bb4e6"`, ...). + +- **uuid**: The `uuid` key generator generates universally unique 128 bit keys, + which are stored in hexadecimal human-readable format. The keys produced by + this key generator are not lexicographically sorted (e.g. + `"04648089-bdeb-4852-b570-f5280f68cf19"`, `"d0f1069c-e38b-4327-8e1e-6bdf7fd33865"`, ...). + +If you specify keys for some documents but rely on key generation for other +documents targeting the same collection, conflicts may occur. You can set +`allowUserKeys` to `false` to only permit auto-generated keys for a collection. ## Synchronous replication of collections From 5c2979c073ab3d6768664a5cc761017b3898b07c Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 15 Jul 2025 09:45:36 +0200 Subject: [PATCH 08/13] Users: passwd is not mandatory, PUT resets access levels --- site/content/3.12/develop/http-api/users.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/site/content/3.12/develop/http-api/users.md b/site/content/3.12/develop/http-api/users.md index 38cd9d12e2..1a03c6c984 100644 --- a/site/content/3.12/develop/http-api/users.md +++ b/site/content/3.12/develop/http-api/users.md @@ -55,7 +55,6 @@ paths: type: object required: - user - - passwd properties: user: description: | @@ -125,7 +124,8 @@ paths: put: operationId: replaceUserData description: | - Replaces the data of an existing user. You need server access level + Replaces the data of an existing user. This resets the user's + access levels for databases and collections. You need server access level *Administrate* in order to execute this REST call. Additionally, users can change their own data. parameters: @@ -151,8 +151,6 @@ paths: application/json: schema: type: object - required: - - passwd properties: passwd: description: | @@ -246,8 +244,6 @@ paths: application/json: schema: type: object - required: - - passwd properties: passwd: description: | From 4d826649e1d1c60d85d572ac2104cb97c356d9d4 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Tue, 15 Jul 2025 09:48:13 +0200 Subject: [PATCH 09/13] Fix shard IDs example and missing response description details parameter would require polymorphic response description (array or object) but we cannot render this at the moment --- .../3.12/develop/http-api/collections.md | 346 +++++++++++++++++- 1 file changed, 337 insertions(+), 9 deletions(-) diff --git a/site/content/3.12/develop/http-api/collections.md b/site/content/3.12/develop/http-api/collections.md index e3390aed1e..1c7bc996c7 100644 --- a/site/content/3.12/develop/http-api/collections.md +++ b/site/content/3.12/develop/http-api/collections.md @@ -1848,11 +1848,12 @@ paths: get: operationId: getCollectionShards description: | - Returns a JSON array with the shard IDs of the collection. - - If the `details` parameter is set to `true`, it returns a JSON object with the - shard IDs as object attribute keys, and the responsible servers for each shard mapped to them. - In the detailed response, the leader shards come first in the arrays. + The response contains a list of the collection's shard IDs. + + If the `details` parameter is set to `true`, it returns an object instead + of a list, with the shard IDs as object attribute keys, and an array with + the responsible servers for each shard mapped to them as attribute values. + The first element of each array is the leader shard. {{}} This method is only available in cluster deployments on Coordinators. @@ -1884,8 +1885,333 @@ paths: responses: '200': description: | - Returns the collection's shards. - # TODO: polymorphic structural description? + All collection properties but additionally the `shards` of the collection. + content: + application/json: + schema: + type: object + required: + - shards + - error + - code + - name + - type + - status + - statusString + - isSystem + - id + - globallyUniqueId + - waitForSync + - keyOptions + - schema + - computedValues + - cacheEnabled + - syncByRevision + # Purposefully undocumented: + # internalValidatorType (internal) + # isSmartChild (internal) + # minReplicationFactor (now writeConcern) + # shadowCollections (internal) + # usesRevisionsAsDocumentIds (internal) + # For backward compatibility: + # status (legacy) + # statusString (legacy) + properties: + shards: + description: | + The type and value depend on the setting of the `details` parameter: + - `false`: An array of the collection shard IDs. + - `true`: An object where the keys are shard IDs and the + values are arrays with the responsible DB-Server names + (shard leader first). + # TODO: polymorphic structural description? Complex to render + #type: [array, object] + #items: + # type: string + # pattern: "^s\\d+$" + #patternProperties: + # "^s\\d+$": + # type: array + # items: + # type: string + # --- or --- + #oneOf: + # - type: array + # items: + # type: string + # pattern: "^s\\d+$" + # - type: object + # patternProperties: + # "^s\\d+$": + # type: array + # items: + # type: string + status: + description: | + The status of the collection (deprecated). + - `3`: loaded + - `5`: deleted + + Every other status indicates a corrupted collection. + type: integer + example: 3 + statusString: + description: | + The status of the collection as a descriptive string (deprecated). + type: string + enum: [loaded, deleted] + example: loaded + error: + description: | + A flag indicating that no error occurred. + type: boolean + example: false + code: + description: | + The HTTP response status code. + type: integer + example: 200 + waitForSync: + description: | + If `true`, creating, changing, or removing + documents waits until the data has been synchronized to disk. + type: boolean + schema: + description: | + The configuration of the collection-level schema validation for documents. + type: object + required: + - rule + - level + - message + - type + properties: + rule: + description: | + A [JSON Schema](https://json-schema.org/specification-links#draft-4) + object (draft-4, without remote schemas). + + See [Document Schema Validation](../../concepts/data-structure/documents/schema-validation.md) + for details. + type: object + level: + description: | + The level controls when the validation is triggered: + - `"none"`: The rule is inactive and validation thus turned off. + - `"new"`: Only newly inserted documents are validated. + - `"moderate"`: New and modified documents must pass validation, + except for modified documents where the OLD value did not pass + validation already. This level is useful if you have documents + which do not match your target structure, but you want to stop + the insertion of more invalid documents and prohibit that valid + documents are changed to invalid documents. + - `"strict"`: All new and modified document must strictly pass + validation. No exceptions are made. + type: string + enum: [none, new, moderate, strict] + default: strict + message: + description: | + The error message to raise if the schema validation fails + for a document. + type: string + type: + description: | + The schema validation type. Only JSON Schema is supported. + type: string + enum: [json] + computedValues: + description: | + A list of objects, each representing a computed value. + type: array + items: + type: object + required: + - name + - expression + - overwrite + properties: + name: + description: | + The name of the target attribute. + type: string + expression: + description: | + An AQL `RETURN` operation with an expression that computes the desired value. + type: string + overwrite: + description: | + Whether the computed value takes precedence over a user-provided or + existing attribute. + type: boolean + computeOn: + description: | + An array of strings that defines on which write operations the value is + computed. + type: array + uniqueItems: true + items: + type: string + enum: [insert, update, replace] + example: ["insert", "update", "replace"] + keepNull: + description: | + Whether the target attribute is set if the expression evaluates to `null`. + type: boolean + failOnWarning: + description: | + Whether the write operation fails if the expression produces a warning. + type: boolean + keyOptions: + description: | + An object which contains key generation options. + type: object + required: + - type + - allowUserKeys + properties: + type: + description: | + Specifies the type of the key generator. + type: string + enum: [traditional, autoincrement, uuid, padded] + allowUserKeys: + description: | + If set to `true`, then you are allowed to supply + own key values in the `_key` attribute of a document. If set to + `false`, then the key generator is solely responsible for + generating keys and an error is raised if you supply own key values in the + `_key` attribute of documents. + + {{}} + You should not use both user-specified and automatically generated document keys + in the same collection in cluster deployments for collections with more than a + single shard. Mixing the two can lead to conflicts because Coordinators that + auto-generate keys in this case are not aware of all keys which are already used. + {{}} + type: boolean + increment: + description: | + The increment value for the `autoincrement` key generator. + Not used by other key generator types. + type: integer + offset: + description: | + The initial offset value for the `autoincrement` key generator. + Not used by other key generator types. + type: integer + lastValue: + description: | + The offset value of the `autoincrement` or `padded` key generator. + This is an internal property for restoring dumps properly. + type: integer + cacheEnabled: + description: | + Whether the in-memory hash cache for documents is enabled for this + collection. + type: boolean + numberOfShards: + description: | + The number of shards of the collection. _(cluster only)_ + type: integer + shardKeys: + description: | + Contains the names of document attributes that are used to + determine the target shard for documents. _(cluster only)_ + type: array + items: + type: string + replicationFactor: + description: | + Contains how many copies of each shard are kept on different DB-Servers. + It is an integer number in the range of 1-10 or the string `"satellite"` + for SatelliteCollections. _(cluster only)_ + type: integer + writeConcern: + description: | + Determines how many copies of each shard are required to be + in-sync on the different DB-Servers. If there are less than these many copies + in the cluster, a shard refuses to write. Writes to shards with enough + up-to-date copies succeed at the same time, however. The value of + `writeConcern` cannot be greater than `replicationFactor`. + + If `distributeShardsLike` is set, the default `writeConcern` + is that of the prototype collection. + For SatelliteCollections, the `writeConcern` is automatically controlled to + equal the number of DB-Servers and has a value of `0`. + Otherwise, the default value is controlled by the current database's + default `writeConcern`, which uses the `--cluster.write-concern` + startup option as default, which defaults to `1`. _(cluster only)_ + type: integer + shardingStrategy: + description: | + The sharding strategy selected for the collection. _(cluster only)_ + type: string + enum: + - community-compat + - enterprise-compat + - enterprise-smart-edge-compat + - hash + - enterprise-hash-smart-edge + - enterprise-hex-smart-vertex + distributeShardsLike: + description: | + The name of another collection. This collection uses the `replicationFactor`, + `numberOfShards` and `shardingStrategy` properties of the other collection and + the shards of this collection are distributed in the same way as the shards of + the other collection. + type: string + isSmart: + description: | + Whether the collection is used in a SmartGraph or EnterpriseGraph. + This is an internal property. _(cluster only)_ + type: boolean + isDisjoint: + description: | + Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint. + This is an internal property. _(cluster only)_ + type: boolean + smartGraphAttribute: + description: | + The attribute that is used for sharding: vertices with the same value of + this attribute are placed in the same shard. All vertices are required to + have this attribute set and it has to be a string. Edges derive the + attribute from their connected vertices. _(cluster only)_ + type: string + smartJoinAttribute: + description: | + Determines an attribute of the collection that must contain the shard key value + of the referred-to SmartJoin collection. _(cluster only)_ + type: string + name: + description: | + The name of this collection. + type: string + id: + description: | + A unique identifier of the collection (deprecated). + type: string + type: + description: | + The type of the collection: + - `0`: "unknown" + - `2`: regular document collection + - `3`: edge collection + type: integer + isSystem: + description: | + Whether the collection is a system collection. Collection names that starts with + an underscore are usually system collections. + type: boolean + syncByRevision: + description: | + Whether the newer revision-based replication protocol is + enabled for this collection. This is an internal property. + type: boolean + globallyUniqueId: + description: | + A unique identifier of the collection. This is an internal property. + type: string '400': description: | The `collection-name` parameter is missing. @@ -1999,7 +2325,8 @@ db._create(cn, { numberOfShards: 3 }); var response = logCurlRequest('GET', "/_api/collection/" + cn + "/shards"); assert(response.code === 200); -logRawResponse(response); +assert(response.parsedBody.hasOwnProperty("shards")); +logJsonResponse(response); db._drop(cn); ``` @@ -2017,7 +2344,8 @@ db._create(cn, { numberOfShards: 3 }); var response = logCurlRequest('GET', "/_api/collection/" + cn + "/shards?details=true"); assert(response.code === 200); -logRawResponse(response); +assert(response.parsedBody.hasOwnProperty("shards")); +logJsonResponse(response); db._drop(cn); ``` From 3486d75cf5cdcb7357ce957026a9d0a2519d56fe Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 4 Aug 2025 14:06:46 +0200 Subject: [PATCH 10/13] maxTransactionSize not available in 3.11 --- .../3.11/develop/http-api/transactions/stream-transactions.md | 4 ---- site/content/3.11/develop/transactions/stream-transactions.md | 1 - 2 files changed, 5 deletions(-) diff --git a/site/content/3.11/develop/http-api/transactions/stream-transactions.md b/site/content/3.11/develop/http-api/transactions/stream-transactions.md index 6f51d97aa6..5435be4bc2 100644 --- a/site/content/3.11/develop/http-api/transactions/stream-transactions.md +++ b/site/content/3.11/develop/http-api/transactions/stream-transactions.md @@ -132,10 +132,6 @@ paths: value will be used. Setting `lockTimeout` to `0` will make ArangoDB not time out waiting for a lock. type: integer - maxTransactionSize: - description: | - Transaction size limit in bytes. - type: integer responses: '201': description: | diff --git a/site/content/3.11/develop/transactions/stream-transactions.md b/site/content/3.11/develop/transactions/stream-transactions.md index 18135239be..6114541444 100644 --- a/site/content/3.11/develop/transactions/stream-transactions.md +++ b/site/content/3.11/develop/transactions/stream-transactions.md @@ -102,7 +102,6 @@ Additionally, `options` can have the following optional attributes: waiting on collection locks. This option is only meaningful when using `exclusive` locks. If not specified, a default value is used. Setting `lockTimeout` to `0` makes ArangoDB not time out waiting for a lock. -- `maxTransactionSize`: Transaction size limit in bytes. Can be at most 128 MiB. The method returns an object that lets you run supported operations as part of the transactions, get the status information, and commit or abort the transaction. From 74ccea8b1c9cddd4cdad53bbce7aacc9c3d51e0a Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 4 Aug 2025 14:07:30 +0200 Subject: [PATCH 11/13] CSS: Make the version selector gray instead of green --- site/themes/arangodb-docs-theme/static/css/theme.css | 1 + 1 file changed, 1 insertion(+) diff --git a/site/themes/arangodb-docs-theme/static/css/theme.css b/site/themes/arangodb-docs-theme/static/css/theme.css index f0de7f1ef0..902f254cbb 100644 --- a/site/themes/arangodb-docs-theme/static/css/theme.css +++ b/site/themes/arangodb-docs-theme/static/css/theme.css @@ -761,6 +761,7 @@ header .logo { .version-selector { border: none; margin-left: 1rem; + color: var(--gray-950); } @media screen and (max-width: 768px) { From 474dbbffe0dea9b9c1b8b28d9d72cc3d5e84a066 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 4 Aug 2025 14:07:50 +0200 Subject: [PATCH 12/13] Unify release notes --- .../release-notes/version-3.12/whats-new-in-3-12.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md b/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md index 98669fffb7..77b8c26bb2 100644 --- a/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md +++ b/site/content/3.13/release-notes/version-3.12/whats-new-in-3-12.md @@ -1688,6 +1688,18 @@ The following startup options for cluster deployments have been added: The delay (in seconds) before shutting down a Coordinator if no heartbeat can be sent. Set to `0` to deactivate this shutdown. +### Limit for shard synchronization actions + +Introduced in: v3.11.14, v3.12.5 + +The number of `SynchronizeShard` actions that can be scheduled internally by the +cluster maintenance has been restricted to prevent these actions from blocking +`TakeoverShardLeadership` actions with a higher priority, which could lead to +service interruption during upgrades and after failovers. + +The new `--server.maximal-number-sync-shard-actions` startup option controls +how many `SynchronizeShard` actions can be queued at any given time. + ## Miscellaneous changes ### V8 and ICU library upgrades From db40dd9f4cea9565dba960149552ff09875a2aa6 Mon Sep 17 00:00:00 2001 From: Simran Spiller Date: Mon, 4 Aug 2025 14:11:30 +0200 Subject: [PATCH 13/13] Finish up improvements to OpenAPI descriptions Missing defaults, add uniqueItems property for indexes, fix type/structure mistakes, reword some descriptions Certain endpoints like for transactions would require multiple types (string or array of strings), but we cannot render that yet --- .../3.12/develop/http-api/administration.md | 35 +- .../3.12/develop/http-api/analyzers.md | 4 +- .../3.12/develop/http-api/batch-requests.md | 14 +- site/content/3.12/develop/http-api/cluster.md | 51 ++- .../3.12/develop/http-api/collections.md | 34 +- .../3.12/develop/http-api/documents.md | 77 ++-- site/content/3.12/develop/http-api/foxx.md | 22 +- .../develop/http-api/graphs/named-graphs.md | 64 +-- .../3.12/develop/http-api/hot-backups.md | 19 +- .../3.12/develop/http-api/indexes/_index.md | 11 +- .../3.12/develop/http-api/indexes/fulltext.md | 7 +- .../develop/http-api/indexes/geo-spatial.md | 8 +- .../3.12/develop/http-api/indexes/inverted.md | 70 ++-- .../http-api/indexes/multi-dimensional.md | 3 + .../develop/http-api/indexes/persistent.md | 22 +- .../3.12/develop/http-api/indexes/vector.md | 3 +- site/content/3.12/develop/http-api/jobs.md | 1 + .../3.12/develop/http-api/monitoring/logs.md | 22 +- .../develop/http-api/queries/aql-queries.md | 102 +++-- .../queries/aql-query-results-cache.md | 26 +- .../queries/user-defined-aql-functions.md | 4 +- .../http-api/replication/replication-dump.md | 12 +- .../replication/replication-logger.md | 3 +- .../http-api/replication/write-ahead-log.md | 3 +- site/content/3.12/develop/http-api/tasks.md | 11 +- .../transactions/javascript-transactions.md | 49 ++- .../transactions/stream-transactions.md | 62 ++- site/content/3.12/develop/http-api/users.md | 6 +- .../http-api/views/arangosearch-views.md | 75 +++- .../http-api/views/search-alias-views.md | 12 + .../geo-spatial-indexes.md | 2 +- .../concepts/data-structure/collections.md | 59 +-- .../3.13/develop/http-api/administration.md | 35 +- .../3.13/develop/http-api/analyzers.md | 4 +- site/content/3.13/develop/http-api/cluster.md | 51 ++- .../3.13/develop/http-api/collections.md | 364 ++++++++++++++++-- .../3.13/develop/http-api/documents.md | 77 ++-- site/content/3.13/develop/http-api/foxx.md | 22 +- .../develop/http-api/graphs/named-graphs.md | 64 +-- .../3.13/develop/http-api/hot-backups.md | 19 +- .../3.13/develop/http-api/indexes/_index.md | 11 +- .../3.13/develop/http-api/indexes/fulltext.md | 7 +- .../develop/http-api/indexes/geo-spatial.md | 8 +- .../3.13/develop/http-api/indexes/inverted.md | 70 ++-- .../http-api/indexes/multi-dimensional.md | 3 + .../develop/http-api/indexes/persistent.md | 22 +- .../3.13/develop/http-api/indexes/vector.md | 3 +- site/content/3.13/develop/http-api/jobs.md | 1 + .../3.13/develop/http-api/monitoring/logs.md | 22 +- .../develop/http-api/queries/aql-queries.md | 241 ++++-------- .../queries/aql-query-results-cache.md | 26 +- .../queries/user-defined-aql-functions.md | 4 +- .../http-api/replication/replication-dump.md | 12 +- .../replication/replication-logger.md | 3 +- .../http-api/replication/write-ahead-log.md | 3 +- site/content/3.13/develop/http-api/tasks.md | 11 +- .../transactions/javascript-transactions.md | 49 ++- .../transactions/stream-transactions.md | 62 ++- site/content/3.13/develop/http-api/users.md | 14 +- .../http-api/views/arangosearch-views.md | 75 +++- .../http-api/views/search-alias-views.md | 12 + .../geo-spatial-indexes.md | 2 +- 62 files changed, 1405 insertions(+), 785 deletions(-) diff --git a/site/content/3.12/develop/http-api/administration.md b/site/content/3.12/develop/http-api/administration.md index 2b0d91c640..9627e59411 100644 --- a/site/content/3.12/develop/http-api/administration.md +++ b/site/content/3.12/develop/http-api/administration.md @@ -46,6 +46,7 @@ paths: the `details` object may vary depending on platform and ArangoDB version. schema: type: boolean + default: false responses: '200': description: | @@ -1308,6 +1309,7 @@ paths: - Ongoing low priority requests schema: type: boolean + default: false responses: '200': description: | @@ -1436,13 +1438,13 @@ paths: changeLevel: description: | whether or not compacted data should be moved to the minimum possible level. - The default value is `false`. type: boolean + default: false compactBottomMostLevel: description: | Whether or not to compact the bottommost level of data. - The default value is `false`. type: boolean + default: false responses: '200': description: | @@ -1509,16 +1511,10 @@ paths: The call returns an object with the servers request information requestBody: content: - application/json: + application/octet-stream: schema: - type: object - required: - - body - properties: - body: - description: | - The request body can be of any type and is simply forwarded. - type: string + description: | + The request body can be of any type and is simply forwarded. parameters: - name: database-name in: path @@ -1701,8 +1697,9 @@ paths: directly, otherwise a string produced by JSON.stringify will be returned. - Note that this API endpoint will only be present if the server was - started with the option `--javascript.allow-admin-execute true`. + Note that this API endpoint is available if the server has been + started with the `--javascript.allow-admin-execute` startup options + enabled. The default value of this option is `false`, which disables the execution of user-defined code and disables this API endpoint entirely. @@ -1718,16 +1715,10 @@ paths: type: string requestBody: content: - application/json: + text/javascript: schema: - type: object - required: - - body - properties: - body: - description: | - The request body is the JavaScript code to be executed. - type: string + description: | + The request body is the JavaScript code to be executed. responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/analyzers.md b/site/content/3.12/develop/http-api/analyzers.md index ea3491b249..feb941feda 100644 --- a/site/content/3.12/develop/http-api/analyzers.md +++ b/site/content/3.12/develop/http-api/analyzers.md @@ -54,8 +54,8 @@ paths: features: description: | The set of features to set on the Analyzer generated fields. - The default value is an empty array. type: array + default: [] uniqueItems: true items: type: string @@ -249,9 +249,9 @@ paths: required: false description: | The Analyzer configuration should be removed even if it is in-use. - The default value is `false`. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/batch-requests.md b/site/content/3.12/develop/http-api/batch-requests.md index 689c05b440..7a7b303bee 100644 --- a/site/content/3.12/develop/http-api/batch-requests.md +++ b/site/content/3.12/develop/http-api/batch-requests.md @@ -283,17 +283,11 @@ paths: type: string requestBody: content: - application/json: + 'text/plain; charset=utf-8': schema: - type: object - required: - - body - properties: - body: - description: | - The multipart batch request, consisting of the envelope and the individual - batch parts. - type: string + description: | + The multipart batch request, consisting of the envelope and the individual + batch parts. responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/cluster.md b/site/content/3.12/develop/http-api/cluster.md index 9089779739..d40ac42208 100644 --- a/site/content/3.12/develop/http-api/cluster.md +++ b/site/content/3.12/develop/http-api/cluster.md @@ -380,6 +380,7 @@ paths: You can send another request when the DB-Server is already in maintenance mode to extend the timeout. type: integer + default: 3600 responses: '200': description: | @@ -808,37 +809,44 @@ paths: type: number maximumNumberOfMoves: description: | - Maximum number of moves to be computed. (Default: `1000`) - type: number + Maximum number of moves to be computed. + type: integer + default: 1000 leaderChanges: description: | - Allow leader changes without moving data. (Default: `true`) + Allow leader changes without moving data. type: boolean + default: true moveLeaders: description: | - Allow moving leaders. (Default: `false`) + Allow moving leaders. type: boolean + default: false moveFollowers: description: | - Allow moving followers. (Default: `false`) + Allow moving followers. type: boolean + default: false excludeSystemCollections: description: | - Ignore system collections in the rebalance plan. (Default: `false`) + Ignore system collections in the rebalance plan. type: boolean + default: false piFactor: description: | - A weighting factor that should remain untouched. (Default: `256e6`) + A weighting factor that should remain untouched. If a collection has more shards than there are DB-Servers, there can be a subtle form of leader imbalance. Some DB-Servers may be responsible for more shards as leader than others. The `piFactor` adjusts how much weight such imbalances get in the overall imbalance score. - type: number + type: integer + default: 256e6 databasesExcluded: description: | - A list of database names to exclude from the analysis. (Default: `[]`) + A list of database names to exclude from the analysis. type: array + default: [] items: type: string responses: @@ -1218,37 +1226,44 @@ paths: type: number maximumNumberOfMoves: description: | - Maximum number of moves to be computed. (Default: `1000`) - type: number + Maximum number of moves to be computed. + type: integer + default: 1000 leaderChanges: description: | - Allow leader changes without moving data. (Default: `true`) + Allow leader changes without moving data. type: boolean + default: true moveLeaders: description: | - Allow moving leaders. (Default: `false`) + Allow moving leaders. type: boolean + default: false moveFollowers: description: | - Allow moving followers. (Default: `false`) + Allow moving followers. type: boolean + default: false excludeSystemCollections: description: | - Ignore system collections in the rebalance plan. (Default: `false`) + Ignore system collections in the rebalance plan. type: boolean + default: false piFactor: description: | - A weighting factor that should remain untouched. (Default: `256e6`) + A weighting factor that should remain untouched. If a collection has more shards than there are DB-Servers, there can be a subtle form of leader imbalance. Some DB-Servers may be responsible for more shards as leader than others. The `piFactor` adjusts how much weight such imbalances get in the overall imbalance score. - type: number + type: integer + default: 256e6 databasesExcluded: description: | - A list of database names to exclude from the analysis. (Default: `[]`) + A list of database names to exclude from the analysis. type: array + default: [] items: type: string responses: diff --git a/site/content/3.12/develop/http-api/collections.md b/site/content/3.12/develop/http-api/collections.md index 1c7bc996c7..a3f8185cdd 100644 --- a/site/content/3.12/develop/http-api/collections.md +++ b/site/content/3.12/develop/http-api/collections.md @@ -51,6 +51,7 @@ paths: Whether system collections should be excluded from the result. schema: type: boolean + default: false responses: '200': description: | @@ -1684,15 +1685,10 @@ paths: content: application/json: schema: + description: | + The request body must be a JSON object with at least the shard key + attributes set to some values, but it may also be a full document. type: object - required: - - document - properties: - document: - description: | - The request body must be a JSON object with at least the shard key - attributes set to some values, but it may also be a full document. - type: object responses: '200': description: | @@ -2384,7 +2380,7 @@ paths: responses: '200': description: | - All collection properties but additionally the collection `revision`. + All collection properties but additionally the `revision` of the collection. content: application/json: schema: @@ -2828,16 +2824,18 @@ paths: in: query required: false description: | - Whether or not to include document revision ids in the checksum calculation. + Whether to include document revision ids in the checksum calculation. schema: type: boolean + default: false - name: withData in: query required: false description: | - Whether or not to include document body data in the checksum calculation. + Whether to include document body data in the checksum calculation. schema: type: boolean + default: false responses: '200': description: | @@ -3192,7 +3190,7 @@ paths: - The `autoincrement` key generator generates numerical keys in ascending order, the initial offset and the spacing can be configured (**note**: `autoincrement` - is currently only supported for non-sharded collections). + is only supported for non-sharded collections). The sequence of generated keys is not guaranteed to be gap-free, because a new key will be generated on every document insert attempt, not just for successful inserts. @@ -3238,11 +3236,13 @@ paths: The increment value for the `autoincrement` key generator. Not allowed for other key generator types. type: integer + default: 1 offset: description: | The initial offset value for the `autoincrement` key generator. Not allowed for other key generator types. type: integer + default: 0 type: description: | The type of the collection to create. @@ -3295,8 +3295,9 @@ paths: If a server fails, this is detected automatically and one of the servers holding copies take over, usually without an error being reported. + + Default: The `replicationFactor` defined by the database. type: integer - default: 1 writeConcern: description: | Determines how many copies of each shard are required to be @@ -3305,7 +3306,7 @@ paths: up-to-date copies succeed at the same time, however. The value of `writeConcern` cannot be greater than `replicationFactor`. - If `distributeShardsLike` is set, the default `writeConcern` + Default: If `distributeShardsLike` is set, the default `writeConcern` is that of the prototype collection. For SatelliteCollections, the `writeConcern` is automatically controlled to equal the number of DB-Servers and has a value of `0`. @@ -3392,7 +3393,7 @@ paths: This feature requires the `distributeShardsLike` attribute of the collection to be set to the name of another collection. It also requires the `shardKeys` attribute of the - collection to be set to a single shard key attribute, with an additional ':' + collection to be set to a single shard key attribute, with an additional `:` at the end. A further restriction is that whenever documents are stored or updated in the collection, the value stored in the `smartJoinAttribute` must be a string. @@ -3823,10 +3824,11 @@ paths: in: query required: false description: | - Whether or not the collection to drop is a system collection. This parameter + Whether the collection to drop is a system collection. This parameter must be set to `true` in order to drop a system collection. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/documents.md b/site/content/3.12/develop/http-api/documents.md index 8fb1a797b1..2a2083475f 100644 --- a/site/content/3.12/develop/http-api/documents.md +++ b/site/content/3.12/develop/http-api/documents.md @@ -111,7 +111,7 @@ paths: in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one + 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. schema: @@ -274,7 +274,7 @@ paths: in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one + If the `If-None-Match` header is given, then it must contain exactly one ETag. If the current document revision is not equal 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. @@ -431,8 +431,8 @@ paths: in: query required: false description: | - Additionally return the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -440,8 +440,9 @@ paths: in: query required: false description: | - Additionally return the complete old document under the attribute `old` - in the result. Only available if the overwrite option is used. + Whether to additionally include the complete previous document under the + `old` attribute in the result. Only available if the `overwriteMode` + parameter is to `"update"` or `"replace"`, or if `overwrite` is set to `true`. schema: type: boolean default: false @@ -906,8 +907,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -915,8 +916,8 @@ paths: in: query required: false description: | - Return additionally the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -1270,8 +1271,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -1279,8 +1280,8 @@ paths: in: query required: false description: | - Return additionally the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -1552,8 +1553,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -1783,9 +1784,9 @@ paths: software does not support payload bodies in `GET` requests. {{}} - Returns the documents identified by their `_key` in the body objects. + Returns the documents identified by their `_key` attribute. The body of the request _must_ contain a JSON array of either - strings (the `_key` values to lookup) or search documents. + strings (the `_key` values to look up) or search documents. A search document _must_ contain at least a value for the `_key` field. A value for `_rev` _may_ be specified to verify whether the document @@ -1862,8 +1863,13 @@ paths: description: | An array of documents to retrieve. type: array - items: - type: object + #items: + # type: [string, object] + #required: + # - _key + #properties: + # _key: + # type: string responses: '200': description: | @@ -1992,8 +1998,8 @@ paths: in: query required: false description: | - Additionally return the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -2001,8 +2007,9 @@ paths: in: query required: false description: | - Additionally return the complete old document under the attribute `old` - in the result. Only available if the overwrite option is used. + Whether to additionally include the complete previous document under the + `old` attribute in the result. Only available if the `overwriteMode` + parameter is to `"update"` or `"replace"`, or if `overwrite` is set to `true`. schema: type: boolean default: false @@ -2358,8 +2365,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - documents under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -2367,8 +2374,8 @@ paths: in: query required: false description: | - Return additionally the complete new documents under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -2623,8 +2630,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - documents under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -2632,8 +2639,8 @@ paths: in: query required: false description: | - Return additionally the complete new documents under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -2827,10 +2834,11 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2843,6 +2851,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: ignoreRevs in: query required: false diff --git a/site/content/3.12/develop/http-api/foxx.md b/site/content/3.12/develop/http-api/foxx.md index 51e2115551..a8b1e29bf4 100644 --- a/site/content/3.12/develop/http-api/foxx.md +++ b/site/content/3.12/develop/http-api/foxx.md @@ -48,6 +48,7 @@ paths: Whether or not system services should be excluded from the result. schema: type: boolean + default: false responses: '200': description: | @@ -165,6 +166,7 @@ paths: Set to `true` to enable development mode. schema: type: boolean + default: false - name: setup in: query required: false @@ -172,6 +174,7 @@ paths: Set to `false` to not run the service's setup script. schema: type: boolean + default: true - name: legacy in: query required: false @@ -179,6 +182,7 @@ paths: Set to `true` to install the service in 2.8 legacy compatibility mode. schema: type: boolean + default: false responses: '201': description: | @@ -221,6 +225,7 @@ paths: Set to `false` to not run the service's teardown script. schema: type: boolean + default: true responses: '204': description: | @@ -294,6 +299,7 @@ paths: Set to `false` to not run the old service's teardown script. schema: type: boolean + default: true - name: setup in: query required: false @@ -301,6 +307,7 @@ paths: Set to `false` to not run the new service's setup script. schema: type: boolean + default: true - name: legacy in: query required: false @@ -308,6 +315,7 @@ paths: Set to `true` to install the new service in 2.8 legacy compatibility mode. schema: type: boolean + default: false - name: force in: query required: false @@ -315,6 +323,7 @@ paths: Set to `true` to force service install even if no service is installed under given mount. schema: type: boolean + default: false responses: '200': description: | @@ -388,6 +397,7 @@ paths: Set to `true` to run the old service's teardown script. schema: type: boolean + default: false - name: setup in: query required: false @@ -395,6 +405,7 @@ paths: Set to `false` to not run the new service's setup script. schema: type: boolean + default: true - name: legacy in: query required: false @@ -402,6 +413,7 @@ paths: Set to `true` to install the new service in 2.8 legacy compatibility mode. schema: type: boolean + default: false - name: force in: query required: false @@ -409,6 +421,7 @@ paths: Set to `true` to force service install even if no service is installed under given mount. schema: type: boolean + default: false responses: '200': description: | @@ -758,12 +771,9 @@ paths: content: application/json: schema: - type: object - properties: - data: - description: | - An arbitrary JSON value that will be parsed and passed to the - script as its first argument. + description: | + An arbitrary JSON value that will be parsed and passed to the + script as its first argument. responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/graphs/named-graphs.md b/site/content/3.12/develop/http-api/graphs/named-graphs.md index 52ba90ad4f..85d2ad9ca0 100644 --- a/site/content/3.12/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.12/develop/http-api/graphs/named-graphs.md @@ -149,6 +149,8 @@ paths: description: | The replication factor used for every new collection in the graph. For SatelliteGraphs, it is the string `"satellite"`. + + Default: The `replicationFactor` defined by the database. type: integer writeConcern: description: | @@ -293,7 +295,7 @@ paths: default: false options: description: | - a JSON object to define options for creating collections within this graph. + Options for creating collections within this graph. It can contain the following attributes: type: object properties: @@ -319,11 +321,14 @@ paths: The number of shards that is used for every collection within this graph. Cannot be modified later. type: integer + default: 1 replicationFactor: description: | The replication factor used when initially creating collections for this graph. Can be set to `"satellite"` to create a SatelliteGraph, which then ignores `numberOfShards`, `minReplicationFactor`, and `writeConcern`. + + Default: The `replicationFactor` defined by the database. type: integer writeConcern: description: | @@ -336,9 +341,6 @@ paths: For SatelliteGraphs, the `writeConcern` is automatically controlled to equal the number of DB-Servers and the attribute is not available. _(cluster only)_ type: integer - required: - - numberOfShards - - replicationFactor responses: '201': description: | @@ -1874,6 +1876,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false responses: '200': description: | @@ -3730,8 +3733,8 @@ paths: in: query required: false description: | - Define if the response should contain the complete - new version of the document. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -4378,8 +4381,8 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -4387,8 +4390,8 @@ paths: in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -4823,8 +4826,8 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -4832,8 +4835,8 @@ paths: in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -5258,8 +5261,8 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -5584,8 +5587,8 @@ paths: in: query required: false description: | - Define if the response should contain the complete - new version of the document. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -6331,20 +6334,22 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: returnNew in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -6835,20 +6840,22 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: returnNew in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -7350,10 +7357,11 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: If-Match in: header required: false diff --git a/site/content/3.12/develop/http-api/hot-backups.md b/site/content/3.12/develop/http-api/hot-backups.md index b986c32ced..a585b2244c 100644 --- a/site/content/3.12/develop/http-api/hot-backups.md +++ b/site/content/3.12/develop/http-api/hot-backups.md @@ -61,8 +61,9 @@ paths: timeout: description: | The time in seconds that the operation tries to get a consistent - snapshot. The default is 120 seconds. - type: number + snapshot. + type: integer + default: 120 allowInconsistent: description: | If this flag is set to `true` and no global transaction lock can be @@ -70,6 +71,7 @@ paths: is taken. The default for this flag is `false` and in this case a timeout results in an HTTP 408 error. type: boolean + default: false force: description: | If this flag is set to `true` and no global transaction lock can be acquired @@ -84,6 +86,7 @@ paths: `allowInconsistent` and `force` are set to `true`, then the latter takes precedence and transactions are aborted. This is only available in the cluster. type: boolean + default: false responses: '201': description: | @@ -393,7 +396,7 @@ paths: description: | Configuration of remote repository. This is required when an upload operation is scheduled. In this case leave out the `uploadId` - attribute. See the description of the _arangobackup_ program in the manual + attribute. See [Rclone Configuration](../../components/tools/arangobackup/examples/#rclone-configuration) for a description of the `config` object. type: object uploadId: @@ -407,6 +410,7 @@ paths: Set this to `true` if a running upload operation should be aborted. In this case, the only other body parameter which is needed is `uploadId`. type: boolean + default: false responses: '200': description: | @@ -523,6 +527,9 @@ paths: application/json: schema: type: object + required: + - remoteRepository + - config properties: id: description: | @@ -545,7 +552,7 @@ paths: description: | Configuration of remote repository. This is required when a download operation is scheduled. In this case leave out the `downloadId` - attribute. See the description of the _arangobackup_ program in the manual + attribute. See [Rclone Configuration](../../components/tools/arangobackup/examples/#rclone-configuration) for a description of the `config` object. type: object downloadId: @@ -559,9 +566,7 @@ paths: Set this to `true` if a running download operation should be aborted. In this case, the only other body parameter which is needed is `downloadId`. type: boolean - required: - - remoteRepository - - config + default: false responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/indexes/_index.md b/site/content/3.12/develop/http-api/indexes/_index.md index 479dfd2604..f759f7e174 100644 --- a/site/content/3.12/develop/http-api/indexes/_index.md +++ b/site/content/3.12/develop/http-api/indexes/_index.md @@ -60,6 +60,7 @@ paths: Whether to include figures and estimates in the result. schema: type: boolean + default: false - name: withHidden in: query required: false @@ -69,6 +70,7 @@ paths: background are hidden. schema: type: boolean + default: false responses: '200': description: | @@ -270,14 +272,9 @@ paths: content: application/json: schema: + description: | + The options for the index. The available attributes depend on the index type. type: object - required: - - index-details - properties: - index-details: - description: | - The options for the index. - type: object responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/indexes/fulltext.md b/site/content/3.12/develop/http-api/indexes/fulltext.md index 687ca29230..318f73ba75 100644 --- a/site/content/3.12/develop/http-api/indexes/fulltext.md +++ b/site/content/3.12/develop/http-api/indexes/fulltext.md @@ -67,10 +67,11 @@ paths: type: string minLength: description: | - 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. + Minimum character length of words to index. The default is + low, thus it is recommended to set this value explicitly + when creating the index. type: integer + default: 2 inBackground: description: | Set this option to `true` to keep the collection/shards available for diff --git a/site/content/3.12/develop/http-api/indexes/geo-spatial.md b/site/content/3.12/develop/http-api/indexes/geo-spatial.md index ad51599a94..4d1eac25ed 100644 --- a/site/content/3.12/develop/http-api/indexes/geo-spatial.md +++ b/site/content/3.12/develop/http-api/indexes/geo-spatial.md @@ -75,15 +75,17 @@ paths: type: array minItems: 1 maxItems: 2 + uniqueItems: true items: type: string geoJson: description: | - If a geo-spatial index on a `location` is constructed - and `geoJson` is `true`, then the order within the array is longitude - followed by latitude. This corresponds to the format described in + If you create a geo-spatial index over a single attribute and `geoJson` + is `true`, then the coordinate order within the attribute's array is + longitude followed by latitude. This corresponds to the format described in type: boolean + default: false legacyPolygons: description: | If `geoJson` is set to `true`, then this option controls how GeoJSON Polygons diff --git a/site/content/3.12/develop/http-api/indexes/inverted.md b/site/content/3.12/develop/http-api/indexes/inverted.md index fb9f1164ba..2e050c3320 100644 --- a/site/content/3.12/develop/http-api/indexes/inverted.md +++ b/site/content/3.12/develop/http-api/indexes/inverted.md @@ -59,6 +59,7 @@ paths: attribute path in the `name` property), or a mix of both. type: array minItems: 1 + uniqueItems: true items: type: object required: @@ -246,9 +247,8 @@ paths: array (`[*]`), then the elements are indexed separately. Otherwise, the array is indexed as a whole, but only `geopoint` and `aql` Analyzers accept array inputs. You cannot use an array expansion if `searchField` is enabled. - - Default: `false` type: boolean + default: false cache: description: | Enable this option to always cache the field normalization values in memory @@ -264,13 +264,12 @@ paths: fields that are indexed with Geo Analyzers in memory for all fields by default. This can improve the performance of geo-spatial queries. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false storedValues: description: | The optional `storedValues` attribute can contain an array of objects with paths @@ -308,6 +307,7 @@ paths: description: | A list of attribute paths. The `.` character denotes sub-attributes. type: array + #uniqueItems: true # Duplicate values are silently ignored items: type: string compression: @@ -325,13 +325,12 @@ paths: memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false primarySort: description: | You can define a primary sort order to enable an AQL optimization. If a query @@ -378,13 +377,12 @@ paths: Otherwise, these values are memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false primaryKeyCache: description: | Enable this option to always cache the primary key column in memory. This can @@ -392,13 +390,12 @@ paths: values are memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false optimizeTopK: description: | This option only applies if you use the inverted index in a `search-alias` Views. @@ -418,18 +415,16 @@ paths: You can define up to 64 expressions per View. Example: `["BM25(@doc) DESC", "TFIDF(@doc, true) DESC"]` - - Default: `[]` type: array + default: [] items: type: string analyzer: description: | The name of an Analyzer to use by default. This Analyzer is applied to the values of the indexed fields for which you don't define Analyzers explicitly. - - Default: `identity` type: string + default: identity features: description: | A list of Analyzer features. You can set this option to overwrite what features @@ -449,13 +444,12 @@ paths: sub-attributes that are configured in the `fields` array (and their sub-attributes). The `analyzer` and `features` properties apply to the sub-attributes. - Default: `false` - {{}} Using `includeAllFields` for a lot of attributes in combination with complex Analyzers may significantly slow down the indexing process. {{}} type: boolean + default: false trackListPositions: description: | This option only applies if you use the inverted index in a `search-alias` Views, @@ -469,10 +463,12 @@ paths: You don't specify an array element in queries, e.g. `doc.attr == "valueY"`, and all elements are searched for a match. type: boolean + default: false parallelism: description: | - The number of threads to use for indexing the fields. Default: `2` + The number of threads to use for indexing the fields. type: integer + default: 2 inBackground: description: | Set this option to `true` to keep the collection/shards available for @@ -483,7 +479,7 @@ paths: cleanupIntervalStep: description: | Wait at least this many commits between removing unused files in the - ArangoSearch data directory (default: 2, to disable use: 0). + ArangoSearch data directory (set to `0` to disable). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value causes a lot of disk space to be wasted. @@ -499,11 +495,11 @@ paths: However, the files for the released states/snapshots are left on disk, and only removed by "cleanup" operation. type: integer + default: 2 commitIntervalMsec: description: | Wait at least this many milliseconds between committing inverted index data store - changes and making documents visible to queries (default: 1000, to disable - use: 0). + changes and making documents visible to queries (set to `0` to disable). For the case where there are a lot of inserts/updates, a higher value causes the index not to account for them and memory usage continues to grow until the commit. A lower value impacts performance, including the case where there are no or only a @@ -522,11 +518,12 @@ paths: subsequent ArangoDB transactions, in-progress ArangoDB transactions will still continue to return a repeatable-read state. type: integer + default: 1000 consolidationIntervalMsec: description: | Wait at least this many milliseconds between applying `consolidationPolicy` to consolidate the inverted index data store and possibly release space on the filesystem - (default: 1000, to disable use: 0). + (set to `0` to disable). For the case where there are a lot of data modification operations, a higher value could potentially have the data store consume more space and file handles. For the case where there are a few data modification operations, a lower value @@ -540,10 +537,10 @@ paths: compaction operations are governed by `consolidationIntervalMsec` and the candidates for compaction are selected via `consolidationPolicy`. type: integer + default: 1000 consolidationPolicy: description: | - The consolidation policy to apply for selecting which segments should be merged - (default: {}). + The consolidation policy to apply for selecting which segments should be merged. _Background:_ With each ArangoDB transaction that inserts documents, one or more @@ -564,53 +561,60 @@ paths: upon several possible configurable formulas as defined by their types. The supported types are: - - `"tier"` (default): consolidate based on segment byte size and live + - `"tier"`: consolidate based on segment byte size and live document count as dictated by the customization attributes. type: string + default: tier segmentsBytesFloor: description: | Defines the value (in bytes) to treat all smaller segments as equal for - consolidation selection. Default: `2097152` + consolidation selection. type: integer + default: 2097152 segmentsBytesMax: description: | The maximum allowed size of all consolidated segments in bytes. - Default: `5368709120` type: integer + default: 5368709120 segmentsMax: description: | The maximum number of segments that are evaluated as candidates for - consolidation. Default: `10` + consolidation. type: integer + default: 10 segmentsMin: description: | The minimum number of segments that are evaluated as candidates for - consolidation. Default: `1` + consolidation. type: integer + default: 1 minScore: description: | - Filter out consolidation candidates with a score less than this. Default: `0` + Filter out consolidation candidates with a score less than this. type: integer + default: 0 writebufferIdle: description: | Maximum number of writers (segments) cached in the pool - (default: 64, use 0 to disable) + (set to `0` to disable). type: integer + default: 64 writebufferActive: description: | Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers - (segments) finish (default: 0, use 0 to disable) + (segments) finish (set to `0` to disable). type: integer + default: 0 writebufferSizeMax: description: | Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. `0` value turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (ArangoDB server startup option). `0` value should be used carefully due to - high potential memory consumption - (default: 33554432, use 0 to disable) + high potential memory consumption (set to `0 `to disable). type: integer + default: 33554432 responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/indexes/multi-dimensional.md b/site/content/3.12/develop/http-api/indexes/multi-dimensional.md index 53aba9abe6..e38f031495 100644 --- a/site/content/3.12/develop/http-api/indexes/multi-dimensional.md +++ b/site/content/3.12/develop/http-api/indexes/multi-dimensional.md @@ -57,6 +57,7 @@ paths: An array of attribute names used for each dimension. Array expansions are not allowed. type: array minItems: 1 + uniqueItems: true items: type: string fieldValueTypes: @@ -69,6 +70,7 @@ paths: An array of attribute names used as search prefix. Array expansions are not allowed. type: array + uniqueItems: true items: type: string storedValues: @@ -99,6 +101,7 @@ paths: The maximum number of attributes in `storedValues` is 32. type: array + uniqueItems: true items: type: string unique: diff --git a/site/content/3.12/develop/http-api/indexes/persistent.md b/site/content/3.12/develop/http-api/indexes/persistent.md index 99be09a69f..7017836a3b 100644 --- a/site/content/3.12/develop/http-api/indexes/persistent.md +++ b/site/content/3.12/develop/http-api/indexes/persistent.md @@ -82,6 +82,7 @@ paths: You can expand one array attribute with `[*]`. type: array minItems: 1 + uniqueItems: true items: type: string storedValues: @@ -105,23 +106,27 @@ paths: type: string unique: description: | - If `true`, then create a unique index. Defaults to `false`. + Whether to create the index with a uniqueness constraint. In unique indexes, only the attributes in `fields` are checked for uniqueness, but the attributes in `storedValues` are not checked for their uniqueness. type: boolean + default: false sparse: description: | - If `true`, then create a sparse index. Defaults to `false`. + Whether create a sparse index that excludes documents with at least + one of the `fields` missing or set to `null`. type: boolean + default: false deduplicate: description: | The attribute controls whether inserting duplicate index values - from the same document into a unique array index will lead to a unique constraint - error or not. The default value is `true`, so only a single instance of each - non-unique index value will be inserted into the index per document. Trying to - insert a value into the index that already exists in the index will always fail, + from the same document into a unique array index lead to a unique constraint + error or not. Only a single instance of each non-unique index value + is inserted into the index per document by default. Trying to + insert a value into the index that already exists in the index always fails, regardless of the value of this attribute. type: boolean + default: true estimates: description: | This attribute controls whether index selectivity estimates are maintained for the @@ -133,9 +138,9 @@ paths: competing indexes in AQL queries when there are multiple candidate indexes to choose from. - The `estimates` attribute is optional and defaults to `true` if not set. - It has no effect on indexes other than `persistent`, `mdi`, and `mdi-prefixed`. + The option has no effect on indexes other than `persistent`, `mdi`, and `mdi-prefixed`. type: boolean + default: true cacheEnabled: description: | This attribute controls whether an extra in-memory hash cache is @@ -157,6 +162,7 @@ paths: `cacheEnabled` defaults to `false` and should only be used for indexes that are known to benefit from an extra layer of caching. type: boolean + default: false inBackground: description: | Set this option to `true` to keep the collection/shards available for diff --git a/site/content/3.12/develop/http-api/indexes/vector.md b/site/content/3.12/develop/http-api/indexes/vector.md index a98bd79166..98b973d3d6 100644 --- a/site/content/3.12/develop/http-api/indexes/vector.md +++ b/site/content/3.12/develop/http-api/indexes/vector.md @@ -67,8 +67,9 @@ paths: type: string parallelism: description: | - The number of threads to use for indexing. Default: `2` + The number of threads to use for indexing. type: integer + default: 2 inBackground: description: | Set this option to `true` to keep the collection/shards available for diff --git a/site/content/3.12/develop/http-api/jobs.md b/site/content/3.12/develop/http-api/jobs.md index 4100b2e04e..c019c47cdf 100644 --- a/site/content/3.12/develop/http-api/jobs.md +++ b/site/content/3.12/develop/http-api/jobs.md @@ -624,6 +624,7 @@ paths: or `done` as `job-id` to list jobs. schema: type: number + default: 100 responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/monitoring/logs.md b/site/content/3.12/develop/http-api/monitoring/logs.md index 64bef4afa0..5ba17a8a9f 100644 --- a/site/content/3.12/develop/http-api/monitoring/logs.md +++ b/site/content/3.12/develop/http-api/monitoring/logs.md @@ -44,9 +44,10 @@ paths: - `warning` or `2` - `info` or `3` - `debug` or `4` - The default value is `info`. + - `trace` or `5` schema: - type: string + #type: [string, integer] + default: info - name: level in: query required: false @@ -59,10 +60,11 @@ paths: in: query required: false description: | - Returns all log entries such that their log entry identifier (`lid` .) + Returns all log entries such that their log entry identifier (`id` value) is greater or equal to `start`. schema: type: number + default: 0 - name: size in: query required: false @@ -78,6 +80,7 @@ paths: and `size` can be used for pagination. schema: type: number + default: 0 - name: search in: query required: false @@ -91,9 +94,10 @@ paths: description: | Sort the log entries either ascending (if `sort` is `asc`) or descending (if `sort` is `desc`) according to their `id` values. Note that the `id` - imposes a chronological order. The default value is `asc`. + imposes a chronological order. schema: type: string + default: asc - name: serverId in: query required: false @@ -149,9 +153,10 @@ paths: - `warning` or `2` - `info` or `3` - `debug` or `4` - The default value is `info`. + - `trace` or `5` schema: - type: string + #type: [string, integer] + default: info - name: level in: query required: false @@ -168,6 +173,7 @@ paths: is greater or equal to `start`. schema: type: number + default: 0 - name: size in: query required: false @@ -183,6 +189,7 @@ paths: and `size` can be used for pagination. schema: type: number + default: 0 - name: search in: query required: false @@ -196,9 +203,10 @@ paths: description: | Sort the log entries either ascending (if `sort` is `asc`) or descending (if `sort` is `desc`) according to their `lid` values. Note that the `lid` - imposes a chronological order. The default value is `asc`. + imposes a chronological order. schema: type: string + default: asc - name: serverId in: query required: false diff --git a/site/content/3.12/develop/http-api/queries/aql-queries.md b/site/content/3.12/develop/http-api/queries/aql-queries.md index 02a81cc341..92d4306fa7 100644 --- a/site/content/3.12/develop/http-api/queries/aql-queries.md +++ b/site/content/3.12/develop/http-api/queries/aql-queries.md @@ -347,12 +347,12 @@ paths: respect to the `ttl`. The cursor will be removed on the server automatically after the specified amount of time. This is useful to ensure garbage collection of cursors that are not fully fetched by clients. - - You can configure a default TTL with the `--query.registry-ttl` startup option. - If not set, the defaults are 30 seconds for single servers and 600 seconds for - Coordinators of a cluster deployment. The time-to-live is renewed upon every access to the cursor. + + Default: Controlled by the `--query.registry-ttl` startup option. + If not set, the defaults are 30 seconds for single servers and 600 seconds for + Coordinators of a cluster deployment. type: integer memoryLimit: description: | @@ -362,7 +362,7 @@ paths: no memory limit, but the `--query.global-memory-limit` startup option may still limit it. - You can configure a default per-query memory limit with the + Default: You can configure a default per-query memory limit with the `--query.memory-limit` startup option. You can only increase this default memory limit if `--query.memory-limit-override` is enabled. @@ -408,15 +408,18 @@ paths: maxNumberOfPlans: description: | Limits the maximum number of plans that are created by the AQL query optimizer. + + Default: Controlled by the `--query.optimizer-max-plans` startup option. type: integer maxNodesPerCallstack: description: | The number of execution nodes in the query plan after that stack splitting is - performed to avoid a potential stack overflow. Defaults to the configured value - of the startup option `--query.max-nodes-per-callstack`. + performed to avoid a potential stack overflow. This option is only useful for testing and debugging and normally does not need any adjustment. + + Default: Controlled by the `--query.max-nodes-per-callstack` startup option. type: integer maxWarningCount: description: | @@ -427,11 +430,12 @@ paths: failOnWarning: description: | If set to `true`, the query throws an exception and aborts instead of producing - a warning. This option should be used during development to catch potential issues + a warning. You should use this option during development to catch potential issues early. When the attribute is set to `false`, warnings are not propagated to exceptions and are returned with the query result. - There is also a `--query.fail-on-warning` startup option for setting the - default value for `failOnWarning`, so it does not need to be set on a per-query basis. + + Default: Controlled by the `--query.fail-on-warning` startup option, + so you don't need to set it on a per-query basis. type: boolean allowRetry: description: | @@ -517,7 +521,7 @@ paths: for the query. If you set it to `true`, the query cache is checked for a cached result **if** the query cache mode is either set to `on` or `demand`. - You can configure a default mode with the `--query.cache-mode` startup option. + Default: Controlled by the `--query.cache-mode` startup option. type: boolean usePlanCache: description: | @@ -545,7 +549,7 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: 128 MiB, respectively the value of the + Default: 128 MiB, respectively the value of the `--temp.intermediate-results-spillover-threshold-memory-usage` startup option. @@ -570,7 +574,7 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: 5 million rows, respectively the value of the + Default: 5 million rows, respectively the value of the `--temp.intermediate-results-spillover-threshold-num-rows` startup option. @@ -588,10 +592,13 @@ paths: properties: rules: description: | - A list of to-be-included or to-be-excluded optimizer rules can be put into this - attribute, telling the optimizer to include or exclude specific rules. To disable - a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is - also a pseudo-rule `all`, which matches all optimizer rules. `-all` disables all rules. + A list of optimizer rules, telling the optimizer to + include or exclude specific rules. See the + [List of optimizer rules](../../../aql/execution-and-performance/query-optimization.md#list-of-optimizer-rules). + + To disable a rule, prefix its name with `-`. To enable a rule, + prefix it with `+`. There is also a pseudo-rule `all` that + matches all optimizer rules. `-all` disables all rules. type: array items: type: string @@ -603,6 +610,7 @@ paths: per query plan node in `stats.nodes` sub-attribute of the `extra` return attribute. Additionally, the query plan is returned in the `extra.plan` sub-attribute. type: integer + default: 0 satelliteSyncWait: description: | This parameter allows to configure how long a DB-Server has time @@ -614,9 +622,10 @@ paths: maxRuntime: description: | The query has to be executed within the given runtime or it is killed. - The value is specified in seconds. The default value is `0.0` (no timeout). + The value is specified in seconds. A value of `0.0` means no timeout. + + Default: Controlled by the `--query.max-runtime` startup option. type: number - default: 0.0 maxDNFConditionMembers: description: | A threshold for the maximum number of `OR` sub-nodes in the internal @@ -633,28 +642,28 @@ paths: condition, the conversion is aborted, and the query continues with a simplified internal representation of the condition, which **cannot be used for index lookups**. - You can set the threshold globally instead of per query with the - `--query.max-dnf-condition-members` startup option. + Default: Controlled by the `--query.max-dnf-condition-members` startup option + to set the threshold globally instead of per query. type: integer maxTransactionSize: description: | The transaction size limit in bytes. - You can configure the default with the `--rocksdb.max-transaction-size` startup option. + Default: Controlled by the `--rocksdb.max-transaction-size` startup option. type: integer intermediateCommitSize: description: | The maximum total size of operations after which an intermediate commit is performed automatically. - You can configure the default with the `--rocksdb.intermediate-commit-size` startup option. + Default: Controlled by `--rocksdb.intermediate-commit-size` startup option. type: integer intermediateCommitCount: description: | The maximum number of operations after which an intermediate commit is performed automatically. - You can configure the default with the `--rocksdb.intermediate-commit-count` startup option. + Default: Controlled by the `--rocksdb.intermediate-commit-count` startup option. type: integer skipInaccessibleCollections: description: | @@ -665,6 +674,7 @@ paths: execute AQL queries on that graph. You can naturally limit the accessible results by changing the access rights of users on collections. type: boolean + default: false allowDirtyReads: description: | If you set this option to `true` and execute the query against a cluster @@ -675,7 +685,13 @@ paths: namely obsolete revisions of documents because changes have not yet been replicated to the follower, as well as changes to documents before they are officially committed on the leader. + + The option is ignored if this operation is part of a Stream Transaction + (`x-arango-trx-id` header). The `x-arango-allow-dirty-read` header set + when creating the transaction decides about dirty reads for the entire + transaction, not the individual read operations. type: boolean + default: false responses: '201': description: | @@ -2674,7 +2690,7 @@ paths: If set to `true`, then queries are tracked. If set to `false`, neither regular queries nor slow queries are tracked. - You can configure the default value with the `--query.tracking` startup option. + Default: Controlled by the `--query.tracking` startup option. type: boolean trackSlowQueries: description: | @@ -2683,14 +2699,14 @@ paths: `slowQueryThreshold`. In order for slow queries to be tracked, the `enabled` property must also be set to `true`. - You can configure the default value with the `--query.tracking-slow-queries` startup option. + Default: Controlled by the `--query.tracking-slow-queries` startup option. type: boolean trackBindVars: description: | If set to `true`, then the bind variables used in queries are tracked along with queries. - You can configure the default value with the `--query.tracking-with-bindvars` startup option. + Default: Controlled by the `--query.tracking-with-bindvars` startup option. type: boolean maxSlowQueries: description: | @@ -2698,13 +2714,14 @@ paths: of slow queries. If the list of slow queries is full, the oldest entry is discarded when additional slow queries occur. type: integer + default: 64 slowQueryThreshold: description: | The threshold value for treating a query as slow (in seconds). A query with a runtime greater or equal to this threshold value is put into the list of slow queries if slow query tracking is enabled. - You can configure the default value with the `--query.slow-threshold` startup option. + Default: Controlled by the `--query.slow-threshold` startup option. type: integer slowStreamingQueryThreshold: description: | @@ -2713,7 +2730,7 @@ paths: threshold value is put into the list of slow queries if slow query tracking is enabled. - You can configure the default value with the `--query.slow-streaming-threshold` startup option. + Default: Controlled by the `--query.slow-streaming-threshold` startup option. type: integer maxQueryStringLength: description: | @@ -3085,8 +3102,8 @@ paths: # explainRegisters allPlans: description: | - if set to `true`, all possible execution plans will be returned. - The default is `false`, meaning only the optimal plan will be returned. + If set to `true`, all possible execution plans are returned. + The default is `false`, meaning only the optimal plan is returned. type: boolean default: false maxNumberOfPlans: @@ -3094,6 +3111,8 @@ paths: The maximum number of plans that the optimizer is allowed to generate. Setting this attribute to a low value allows to put a cap on the amount of work the optimizer does. + + Default: Controlled by the `--query.optimizer-max-plans` startup option. type: integer fullCount: description: | @@ -3109,14 +3128,16 @@ paths: If set to `2`, the response includes the time it took to process each optimizer rule under `stats.rules`. type: integer + default: 0 maxNodesPerCallstack: description: | The number of execution nodes in the query plan after that stack splitting is - performed to avoid a potential stack overflow. Defaults to the configured value - of the startup option `--query.max-nodes-per-callstack`. + performed to avoid a potential stack overflow. This option is only useful for testing and debugging and normally does not need any adjustment. + + Default: Controlled by the `--query.max-nodes-per-callstack` startup option. type: integer maxWarningCount: description: | @@ -3131,8 +3152,8 @@ paths: early. When the attribute is set to `false`, warnings are not propagated to exceptions and are returned with the query result. - You can use the `--query.fail-on-warning` startup option to adjust the - default value for `failOnWarning` so you don't need to set it on a per-query basis. + Default: Controlled by the `--query.fail-on-warning` startup option, + so you don't need to set it on a per-query basis. type: boolean optimizer: description: | @@ -3141,10 +3162,13 @@ paths: properties: rules: description: | - A list of to-be-included or to-be-excluded optimizer rules can be put into this - attribute, telling the optimizer to include or exclude specific rules. To disable - a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is - also a pseudo-rule `all`, which matches all optimizer rules. `-all` disables all rules. + A list of optimizer rules, telling the optimizer to + include or exclude specific rules. See the + [List of optimizer rules](../../../aql/execution-and-performance/query-optimization.md#list-of-optimizer-rules). + + To disable a rule, prefix its name with `-`. To enable a rule, + prefix it with `+`. There is also a pseudo-rule `all` that + matches all optimizer rules. `-all` disables all rules. type: array items: type: string diff --git a/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md b/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md index fd3fa6932c..6be038563f 100644 --- a/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md +++ b/site/content/3.12/develop/http-api/queries/aql-query-results-cache.md @@ -225,9 +225,6 @@ paths: mode: description: | The mode the AQL query results cache operates in. - - You can configure the default value with the - `--query.cache-mode` startup option. type: string # Unquoted on and off are booleans in YAML 1.1! enum: ["off", "on", "demand"] @@ -235,32 +232,20 @@ paths: description: | The maximum number of query results that are stored per database-specific cache. - - You can configure the default value with the - `--query.cache-entries` startup option. type: integer maxResultsSize: description: | The maximum cumulated size of query results that are stored per database-specific cache (in bytes). - - You can configure the default value with the - `--query.cache-entries-max-size` startup option. type: integer maxEntrySize: description: | The maximum individual result size of queries that are stored per database-specific cache (in bytes). - - You can configure the default value with the - `--query.cache-entry-max-size` startup option. includeSystem: description: | Whether results of queries that involve system collections are stored in the query results cache. - - You can configure the default value with the - `--query.cache-include-system-collections` startup option. type: boolean '400': description: | @@ -318,6 +303,8 @@ paths: mode: description: | The mode the AQL query cache shall operate in. + + Default: Controlled by the `--query.cache-mode` startup option. type: string # Unquoted on and off are booleans in YAML 1.1! enum: ["off", "on", "demand"] @@ -325,21 +312,30 @@ paths: description: | The maximum number of query results that are stored per database-specific cache. + + Default: Controlled by the `--query.cache-entries` startup option. type: integer maxResultsSize: description: | The maximum cumulated size of query results that are stored per database-specific cache (in bytes). + + Default: Controlled by the `--query.cache-entries-max-size` startup option. type: integer maxEntrySize: description: | The maximum individual size of query results that are stored per database-specific cache (in bytes). + + Default: Controlled by the `--query.cache-entry-max-size` startup option. type: integer includeSystem: description: | Whether to store results of queries that involve system collections in the cache. + + Default: Controlled by the `--query.cache-include-system-collections` + startup option type: boolean responses: '200': diff --git a/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md b/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md index cf497ebdf8..25f9b271c1 100644 --- a/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md +++ b/site/content/3.12/develop/http-api/queries/user-defined-aql-functions.md @@ -202,13 +202,15 @@ paths: in: query required: false description: | + Possible values: - `true`: The function name provided in `name` is treated as a namespace prefix, and all functions in the specified namespace will be deleted. The returned number of deleted functions may become 0 if none matches the string. - `false`: The function name provided in `name` must be fully qualified, including any namespaces. If none matches the `name`, HTTP 404 is returned. schema: - type: string + type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/replication/replication-dump.md b/site/content/3.12/develop/http-api/replication/replication-dump.md index 32ce89dd72..240f70b647 100644 --- a/site/content/3.12/develop/http-api/replication/replication-dump.md +++ b/site/content/3.12/develop/http-api/replication/replication-dump.md @@ -112,16 +112,19 @@ paths: in: query required: false description: | - Include system collections in the result. The default value is `true`. + Include system collections in the result. schema: type: boolean + default: true - name: global in: query required: false description: | - Include all databases in the response. Only works on `_system` The default value is `false`. + Include all databases in the response. Only works in the context of + the `_system` database. schema: type: boolean + default: false - name: batchId in: query required: true @@ -197,7 +200,7 @@ paths: in: query required: false description: | - setting `state` to true will make the response also contain + Setting `state` to `true` makes the response also contain a `state` attribute with information about the leader state. This is used only internally during the replication process and should not be used by client applications. @@ -969,9 +972,10 @@ paths: in: query required: false description: | - Include system collections in the result. The default value is `true`. + Include system collections in the result. schema: type: boolean + default: true responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/replication/replication-logger.md b/site/content/3.12/develop/http-api/replication/replication-logger.md index 17b3d74b98..32d1199cd6 100644 --- a/site/content/3.12/develop/http-api/replication/replication-logger.md +++ b/site/content/3.12/develop/http-api/replication/replication-logger.md @@ -244,9 +244,10 @@ paths: in: query required: false description: | - Include system collections in the result. The default value is `true`. + Include system collections in the result. schema: type: boolean + default: true responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/replication/write-ahead-log.md b/site/content/3.12/develop/http-api/replication/write-ahead-log.md index 50bd2833dc..b4bcfda59d 100644 --- a/site/content/3.12/develop/http-api/replication/write-ahead-log.md +++ b/site/content/3.12/develop/http-api/replication/write-ahead-log.md @@ -270,9 +270,10 @@ paths: description: | Whether operations for all databases should be included. If set to `false`, only the operations for the current database are included. The value `true` is - only valid on the `_system` database. The default is `false`. + only valid on the `_system` database. schema: type: boolean + default: false - name: from in: query required: false diff --git a/site/content/3.12/develop/http-api/tasks.md b/site/content/3.12/develop/http-api/tasks.md index e1443c7e86..63056e0ea3 100644 --- a/site/content/3.12/develop/http-api/tasks.md +++ b/site/content/3.12/develop/http-api/tasks.md @@ -249,14 +249,15 @@ paths: description: | The name of the task. type: string + default: "user-defined task" command: description: | The JavaScript code to be executed. type: string params: description: | - The parameters to be passed to the command. - type: string + The value to be passed to the command. + It can be of any type. period: description: | The number of seconds between the executions. @@ -265,6 +266,7 @@ paths: description: | The number of seconds for the initial delay. type: integer + default: 0 responses: '200': description: | @@ -397,8 +399,8 @@ paths: type: string params: description: | - The parameters to be passed to the command. - type: string + The value to be passed to the command. + It can be of any type. period: description: | The number of seconds between the executions. @@ -407,6 +409,7 @@ paths: description: | The number of seconds for the initial delay. type: integer + default: 0 responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/transactions/javascript-transactions.md b/site/content/3.12/develop/http-api/transactions/javascript-transactions.md index 50423b214c..1443242a78 100644 --- a/site/content/3.12/develop/http-api/transactions/javascript-transactions.md +++ b/site/content/3.12/develop/http-api/transactions/javascript-transactions.md @@ -92,7 +92,7 @@ paths: properties: collections: description: | - `collections` must be a JSON object that can have one or all sub-attributes + Must be a JSON object that can have one or all sub-attributes `read`, `write` or `exclusive`, each being an array of collection names or a single collection name as string. Collections that will be written to in the transaction must be declared with the `write` or `exclusive` attribute or it @@ -101,42 +101,65 @@ paths: to let transactions fail in case of undeclared collections for reading. Collections for reading should be fully declared if possible, to avoid deadlocks. - type: string + type: object + properties: + read: + description: | + A single collection or a list of collections to use in + the transaction in read-only mode. + # type: [string, array] + # items: + # type: string + write: + description: | + A single collection or a list of collections to use in + the transaction in write or read mode. + # type: [string, array] + # items: + # type: string + exclusive: + description: | + A single collection or a list of collections to acquire + exclusive write access for. + # type: [string, array] + # items: + # type: string action: description: | - the actual transaction operations to be executed, in the - form of stringified JavaScript code. The code will be executed on server + The actual transaction operations to be executed, in the + form of stringified JavaScript code. The code is executed on the 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` + value returned is also returned by the REST API in the `result` attribute if the transaction committed successfully. type: string waitForSync: description: | - an optional boolean flag that, if set, will force the + An optional boolean flag that, if set, forces the transaction to write all data to disk before returning. type: boolean allowImplicit: description: | Allow reading from undeclared collections. type: boolean + default: true lockTimeout: description: | - an optional numeric value that can be used to set a - timeout in seconds for waiting on collection locks. This option is only - meaningful when using exclusive locks. If not specified, a default value of - 900 seconds will be used. Setting `lockTimeout` to `0` will make ArangoDB - not time out waiting for a lock. + The timeout in seconds for waiting on collection locks. + This option is only meaningful when using exclusive locks. + Set `lockTimeout` to `0` to make ArangoDB not time out + waiting for a lock. type: integer + default: 900 params: description: | - optional arguments passed to `action`. - type: string + Optional argument passed to `action`. Can be of any type. maxTransactionSize: description: | Transaction size limit in bytes. type: integer + default: 18446744073709551615 # Max value of uint64_t responses: '200': description: | diff --git a/site/content/3.12/develop/http-api/transactions/stream-transactions.md b/site/content/3.12/develop/http-api/transactions/stream-transactions.md index 147d446747..0deab59187 100644 --- a/site/content/3.12/develop/http-api/transactions/stream-transactions.md +++ b/site/content/3.12/develop/http-api/transactions/stream-transactions.md @@ -22,7 +22,7 @@ ArangoDB. No `action` attribute is supported. The Stream Transaction API works in *conjunction* with other APIs in ArangoDB. To use the transaction for a supported operation a client needs to specify the transaction identifier in the `x-arango-trx-id` HTTP header on each request. -This will automatically cause these operations to use the specified transaction. +This automatically causes these operations to use the specified transaction. Supported transactional API operations include: @@ -51,7 +51,7 @@ paths: until the entire transaction times out. The transaction description must be passed in the body of the POST request. - If the transaction can be started on the server, *HTTP 201* will be returned. + If the transaction can be started on the server, *HTTP 201* is returned. For successfully started transactions, the returned JSON object has the following properties: @@ -66,9 +66,9 @@ paths: - `status`: containing the string 'running' If the transaction specification is either missing or malformed, the server - will respond with *HTTP 400* or *HTTP 404*. + responds with *HTTP 400* or *HTTP 404*. - The body of the response will then contain a JSON object with additional error + The body of the response then contains 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) @@ -108,33 +108,59 @@ paths: properties: collections: description: | - `collections` must be a JSON object that can have one or all sub-attributes + Must be a JSON object that can have one or all sub-attributes `read`, `write` or `exclusive`, each being an array of collection names or a single collection name as string. Collections that will be written to in the transaction must be declared with the `write` or `exclusive` attribute or it will fail, whereas non-declared collections from which is solely read will be added lazily. type: object + properties: + read: + description: | + A single collection or a list of collections to use in + the transaction in read-only mode. + # type: [string, array] + # items: + # type: string + write: + description: | + A single collection or a list of collections to use in + the transaction in write or read mode. + # type: [string, array] + # items: + # type: string + exclusive: + description: | + A single collection or a list of collections to acquire + exclusive write access for. + # type: [string, array] + # items: + # type: string waitForSync: description: | - an optional boolean flag that, if set, will force the + An optional boolean flag that, if set, forces the transaction to write all data to disk before returning. type: boolean allowImplicit: description: | Allow reading from undeclared collections. type: boolean + default: true lockTimeout: description: | - an optional numeric value that can be used to set a - timeout in seconds for waiting on collection locks. This option is only - meaningful when using exclusive locks. If not specified, a default - value will be used. Setting `lockTimeout` to `0` will make ArangoDB - not time out waiting for a lock. + The timeout in seconds for waiting on collection locks. + This option is only meaningful when using exclusive locks. + Set `lockTimeout` to `0` to make ArangoDB not time out + waiting for a lock. type: integer + default: 900 maxTransactionSize: description: | Transaction size limit in bytes. + + Default: Controlled by the `--transaction.streaming-max-transaction-size` + startup option. type: integer skipFastLockRound: description: | @@ -301,7 +327,7 @@ paths: Commit a running server-side transaction. Committing is an idempotent operation. It is not an error to commit a transaction more than once. - If the transaction can be committed, *HTTP 200* will be returned. + If the transaction can be committed, *HTTP 200* is returned. The returned JSON object has the following properties: - `error`: boolean flag to indicate if an error occurred (`false` @@ -315,9 +341,9 @@ paths: If the transaction cannot be found, committing is not allowed or the transaction was aborted, the server - will respond with *HTTP 400*, *HTTP 404* or *HTTP 409*. + responds with *HTTP 400*, *HTTP 404* or *HTTP 409*. - The body of the response will then contain a JSON object with additional error + The body of the response then contains 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) @@ -402,7 +428,7 @@ paths: Abort a running server-side transaction. Aborting is an idempotent operation. It is not an error to abort a transaction more than once. - If the transaction can be aborted, *HTTP 200* will be returned. + If the transaction can be aborted, *HTTP 200* is returned. The returned JSON object has the following properties: - `error`: boolean flag to indicate if an error occurred (`false` @@ -416,9 +442,9 @@ paths: If the transaction cannot be found, aborting is not allowed or the transaction was already committed, the server - will respond with *HTTP 400*, *HTTP 404* or *HTTP 409*. + responds with *HTTP 400*, *HTTP 404* or *HTTP 409*. - The body of the response will then contain a JSON object with additional error + The body of the response then contains 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) @@ -502,7 +528,7 @@ paths: description: | The result is an object with the `transactions` attribute, which contains an array of transactions. - In a cluster the array will contain the transactions from all Coordinators. + In a cluster, the array contains the transactions from all Coordinators. Each array entry contains an object with the following attributes: diff --git a/site/content/3.12/develop/http-api/users.md b/site/content/3.12/develop/http-api/users.md index 1a03c6c984..c527c88f83 100644 --- a/site/content/3.12/develop/http-api/users.md +++ b/site/content/3.12/develop/http-api/users.md @@ -62,9 +62,10 @@ paths: type: string passwd: description: | - The user password as a string. If not specified, it will default to an empty + The user password as a string. If not specified, it default to an empty string. type: string + default: "" active: description: | Whether the user account should be able to log in to the database system. @@ -154,9 +155,10 @@ paths: properties: passwd: description: | - The user password as a string. If not specified, it will default to an empty + The user password as a string. If not specified, it defaults to an empty string. type: string + default: "" active: description: | Whether the user account should be able to log in to the database system. diff --git a/site/content/3.12/develop/http-api/views/arangosearch-views.md b/site/content/3.12/develop/http-api/views/arangosearch-views.md index 9f6f0185bb..f585052364 100644 --- a/site/content/3.12/develop/http-api/views/arangosearch-views.md +++ b/site/content/3.12/develop/http-api/views/arangosearch-views.md @@ -46,8 +46,28 @@ paths: links: description: | Expects an object with the attribute keys being names of to be linked collections, - and the link properties as attribute values. See - [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) + and the link properties as attribute values. Example: + + ```json + { + "name": "arangosearch", + "links": { + "coll": { + "fields": { + "my_attribute": { + "fields": { + "my_sub_attribute": { + "analyzers": ["text_en"] + } + } + } + } + } + } + } + ``` + + See [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) for details. type: object primarySort: @@ -63,6 +83,7 @@ paths: (attribute path) and a sort direction: `[ { "field": "attr", "direction": "asc"}, … ]` type: array + default: [] items: type: object required: @@ -142,6 +163,7 @@ paths: Example: `["BM25(@doc) DESC", "TFIDF(@doc, true) DESC"]` type: array + default: [] items: type: string storedValues: @@ -180,6 +202,7 @@ paths: The `storedValues` option is not to be confused with the `storeValues` option, which allows to store meta data about attribute values in the View index. type: array + default: [] items: type: object required: @@ -1289,8 +1312,28 @@ paths: links: description: | Expects an object with the attribute keys being names of to be linked collections, - and the link properties as attribute values. See - [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) + and the link properties as attribute values. Example: + + ```json + { + "name": "arangosearch", + "links": { + "coll": { + "fields": { + "my_attribute": { + "fields": { + "my_sub_attribute": { + "analyzers": ["text_en"] + } + } + } + } + } + } + } + ``` + + See [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) for details. type: object cleanupIntervalStep: @@ -1781,8 +1824,28 @@ paths: links: description: | Expects an object with the attribute keys being names of to be linked collections, - and the link properties as attribute values. See - [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) + and the link properties as attribute values. Example: + + ```json + { + "name": "arangosearch", + "links": { + "coll": { + "fields": { + "my_attribute": { + "fields": { + "my_sub_attribute": { + "analyzers": ["text_en"] + } + } + } + } + } + } + } + ``` + + See [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) for details. type: object cleanupIntervalStep: diff --git a/site/content/3.12/develop/http-api/views/search-alias-views.md b/site/content/3.12/develop/http-api/views/search-alias-views.md index ed4015ac5d..9ac1ae3fdf 100644 --- a/site/content/3.12/develop/http-api/views/search-alias-views.md +++ b/site/content/3.12/develop/http-api/views/search-alias-views.md @@ -1035,6 +1035,18 @@ paths: The name of the View to rename. schema: type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + description: | + The new name for the View. + type: string responses: '200': description: | diff --git a/site/content/3.12/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md b/site/content/3.12/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md index ae5b4dc316..6feb707e61 100644 --- a/site/content/3.12/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md +++ b/site/content/3.12/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md @@ -76,7 +76,7 @@ _longitude_. The `geoJson` flag is implicitly _false_ in this mode. Alternatively you can specify only one field: -`collection.ensureIndex({ type: "geo", fields: [ "location" ], geoJson:false })` +`collection.ensureIndex({ type: "geo", fields: [ "location" ], geoJson: false })` It creates a geospatial index on all documents using `location` as the path to the coordinates. The value of the attribute has to be an array with at least two diff --git a/site/content/3.13/concepts/data-structure/collections.md b/site/content/3.13/concepts/data-structure/collections.md index 892903ab72..8f8323bbc9 100644 --- a/site/content/3.13/concepts/data-structure/collections.md +++ b/site/content/3.13/concepts/data-structure/collections.md @@ -119,29 +119,42 @@ ArangoDB as opaque strings when they store or use them locally. ## Key generators -ArangoDB allows using key generators for each collection. Key generators -have the purpose of auto-generating values for the `_key` attribute of a document -if none was specified by the user. By default, ArangoDB uses the traditional -key generator. The traditional key generator auto-generates key values that -are strings with ever-increasing numbers. The increment values it uses are -non-deterministic. - -Contrary, the auto-increment key generator auto-generates deterministic key -values. Both the start value and the increment value can be defined when the -collection is created. The default start value is `0` and the default increment -is `1`, meaning the key values it creates 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, ... - -The auto-increment values are increased and handed out on each document insert -attempt. Even if an insert fails, the auto-increment value is never rolled back. -That means there may exist gaps in the sequence of assigned auto-increment values -if inserts fails. +ArangoDB allows you to use different key generators for each collection. +Key generators have the purpose of auto-generating a value for the `_key` +attribute of a document if none was specified by the user. + +- **traditional** (default): The `traditional` key generator auto-generates + key values that are strings with ever-increasing numbers. The increment values + it uses are non-deterministic (e.g. `"137"`, `"140"`, `"141"`, `"145"`, ...). + +- **autoincrement**: The `autoincrement` key generator auto-generates + deterministic key values. You can define both the start value (`offset`) and + the `increment` value when creating the collection. The default start value is + `0` and the default increment is `1` (`"1"`, `"2"`, `"3"`, `"4"`, `"5"`, ...). + With an `increment` of `5` and `offset` of `2`: `"2"`, `"7"`, `"12"`, `"17"`, `"22"`, ... + + The auto-increment values are increased and handed out on each document insert + attempt. Even if an insert fails, the auto-increment value is never rolled back. + That means there may exist gaps in the sequence of assigned auto-increment values + if inserts fail. + + The `autoincrement` key generator is only supported for collections with a + single shard. + +- **padded**: The `padded` key generator generates keys of a fixed length + (16 bytes) in ascending lexicographical sort order. This is ideal for the + RocksDB storage engine, which slightly benefits keys that are inserted in + lexicographically ascending order. The sequence of generated keys is not + guaranteed to be gap-free (e.g. `"00000000005bb4d9"`, `"00000000005bb4e6"`, ...). + +- **uuid**: The `uuid` key generator generates universally unique 128 bit keys, + which are stored in hexadecimal human-readable format. The keys produced by + this key generator are not lexicographically sorted (e.g. + `"04648089-bdeb-4852-b570-f5280f68cf19"`, `"d0f1069c-e38b-4327-8e1e-6bdf7fd33865"`, ...). + +If you specify keys for some documents but rely on key generation for other +documents targeting the same collection, conflicts may occur. You can set +`allowUserKeys` to `false` to only permit auto-generated keys for a collection. ## Synchronous replication of collections diff --git a/site/content/3.13/develop/http-api/administration.md b/site/content/3.13/develop/http-api/administration.md index 2b0d91c640..9627e59411 100644 --- a/site/content/3.13/develop/http-api/administration.md +++ b/site/content/3.13/develop/http-api/administration.md @@ -46,6 +46,7 @@ paths: the `details` object may vary depending on platform and ArangoDB version. schema: type: boolean + default: false responses: '200': description: | @@ -1308,6 +1309,7 @@ paths: - Ongoing low priority requests schema: type: boolean + default: false responses: '200': description: | @@ -1436,13 +1438,13 @@ paths: changeLevel: description: | whether or not compacted data should be moved to the minimum possible level. - The default value is `false`. type: boolean + default: false compactBottomMostLevel: description: | Whether or not to compact the bottommost level of data. - The default value is `false`. type: boolean + default: false responses: '200': description: | @@ -1509,16 +1511,10 @@ paths: The call returns an object with the servers request information requestBody: content: - application/json: + application/octet-stream: schema: - type: object - required: - - body - properties: - body: - description: | - The request body can be of any type and is simply forwarded. - type: string + description: | + The request body can be of any type and is simply forwarded. parameters: - name: database-name in: path @@ -1701,8 +1697,9 @@ paths: directly, otherwise a string produced by JSON.stringify will be returned. - Note that this API endpoint will only be present if the server was - started with the option `--javascript.allow-admin-execute true`. + Note that this API endpoint is available if the server has been + started with the `--javascript.allow-admin-execute` startup options + enabled. The default value of this option is `false`, which disables the execution of user-defined code and disables this API endpoint entirely. @@ -1718,16 +1715,10 @@ paths: type: string requestBody: content: - application/json: + text/javascript: schema: - type: object - required: - - body - properties: - body: - description: | - The request body is the JavaScript code to be executed. - type: string + description: | + The request body is the JavaScript code to be executed. responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/analyzers.md b/site/content/3.13/develop/http-api/analyzers.md index ea3491b249..feb941feda 100644 --- a/site/content/3.13/develop/http-api/analyzers.md +++ b/site/content/3.13/develop/http-api/analyzers.md @@ -54,8 +54,8 @@ paths: features: description: | The set of features to set on the Analyzer generated fields. - The default value is an empty array. type: array + default: [] uniqueItems: true items: type: string @@ -249,9 +249,9 @@ paths: required: false description: | The Analyzer configuration should be removed even if it is in-use. - The default value is `false`. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/cluster.md b/site/content/3.13/develop/http-api/cluster.md index 9089779739..d40ac42208 100644 --- a/site/content/3.13/develop/http-api/cluster.md +++ b/site/content/3.13/develop/http-api/cluster.md @@ -380,6 +380,7 @@ paths: You can send another request when the DB-Server is already in maintenance mode to extend the timeout. type: integer + default: 3600 responses: '200': description: | @@ -808,37 +809,44 @@ paths: type: number maximumNumberOfMoves: description: | - Maximum number of moves to be computed. (Default: `1000`) - type: number + Maximum number of moves to be computed. + type: integer + default: 1000 leaderChanges: description: | - Allow leader changes without moving data. (Default: `true`) + Allow leader changes without moving data. type: boolean + default: true moveLeaders: description: | - Allow moving leaders. (Default: `false`) + Allow moving leaders. type: boolean + default: false moveFollowers: description: | - Allow moving followers. (Default: `false`) + Allow moving followers. type: boolean + default: false excludeSystemCollections: description: | - Ignore system collections in the rebalance plan. (Default: `false`) + Ignore system collections in the rebalance plan. type: boolean + default: false piFactor: description: | - A weighting factor that should remain untouched. (Default: `256e6`) + A weighting factor that should remain untouched. If a collection has more shards than there are DB-Servers, there can be a subtle form of leader imbalance. Some DB-Servers may be responsible for more shards as leader than others. The `piFactor` adjusts how much weight such imbalances get in the overall imbalance score. - type: number + type: integer + default: 256e6 databasesExcluded: description: | - A list of database names to exclude from the analysis. (Default: `[]`) + A list of database names to exclude from the analysis. type: array + default: [] items: type: string responses: @@ -1218,37 +1226,44 @@ paths: type: number maximumNumberOfMoves: description: | - Maximum number of moves to be computed. (Default: `1000`) - type: number + Maximum number of moves to be computed. + type: integer + default: 1000 leaderChanges: description: | - Allow leader changes without moving data. (Default: `true`) + Allow leader changes without moving data. type: boolean + default: true moveLeaders: description: | - Allow moving leaders. (Default: `false`) + Allow moving leaders. type: boolean + default: false moveFollowers: description: | - Allow moving followers. (Default: `false`) + Allow moving followers. type: boolean + default: false excludeSystemCollections: description: | - Ignore system collections in the rebalance plan. (Default: `false`) + Ignore system collections in the rebalance plan. type: boolean + default: false piFactor: description: | - A weighting factor that should remain untouched. (Default: `256e6`) + A weighting factor that should remain untouched. If a collection has more shards than there are DB-Servers, there can be a subtle form of leader imbalance. Some DB-Servers may be responsible for more shards as leader than others. The `piFactor` adjusts how much weight such imbalances get in the overall imbalance score. - type: number + type: integer + default: 256e6 databasesExcluded: description: | - A list of database names to exclude from the analysis. (Default: `[]`) + A list of database names to exclude from the analysis. type: array + default: [] items: type: string responses: diff --git a/site/content/3.13/develop/http-api/collections.md b/site/content/3.13/develop/http-api/collections.md index 6c1658a9c8..bb1a7ea265 100644 --- a/site/content/3.13/develop/http-api/collections.md +++ b/site/content/3.13/develop/http-api/collections.md @@ -51,6 +51,7 @@ paths: Whether system collections should be excluded from the result. schema: type: boolean + default: false responses: '200': description: | @@ -1636,15 +1637,10 @@ paths: content: application/json: schema: + description: | + The request body must be a JSON object with at least the shard key + attributes set to some values, but it may also be a full document. type: object - required: - - document - properties: - document: - description: | - The request body must be a JSON object with at least the shard key - attributes set to some values, but it may also be a full document. - type: object responses: '200': description: | @@ -1800,11 +1796,12 @@ paths: get: operationId: getCollectionShards description: | - Returns a JSON array with the shard IDs of the collection. - - If the `details` parameter is set to `true`, it returns a JSON object with the - shard IDs as object attribute keys, and the responsible servers for each shard mapped to them. - In the detailed response, the leader shards come first in the arrays. + The response contains a list of the collection's shard IDs. + + If the `details` parameter is set to `true`, it returns an object instead + of a list, with the shard IDs as object attribute keys, and an array with + the responsible servers for each shard mapped to them as attribute values. + The first element of each array is the leader shard. {{}} This method is only available in cluster deployments on Coordinators. @@ -1836,8 +1833,317 @@ paths: responses: '200': description: | - Returns the collection's shards. - # TODO: polymorphic structural description? + All collection properties but additionally the `shards` of the collection. + content: + application/json: + schema: + type: object + required: + - shards + - error + - code + - name + - type + - status + - statusString + - isSystem + - id + - globallyUniqueId + - waitForSync + - keyOptions + - schema + - computedValues + - cacheEnabled + - syncByRevision + # Purposefully undocumented: + # internalValidatorType (internal) + # isSmartChild (internal) + # minReplicationFactor (now writeConcern) + # shadowCollections (internal) + # usesRevisionsAsDocumentIds (internal) + # status (legacy) + # statusString (legacy) + properties: + shards: + description: | + The type and value depend on the setting of the `details` parameter: + - `false`: An array of the collection shard IDs. + - `true`: An object where the keys are shard IDs and the + values are arrays with the responsible DB-Server names + (shard leader first). + # TODO: polymorphic structural description? Complex to render + #type: [array, object] + #items: + # type: string + # pattern: "^s\\d+$" + #patternProperties: + # "^s\\d+$": + # type: array + # items: + # type: string + # --- or --- + #oneOf: + # - type: array + # items: + # type: string + # pattern: "^s\\d+$" + # - type: object + # patternProperties: + # "^s\\d+$": + # type: array + # items: + # type: string + error: + description: | + A flag indicating that no error occurred. + type: boolean + example: false + code: + description: | + The HTTP response status code. + type: integer + example: 200 + waitForSync: + description: | + If `true`, creating, changing, or removing + documents waits until the data has been synchronized to disk. + type: boolean + schema: + description: | + The configuration of the collection-level schema validation for documents. + type: object + required: + - rule + - level + - message + - type + properties: + rule: + description: | + A [JSON Schema](https://json-schema.org/specification-links#draft-4) + object (draft-4, without remote schemas). + + See [Document Schema Validation](../../concepts/data-structure/documents/schema-validation.md) + for details. + type: object + level: + description: | + The level controls when the validation is triggered: + - `"none"`: The rule is inactive and validation thus turned off. + - `"new"`: Only newly inserted documents are validated. + - `"moderate"`: New and modified documents must pass validation, + except for modified documents where the OLD value did not pass + validation already. This level is useful if you have documents + which do not match your target structure, but you want to stop + the insertion of more invalid documents and prohibit that valid + documents are changed to invalid documents. + - `"strict"`: All new and modified document must strictly pass + validation. No exceptions are made. + type: string + enum: [none, new, moderate, strict] + default: strict + message: + description: | + The error message to raise if the schema validation fails + for a document. + type: string + type: + description: | + The schema validation type. Only JSON Schema is supported. + type: string + enum: [json] + computedValues: + description: | + A list of objects, each representing a computed value. + type: array + items: + type: object + required: + - name + - expression + - overwrite + properties: + name: + description: | + The name of the target attribute. + type: string + expression: + description: | + An AQL `RETURN` operation with an expression that computes the desired value. + type: string + overwrite: + description: | + Whether the computed value takes precedence over a user-provided or + existing attribute. + type: boolean + computeOn: + description: | + An array of strings that defines on which write operations the value is + computed. + type: array + uniqueItems: true + items: + type: string + enum: [insert, update, replace] + example: ["insert", "update", "replace"] + keepNull: + description: | + Whether the target attribute is set if the expression evaluates to `null`. + type: boolean + failOnWarning: + description: | + Whether the write operation fails if the expression produces a warning. + type: boolean + keyOptions: + description: | + An object which contains key generation options. + type: object + required: + - type + - allowUserKeys + properties: + type: + description: | + Specifies the type of the key generator. + type: string + enum: [traditional, autoincrement, uuid, padded] + allowUserKeys: + description: | + If set to `true`, then you are allowed to supply + own key values in the `_key` attribute of a document. If set to + `false`, then the key generator is solely responsible for + generating keys and an error is raised if you supply own key values in the + `_key` attribute of documents. + + {{}} + You should not use both user-specified and automatically generated document keys + in the same collection in cluster deployments for collections with more than a + single shard. Mixing the two can lead to conflicts because Coordinators that + auto-generate keys in this case are not aware of all keys which are already used. + {{}} + type: boolean + increment: + description: | + The increment value for the `autoincrement` key generator. + Not used by other key generator types. + type: integer + offset: + description: | + The initial offset value for the `autoincrement` key generator. + Not used by other key generator types. + type: integer + lastValue: + description: | + The offset value of the `autoincrement` or `padded` key generator. + This is an internal property for restoring dumps properly. + type: integer + cacheEnabled: + description: | + Whether the in-memory hash cache for documents is enabled for this + collection. + type: boolean + numberOfShards: + description: | + The number of shards of the collection. _(cluster only)_ + type: integer + shardKeys: + description: | + Contains the names of document attributes that are used to + determine the target shard for documents. _(cluster only)_ + type: array + items: + type: string + replicationFactor: + description: | + Contains how many copies of each shard are kept on different DB-Servers. + It is an integer number in the range of 1-10 or the string `"satellite"` + for SatelliteCollections. _(cluster only)_ + type: integer + writeConcern: + description: | + Determines how many copies of each shard are required to be + in-sync on the different DB-Servers. If there are less than these many copies + in the cluster, a shard refuses to write. Writes to shards with enough + up-to-date copies succeed at the same time, however. The value of + `writeConcern` cannot be greater than `replicationFactor`. + + If `distributeShardsLike` is set, the default `writeConcern` + is that of the prototype collection. + For SatelliteCollections, the `writeConcern` is automatically controlled to + equal the number of DB-Servers and has a value of `0`. + Otherwise, the default value is controlled by the current database's + default `writeConcern`, which uses the `--cluster.write-concern` + startup option as default, which defaults to `1`. _(cluster only)_ + type: integer + shardingStrategy: + description: | + The sharding strategy selected for the collection. _(cluster only)_ + type: string + enum: + - community-compat + - enterprise-compat + - enterprise-smart-edge-compat + - hash + - enterprise-hash-smart-edge + - enterprise-hex-smart-vertex + distributeShardsLike: + description: | + The name of another collection. This collection uses the `replicationFactor`, + `numberOfShards` and `shardingStrategy` properties of the other collection and + the shards of this collection are distributed in the same way as the shards of + the other collection. + type: string + isSmart: + description: | + Whether the collection is used in a SmartGraph or EnterpriseGraph. + This is an internal property. _(cluster only)_ + type: boolean + isDisjoint: + description: | + Whether the SmartGraph or EnterpriseGraph this collection belongs to is disjoint. + This is an internal property. _(cluster only)_ + type: boolean + smartGraphAttribute: + description: | + The attribute that is used for sharding: vertices with the same value of + this attribute are placed in the same shard. All vertices are required to + have this attribute set and it has to be a string. Edges derive the + attribute from their connected vertices. _(cluster only)_ + type: string + smartJoinAttribute: + description: | + Determines an attribute of the collection that must contain the shard key value + of the referred-to SmartJoin collection. _(cluster only)_ + type: string + name: + description: | + The name of this collection. + type: string + id: + description: | + A unique identifier of the collection (deprecated). + type: string + type: + description: | + The type of the collection: + - `0`: "unknown" + - `2`: regular document collection + - `3`: edge collection + type: integer + isSystem: + description: | + Whether the collection is a system collection. Collection names that starts with + an underscore are usually system collections. + type: boolean + syncByRevision: + description: | + Whether the newer revision-based replication protocol is + enabled for this collection. This is an internal property. + type: boolean + globallyUniqueId: + description: | + A unique identifier of the collection. This is an internal property. + type: string '400': description: | The `collection-name` parameter is missing. @@ -1951,7 +2257,8 @@ db._create(cn, { numberOfShards: 3 }); var response = logCurlRequest('GET', "/_api/collection/" + cn + "/shards"); assert(response.code === 200); -logRawResponse(response); +assert(response.parsedBody.hasOwnProperty("shards")); +logJsonResponse(response); db._drop(cn); ``` @@ -1969,7 +2276,8 @@ db._create(cn, { numberOfShards: 3 }); var response = logCurlRequest('GET', "/_api/collection/" + cn + "/shards?details=true"); assert(response.code === 200); -logRawResponse(response); +assert(response.parsedBody.hasOwnProperty("shards")); +logJsonResponse(response); db._drop(cn); ``` @@ -2008,7 +2316,7 @@ paths: responses: '200': description: | - All collection properties but additionally the collection `revision`. + All collection properties but additionally the `revision` of the collection. content: application/json: schema: @@ -2436,16 +2744,18 @@ paths: in: query required: false description: | - Whether or not to include document revision ids in the checksum calculation. + Whether to include document revision ids in the checksum calculation. schema: type: boolean + default: false - name: withData in: query required: false description: | - Whether or not to include document body data in the checksum calculation. + Whether to include document body data in the checksum calculation. schema: type: boolean + default: false responses: '200': description: | @@ -2800,7 +3110,7 @@ paths: - The `autoincrement` key generator generates numerical keys in ascending order, the initial offset and the spacing can be configured (**note**: `autoincrement` - is currently only supported for non-sharded collections). + is only supported for non-sharded collections). The sequence of generated keys is not guaranteed to be gap-free, because a new key will be generated on every document insert attempt, not just for successful inserts. @@ -2846,11 +3156,13 @@ paths: The increment value for the `autoincrement` key generator. Not allowed for other key generator types. type: integer + default: 1 offset: description: | The initial offset value for the `autoincrement` key generator. Not allowed for other key generator types. type: integer + default: 0 type: description: | The type of the collection to create. @@ -2903,8 +3215,9 @@ paths: If a server fails, this is detected automatically and one of the servers holding copies take over, usually without an error being reported. + + Default: The `replicationFactor` defined by the database. type: integer - default: 1 writeConcern: description: | Determines how many copies of each shard are required to be @@ -2913,7 +3226,7 @@ paths: up-to-date copies succeed at the same time, however. The value of `writeConcern` cannot be greater than `replicationFactor`. - If `distributeShardsLike` is set, the default `writeConcern` + Default: If `distributeShardsLike` is set, the default `writeConcern` is that of the prototype collection. For SatelliteCollections, the `writeConcern` is automatically controlled to equal the number of DB-Servers and has a value of `0`. @@ -3000,7 +3313,7 @@ paths: This feature requires the `distributeShardsLike` attribute of the collection to be set to the name of another collection. It also requires the `shardKeys` attribute of the - collection to be set to a single shard key attribute, with an additional ':' + collection to be set to a single shard key attribute, with an additional `:` at the end. A further restriction is that whenever documents are stored or updated in the collection, the value stored in the `smartJoinAttribute` must be a string. @@ -3415,10 +3728,11 @@ paths: in: query required: false description: | - Whether or not the collection to drop is a system collection. This parameter + Whether the collection to drop is a system collection. This parameter must be set to `true` in order to drop a system collection. schema: type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/documents.md b/site/content/3.13/develop/http-api/documents.md index 8fb1a797b1..2a2083475f 100644 --- a/site/content/3.13/develop/http-api/documents.md +++ b/site/content/3.13/develop/http-api/documents.md @@ -111,7 +111,7 @@ paths: in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one + 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. schema: @@ -274,7 +274,7 @@ paths: in: header required: false description: | - If the "If-None-Match" header is given, then it must contain exactly one + If the `If-None-Match` header is given, then it must contain exactly one ETag. If the current document revision is not equal 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. @@ -431,8 +431,8 @@ paths: in: query required: false description: | - Additionally return the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -440,8 +440,9 @@ paths: in: query required: false description: | - Additionally return the complete old document under the attribute `old` - in the result. Only available if the overwrite option is used. + Whether to additionally include the complete previous document under the + `old` attribute in the result. Only available if the `overwriteMode` + parameter is to `"update"` or `"replace"`, or if `overwrite` is set to `true`. schema: type: boolean default: false @@ -906,8 +907,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -915,8 +916,8 @@ paths: in: query required: false description: | - Return additionally the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -1270,8 +1271,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -1279,8 +1280,8 @@ paths: in: query required: false description: | - Return additionally the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -1552,8 +1553,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -1783,9 +1784,9 @@ paths: software does not support payload bodies in `GET` requests. {{}} - Returns the documents identified by their `_key` in the body objects. + Returns the documents identified by their `_key` attribute. The body of the request _must_ contain a JSON array of either - strings (the `_key` values to lookup) or search documents. + strings (the `_key` values to look up) or search documents. A search document _must_ contain at least a value for the `_key` field. A value for `_rev` _may_ be specified to verify whether the document @@ -1862,8 +1863,13 @@ paths: description: | An array of documents to retrieve. type: array - items: - type: object + #items: + # type: [string, object] + #required: + # - _key + #properties: + # _key: + # type: string responses: '200': description: | @@ -1992,8 +1998,8 @@ paths: in: query required: false description: | - Additionally return the complete new document under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -2001,8 +2007,9 @@ paths: in: query required: false description: | - Additionally return the complete old document under the attribute `old` - in the result. Only available if the overwrite option is used. + Whether to additionally include the complete previous document under the + `old` attribute in the result. Only available if the `overwriteMode` + parameter is to `"update"` or `"replace"`, or if `overwrite` is set to `true`. schema: type: boolean default: false @@ -2358,8 +2365,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - documents under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -2367,8 +2374,8 @@ paths: in: query required: false description: | - Return additionally the complete new documents under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -2623,8 +2630,8 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - documents under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -2632,8 +2639,8 @@ paths: in: query required: false description: | - Return additionally the complete new documents under the attribute `new` - in the result. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -2827,10 +2834,11 @@ paths: in: query required: false description: | - Return additionally the complete previous revision of the changed - document under the attribute `old` in the result. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2843,6 +2851,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: ignoreRevs in: query required: false diff --git a/site/content/3.13/develop/http-api/foxx.md b/site/content/3.13/develop/http-api/foxx.md index 51e2115551..a8b1e29bf4 100644 --- a/site/content/3.13/develop/http-api/foxx.md +++ b/site/content/3.13/develop/http-api/foxx.md @@ -48,6 +48,7 @@ paths: Whether or not system services should be excluded from the result. schema: type: boolean + default: false responses: '200': description: | @@ -165,6 +166,7 @@ paths: Set to `true` to enable development mode. schema: type: boolean + default: false - name: setup in: query required: false @@ -172,6 +174,7 @@ paths: Set to `false` to not run the service's setup script. schema: type: boolean + default: true - name: legacy in: query required: false @@ -179,6 +182,7 @@ paths: Set to `true` to install the service in 2.8 legacy compatibility mode. schema: type: boolean + default: false responses: '201': description: | @@ -221,6 +225,7 @@ paths: Set to `false` to not run the service's teardown script. schema: type: boolean + default: true responses: '204': description: | @@ -294,6 +299,7 @@ paths: Set to `false` to not run the old service's teardown script. schema: type: boolean + default: true - name: setup in: query required: false @@ -301,6 +307,7 @@ paths: Set to `false` to not run the new service's setup script. schema: type: boolean + default: true - name: legacy in: query required: false @@ -308,6 +315,7 @@ paths: Set to `true` to install the new service in 2.8 legacy compatibility mode. schema: type: boolean + default: false - name: force in: query required: false @@ -315,6 +323,7 @@ paths: Set to `true` to force service install even if no service is installed under given mount. schema: type: boolean + default: false responses: '200': description: | @@ -388,6 +397,7 @@ paths: Set to `true` to run the old service's teardown script. schema: type: boolean + default: false - name: setup in: query required: false @@ -395,6 +405,7 @@ paths: Set to `false` to not run the new service's setup script. schema: type: boolean + default: true - name: legacy in: query required: false @@ -402,6 +413,7 @@ paths: Set to `true` to install the new service in 2.8 legacy compatibility mode. schema: type: boolean + default: false - name: force in: query required: false @@ -409,6 +421,7 @@ paths: Set to `true` to force service install even if no service is installed under given mount. schema: type: boolean + default: false responses: '200': description: | @@ -758,12 +771,9 @@ paths: content: application/json: schema: - type: object - properties: - data: - description: | - An arbitrary JSON value that will be parsed and passed to the - script as its first argument. + description: | + An arbitrary JSON value that will be parsed and passed to the + script as its first argument. responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/graphs/named-graphs.md b/site/content/3.13/develop/http-api/graphs/named-graphs.md index 52ba90ad4f..85d2ad9ca0 100644 --- a/site/content/3.13/develop/http-api/graphs/named-graphs.md +++ b/site/content/3.13/develop/http-api/graphs/named-graphs.md @@ -149,6 +149,8 @@ paths: description: | The replication factor used for every new collection in the graph. For SatelliteGraphs, it is the string `"satellite"`. + + Default: The `replicationFactor` defined by the database. type: integer writeConcern: description: | @@ -293,7 +295,7 @@ paths: default: false options: description: | - a JSON object to define options for creating collections within this graph. + Options for creating collections within this graph. It can contain the following attributes: type: object properties: @@ -319,11 +321,14 @@ paths: The number of shards that is used for every collection within this graph. Cannot be modified later. type: integer + default: 1 replicationFactor: description: | The replication factor used when initially creating collections for this graph. Can be set to `"satellite"` to create a SatelliteGraph, which then ignores `numberOfShards`, `minReplicationFactor`, and `writeConcern`. + + Default: The `replicationFactor` defined by the database. type: integer writeConcern: description: | @@ -336,9 +341,6 @@ paths: For SatelliteGraphs, the `writeConcern` is automatically controlled to equal the number of DB-Servers and the attribute is not available. _(cluster only)_ type: integer - required: - - numberOfShards - - replicationFactor responses: '201': description: | @@ -1874,6 +1876,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false responses: '200': description: | @@ -3730,8 +3733,8 @@ paths: in: query required: false description: | - Define if the response should contain the complete - new version of the document. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -4378,8 +4381,8 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -4387,8 +4390,8 @@ paths: in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -4823,8 +4826,8 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -4832,8 +4835,8 @@ paths: in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -5258,8 +5261,8 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean default: false @@ -5584,8 +5587,8 @@ paths: in: query required: false description: | - Define if the response should contain the complete - new version of the document. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -6331,20 +6334,22 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: returnNew in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -6835,20 +6840,22 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: returnNew in: query required: false description: | - Define if a presentation of the new document should - be returned within the response object. + Whether to additionally include the complete new document under the + `new` attribute in the result. schema: type: boolean default: false @@ -7350,10 +7357,11 @@ paths: in: query required: false description: | - Define if a presentation of the deleted document should - be returned within the response object. + Whether to additionally include the complete previous document under the + `old` attribute in the result. schema: type: boolean + default: false - name: If-Match in: header required: false diff --git a/site/content/3.13/develop/http-api/hot-backups.md b/site/content/3.13/develop/http-api/hot-backups.md index b986c32ced..a585b2244c 100644 --- a/site/content/3.13/develop/http-api/hot-backups.md +++ b/site/content/3.13/develop/http-api/hot-backups.md @@ -61,8 +61,9 @@ paths: timeout: description: | The time in seconds that the operation tries to get a consistent - snapshot. The default is 120 seconds. - type: number + snapshot. + type: integer + default: 120 allowInconsistent: description: | If this flag is set to `true` and no global transaction lock can be @@ -70,6 +71,7 @@ paths: is taken. The default for this flag is `false` and in this case a timeout results in an HTTP 408 error. type: boolean + default: false force: description: | If this flag is set to `true` and no global transaction lock can be acquired @@ -84,6 +86,7 @@ paths: `allowInconsistent` and `force` are set to `true`, then the latter takes precedence and transactions are aborted. This is only available in the cluster. type: boolean + default: false responses: '201': description: | @@ -393,7 +396,7 @@ paths: description: | Configuration of remote repository. This is required when an upload operation is scheduled. In this case leave out the `uploadId` - attribute. See the description of the _arangobackup_ program in the manual + attribute. See [Rclone Configuration](../../components/tools/arangobackup/examples/#rclone-configuration) for a description of the `config` object. type: object uploadId: @@ -407,6 +410,7 @@ paths: Set this to `true` if a running upload operation should be aborted. In this case, the only other body parameter which is needed is `uploadId`. type: boolean + default: false responses: '200': description: | @@ -523,6 +527,9 @@ paths: application/json: schema: type: object + required: + - remoteRepository + - config properties: id: description: | @@ -545,7 +552,7 @@ paths: description: | Configuration of remote repository. This is required when a download operation is scheduled. In this case leave out the `downloadId` - attribute. See the description of the _arangobackup_ program in the manual + attribute. See [Rclone Configuration](../../components/tools/arangobackup/examples/#rclone-configuration) for a description of the `config` object. type: object downloadId: @@ -559,9 +566,7 @@ paths: Set this to `true` if a running download operation should be aborted. In this case, the only other body parameter which is needed is `downloadId`. type: boolean - required: - - remoteRepository - - config + default: false responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/indexes/_index.md b/site/content/3.13/develop/http-api/indexes/_index.md index 479dfd2604..f759f7e174 100644 --- a/site/content/3.13/develop/http-api/indexes/_index.md +++ b/site/content/3.13/develop/http-api/indexes/_index.md @@ -60,6 +60,7 @@ paths: Whether to include figures and estimates in the result. schema: type: boolean + default: false - name: withHidden in: query required: false @@ -69,6 +70,7 @@ paths: background are hidden. schema: type: boolean + default: false responses: '200': description: | @@ -270,14 +272,9 @@ paths: content: application/json: schema: + description: | + The options for the index. The available attributes depend on the index type. type: object - required: - - index-details - properties: - index-details: - description: | - The options for the index. - type: object responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/indexes/fulltext.md b/site/content/3.13/develop/http-api/indexes/fulltext.md index 687ca29230..318f73ba75 100644 --- a/site/content/3.13/develop/http-api/indexes/fulltext.md +++ b/site/content/3.13/develop/http-api/indexes/fulltext.md @@ -67,10 +67,11 @@ paths: type: string minLength: description: | - 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. + Minimum character length of words to index. The default is + low, thus it is recommended to set this value explicitly + when creating the index. type: integer + default: 2 inBackground: description: | Set this option to `true` to keep the collection/shards available for diff --git a/site/content/3.13/develop/http-api/indexes/geo-spatial.md b/site/content/3.13/develop/http-api/indexes/geo-spatial.md index ad51599a94..4d1eac25ed 100644 --- a/site/content/3.13/develop/http-api/indexes/geo-spatial.md +++ b/site/content/3.13/develop/http-api/indexes/geo-spatial.md @@ -75,15 +75,17 @@ paths: type: array minItems: 1 maxItems: 2 + uniqueItems: true items: type: string geoJson: description: | - If a geo-spatial index on a `location` is constructed - and `geoJson` is `true`, then the order within the array is longitude - followed by latitude. This corresponds to the format described in + If you create a geo-spatial index over a single attribute and `geoJson` + is `true`, then the coordinate order within the attribute's array is + longitude followed by latitude. This corresponds to the format described in type: boolean + default: false legacyPolygons: description: | If `geoJson` is set to `true`, then this option controls how GeoJSON Polygons diff --git a/site/content/3.13/develop/http-api/indexes/inverted.md b/site/content/3.13/develop/http-api/indexes/inverted.md index fb9f1164ba..2e050c3320 100644 --- a/site/content/3.13/develop/http-api/indexes/inverted.md +++ b/site/content/3.13/develop/http-api/indexes/inverted.md @@ -59,6 +59,7 @@ paths: attribute path in the `name` property), or a mix of both. type: array minItems: 1 + uniqueItems: true items: type: object required: @@ -246,9 +247,8 @@ paths: array (`[*]`), then the elements are indexed separately. Otherwise, the array is indexed as a whole, but only `geopoint` and `aql` Analyzers accept array inputs. You cannot use an array expansion if `searchField` is enabled. - - Default: `false` type: boolean + default: false cache: description: | Enable this option to always cache the field normalization values in memory @@ -264,13 +264,12 @@ paths: fields that are indexed with Geo Analyzers in memory for all fields by default. This can improve the performance of geo-spatial queries. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false storedValues: description: | The optional `storedValues` attribute can contain an array of objects with paths @@ -308,6 +307,7 @@ paths: description: | A list of attribute paths. The `.` character denotes sub-attributes. type: array + #uniqueItems: true # Duplicate values are silently ignored items: type: string compression: @@ -325,13 +325,12 @@ paths: memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false primarySort: description: | You can define a primary sort order to enable an AQL optimization. If a query @@ -378,13 +377,12 @@ paths: Otherwise, these values are memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false primaryKeyCache: description: | Enable this option to always cache the primary key column in memory. This can @@ -392,13 +390,12 @@ paths: values are memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory. - Default: `false` - See the `--arangosearch.columns-cache-limit` startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the `--arangosearch.columns-cache-only-leader` startup option (introduced in v3.10.6). type: boolean + default: false optimizeTopK: description: | This option only applies if you use the inverted index in a `search-alias` Views. @@ -418,18 +415,16 @@ paths: You can define up to 64 expressions per View. Example: `["BM25(@doc) DESC", "TFIDF(@doc, true) DESC"]` - - Default: `[]` type: array + default: [] items: type: string analyzer: description: | The name of an Analyzer to use by default. This Analyzer is applied to the values of the indexed fields for which you don't define Analyzers explicitly. - - Default: `identity` type: string + default: identity features: description: | A list of Analyzer features. You can set this option to overwrite what features @@ -449,13 +444,12 @@ paths: sub-attributes that are configured in the `fields` array (and their sub-attributes). The `analyzer` and `features` properties apply to the sub-attributes. - Default: `false` - {{}} Using `includeAllFields` for a lot of attributes in combination with complex Analyzers may significantly slow down the indexing process. {{}} type: boolean + default: false trackListPositions: description: | This option only applies if you use the inverted index in a `search-alias` Views, @@ -469,10 +463,12 @@ paths: You don't specify an array element in queries, e.g. `doc.attr == "valueY"`, and all elements are searched for a match. type: boolean + default: false parallelism: description: | - The number of threads to use for indexing the fields. Default: `2` + The number of threads to use for indexing the fields. type: integer + default: 2 inBackground: description: | Set this option to `true` to keep the collection/shards available for @@ -483,7 +479,7 @@ paths: cleanupIntervalStep: description: | Wait at least this many commits between removing unused files in the - ArangoSearch data directory (default: 2, to disable use: 0). + ArangoSearch data directory (set to `0` to disable). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value causes a lot of disk space to be wasted. @@ -499,11 +495,11 @@ paths: However, the files for the released states/snapshots are left on disk, and only removed by "cleanup" operation. type: integer + default: 2 commitIntervalMsec: description: | Wait at least this many milliseconds between committing inverted index data store - changes and making documents visible to queries (default: 1000, to disable - use: 0). + changes and making documents visible to queries (set to `0` to disable). For the case where there are a lot of inserts/updates, a higher value causes the index not to account for them and memory usage continues to grow until the commit. A lower value impacts performance, including the case where there are no or only a @@ -522,11 +518,12 @@ paths: subsequent ArangoDB transactions, in-progress ArangoDB transactions will still continue to return a repeatable-read state. type: integer + default: 1000 consolidationIntervalMsec: description: | Wait at least this many milliseconds between applying `consolidationPolicy` to consolidate the inverted index data store and possibly release space on the filesystem - (default: 1000, to disable use: 0). + (set to `0` to disable). For the case where there are a lot of data modification operations, a higher value could potentially have the data store consume more space and file handles. For the case where there are a few data modification operations, a lower value @@ -540,10 +537,10 @@ paths: compaction operations are governed by `consolidationIntervalMsec` and the candidates for compaction are selected via `consolidationPolicy`. type: integer + default: 1000 consolidationPolicy: description: | - The consolidation policy to apply for selecting which segments should be merged - (default: {}). + The consolidation policy to apply for selecting which segments should be merged. _Background:_ With each ArangoDB transaction that inserts documents, one or more @@ -564,53 +561,60 @@ paths: upon several possible configurable formulas as defined by their types. The supported types are: - - `"tier"` (default): consolidate based on segment byte size and live + - `"tier"`: consolidate based on segment byte size and live document count as dictated by the customization attributes. type: string + default: tier segmentsBytesFloor: description: | Defines the value (in bytes) to treat all smaller segments as equal for - consolidation selection. Default: `2097152` + consolidation selection. type: integer + default: 2097152 segmentsBytesMax: description: | The maximum allowed size of all consolidated segments in bytes. - Default: `5368709120` type: integer + default: 5368709120 segmentsMax: description: | The maximum number of segments that are evaluated as candidates for - consolidation. Default: `10` + consolidation. type: integer + default: 10 segmentsMin: description: | The minimum number of segments that are evaluated as candidates for - consolidation. Default: `1` + consolidation. type: integer + default: 1 minScore: description: | - Filter out consolidation candidates with a score less than this. Default: `0` + Filter out consolidation candidates with a score less than this. type: integer + default: 0 writebufferIdle: description: | Maximum number of writers (segments) cached in the pool - (default: 64, use 0 to disable) + (set to `0` to disable). type: integer + default: 64 writebufferActive: description: | Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers - (segments) finish (default: 0, use 0 to disable) + (segments) finish (set to `0` to disable). type: integer + default: 0 writebufferSizeMax: description: | Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. `0` value turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (ArangoDB server startup option). `0` value should be used carefully due to - high potential memory consumption - (default: 33554432, use 0 to disable) + high potential memory consumption (set to `0 `to disable). type: integer + default: 33554432 responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/indexes/multi-dimensional.md b/site/content/3.13/develop/http-api/indexes/multi-dimensional.md index 53aba9abe6..e38f031495 100644 --- a/site/content/3.13/develop/http-api/indexes/multi-dimensional.md +++ b/site/content/3.13/develop/http-api/indexes/multi-dimensional.md @@ -57,6 +57,7 @@ paths: An array of attribute names used for each dimension. Array expansions are not allowed. type: array minItems: 1 + uniqueItems: true items: type: string fieldValueTypes: @@ -69,6 +70,7 @@ paths: An array of attribute names used as search prefix. Array expansions are not allowed. type: array + uniqueItems: true items: type: string storedValues: @@ -99,6 +101,7 @@ paths: The maximum number of attributes in `storedValues` is 32. type: array + uniqueItems: true items: type: string unique: diff --git a/site/content/3.13/develop/http-api/indexes/persistent.md b/site/content/3.13/develop/http-api/indexes/persistent.md index 99be09a69f..7017836a3b 100644 --- a/site/content/3.13/develop/http-api/indexes/persistent.md +++ b/site/content/3.13/develop/http-api/indexes/persistent.md @@ -82,6 +82,7 @@ paths: You can expand one array attribute with `[*]`. type: array minItems: 1 + uniqueItems: true items: type: string storedValues: @@ -105,23 +106,27 @@ paths: type: string unique: description: | - If `true`, then create a unique index. Defaults to `false`. + Whether to create the index with a uniqueness constraint. In unique indexes, only the attributes in `fields` are checked for uniqueness, but the attributes in `storedValues` are not checked for their uniqueness. type: boolean + default: false sparse: description: | - If `true`, then create a sparse index. Defaults to `false`. + Whether create a sparse index that excludes documents with at least + one of the `fields` missing or set to `null`. type: boolean + default: false deduplicate: description: | The attribute controls whether inserting duplicate index values - from the same document into a unique array index will lead to a unique constraint - error or not. The default value is `true`, so only a single instance of each - non-unique index value will be inserted into the index per document. Trying to - insert a value into the index that already exists in the index will always fail, + from the same document into a unique array index lead to a unique constraint + error or not. Only a single instance of each non-unique index value + is inserted into the index per document by default. Trying to + insert a value into the index that already exists in the index always fails, regardless of the value of this attribute. type: boolean + default: true estimates: description: | This attribute controls whether index selectivity estimates are maintained for the @@ -133,9 +138,9 @@ paths: competing indexes in AQL queries when there are multiple candidate indexes to choose from. - The `estimates` attribute is optional and defaults to `true` if not set. - It has no effect on indexes other than `persistent`, `mdi`, and `mdi-prefixed`. + The option has no effect on indexes other than `persistent`, `mdi`, and `mdi-prefixed`. type: boolean + default: true cacheEnabled: description: | This attribute controls whether an extra in-memory hash cache is @@ -157,6 +162,7 @@ paths: `cacheEnabled` defaults to `false` and should only be used for indexes that are known to benefit from an extra layer of caching. type: boolean + default: false inBackground: description: | Set this option to `true` to keep the collection/shards available for diff --git a/site/content/3.13/develop/http-api/indexes/vector.md b/site/content/3.13/develop/http-api/indexes/vector.md index a98bd79166..98b973d3d6 100644 --- a/site/content/3.13/develop/http-api/indexes/vector.md +++ b/site/content/3.13/develop/http-api/indexes/vector.md @@ -67,8 +67,9 @@ paths: type: string parallelism: description: | - The number of threads to use for indexing. Default: `2` + The number of threads to use for indexing. type: integer + default: 2 inBackground: description: | Set this option to `true` to keep the collection/shards available for diff --git a/site/content/3.13/develop/http-api/jobs.md b/site/content/3.13/develop/http-api/jobs.md index 4100b2e04e..c019c47cdf 100644 --- a/site/content/3.13/develop/http-api/jobs.md +++ b/site/content/3.13/develop/http-api/jobs.md @@ -624,6 +624,7 @@ paths: or `done` as `job-id` to list jobs. schema: type: number + default: 100 responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/monitoring/logs.md b/site/content/3.13/develop/http-api/monitoring/logs.md index 64bef4afa0..5ba17a8a9f 100644 --- a/site/content/3.13/develop/http-api/monitoring/logs.md +++ b/site/content/3.13/develop/http-api/monitoring/logs.md @@ -44,9 +44,10 @@ paths: - `warning` or `2` - `info` or `3` - `debug` or `4` - The default value is `info`. + - `trace` or `5` schema: - type: string + #type: [string, integer] + default: info - name: level in: query required: false @@ -59,10 +60,11 @@ paths: in: query required: false description: | - Returns all log entries such that their log entry identifier (`lid` .) + Returns all log entries such that their log entry identifier (`id` value) is greater or equal to `start`. schema: type: number + default: 0 - name: size in: query required: false @@ -78,6 +80,7 @@ paths: and `size` can be used for pagination. schema: type: number + default: 0 - name: search in: query required: false @@ -91,9 +94,10 @@ paths: description: | Sort the log entries either ascending (if `sort` is `asc`) or descending (if `sort` is `desc`) according to their `id` values. Note that the `id` - imposes a chronological order. The default value is `asc`. + imposes a chronological order. schema: type: string + default: asc - name: serverId in: query required: false @@ -149,9 +153,10 @@ paths: - `warning` or `2` - `info` or `3` - `debug` or `4` - The default value is `info`. + - `trace` or `5` schema: - type: string + #type: [string, integer] + default: info - name: level in: query required: false @@ -168,6 +173,7 @@ paths: is greater or equal to `start`. schema: type: number + default: 0 - name: size in: query required: false @@ -183,6 +189,7 @@ paths: and `size` can be used for pagination. schema: type: number + default: 0 - name: search in: query required: false @@ -196,9 +203,10 @@ paths: description: | Sort the log entries either ascending (if `sort` is `asc`) or descending (if `sort` is `desc`) according to their `lid` values. Note that the `lid` - imposes a chronological order. The default value is `asc`. + imposes a chronological order. schema: type: string + default: asc - name: serverId in: query required: false diff --git a/site/content/3.13/develop/http-api/queries/aql-queries.md b/site/content/3.13/develop/http-api/queries/aql-queries.md index 02a81cc341..d58691d1f5 100644 --- a/site/content/3.13/develop/http-api/queries/aql-queries.md +++ b/site/content/3.13/develop/http-api/queries/aql-queries.md @@ -5,6 +5,8 @@ weight: 5 description: >- The HTTP API for AQL queries lets you to execute, track, kill, explain, and validate queries written in ArangoDB's query language +# Undocumented on purpose: +# PUT /_db/{database-name}/_api/cursor/{cursor-identifier} (deprecated) --- ## Cursors @@ -347,12 +349,12 @@ paths: respect to the `ttl`. The cursor will be removed on the server automatically after the specified amount of time. This is useful to ensure garbage collection of cursors that are not fully fetched by clients. - - You can configure a default TTL with the `--query.registry-ttl` startup option. - If not set, the defaults are 30 seconds for single servers and 600 seconds for - Coordinators of a cluster deployment. The time-to-live is renewed upon every access to the cursor. + + Default: Controlled by the `--query.registry-ttl` startup option. + If not set, the defaults are 30 seconds for single servers and 600 seconds for + Coordinators of a cluster deployment. type: integer memoryLimit: description: | @@ -362,7 +364,7 @@ paths: no memory limit, but the `--query.global-memory-limit` startup option may still limit it. - You can configure a default per-query memory limit with the + Default: You can configure a default per-query memory limit with the `--query.memory-limit` startup option. You can only increase this default memory limit if `--query.memory-limit-override` is enabled. @@ -408,15 +410,18 @@ paths: maxNumberOfPlans: description: | Limits the maximum number of plans that are created by the AQL query optimizer. + + Default: Controlled by the `--query.optimizer-max-plans` startup option. type: integer maxNodesPerCallstack: description: | The number of execution nodes in the query plan after that stack splitting is - performed to avoid a potential stack overflow. Defaults to the configured value - of the startup option `--query.max-nodes-per-callstack`. + performed to avoid a potential stack overflow. This option is only useful for testing and debugging and normally does not need any adjustment. + + Default: Controlled by the `--query.max-nodes-per-callstack` startup option. type: integer maxWarningCount: description: | @@ -427,11 +432,12 @@ paths: failOnWarning: description: | If set to `true`, the query throws an exception and aborts instead of producing - a warning. This option should be used during development to catch potential issues + a warning. You should use this option during development to catch potential issues early. When the attribute is set to `false`, warnings are not propagated to exceptions and are returned with the query result. - There is also a `--query.fail-on-warning` startup option for setting the - default value for `failOnWarning`, so it does not need to be set on a per-query basis. + + Default: Controlled by the `--query.fail-on-warning` startup option, + so you don't need to set it on a per-query basis. type: boolean allowRetry: description: | @@ -517,7 +523,7 @@ paths: for the query. If you set it to `true`, the query cache is checked for a cached result **if** the query cache mode is either set to `on` or `demand`. - You can configure a default mode with the `--query.cache-mode` startup option. + Default: Controlled by the `--query.cache-mode` startup option. type: boolean usePlanCache: description: | @@ -545,7 +551,7 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: 128 MiB, respectively the value of the + Default: 128 MiB, respectively the value of the `--temp.intermediate-results-spillover-threshold-memory-usage` startup option. @@ -570,7 +576,7 @@ paths: for the directory to store the temporary data in with the `--temp.intermediate-results-path` startup option. - Default value: 5 million rows, respectively the value of the + Default: 5 million rows, respectively the value of the `--temp.intermediate-results-spillover-threshold-num-rows` startup option. @@ -588,10 +594,13 @@ paths: properties: rules: description: | - A list of to-be-included or to-be-excluded optimizer rules can be put into this - attribute, telling the optimizer to include or exclude specific rules. To disable - a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is - also a pseudo-rule `all`, which matches all optimizer rules. `-all` disables all rules. + A list of optimizer rules, telling the optimizer to + include or exclude specific rules. See the + [List of optimizer rules](../../../aql/execution-and-performance/query-optimization.md#list-of-optimizer-rules). + + To disable a rule, prefix its name with `-`. To enable a rule, + prefix it with `+`. There is also a pseudo-rule `all` that + matches all optimizer rules. `-all` disables all rules. type: array items: type: string @@ -603,6 +612,7 @@ paths: per query plan node in `stats.nodes` sub-attribute of the `extra` return attribute. Additionally, the query plan is returned in the `extra.plan` sub-attribute. type: integer + default: 0 satelliteSyncWait: description: | This parameter allows to configure how long a DB-Server has time @@ -614,9 +624,10 @@ paths: maxRuntime: description: | The query has to be executed within the given runtime or it is killed. - The value is specified in seconds. The default value is `0.0` (no timeout). + The value is specified in seconds. A value of `0.0` means no timeout. + + Default: Controlled by the `--query.max-runtime` startup option. type: number - default: 0.0 maxDNFConditionMembers: description: | A threshold for the maximum number of `OR` sub-nodes in the internal @@ -633,28 +644,28 @@ paths: condition, the conversion is aborted, and the query continues with a simplified internal representation of the condition, which **cannot be used for index lookups**. - You can set the threshold globally instead of per query with the - `--query.max-dnf-condition-members` startup option. + Default: Controlled by the `--query.max-dnf-condition-members` startup option + to set the threshold globally instead of per query. type: integer maxTransactionSize: description: | The transaction size limit in bytes. - You can configure the default with the `--rocksdb.max-transaction-size` startup option. + Default: Controlled by the `--rocksdb.max-transaction-size` startup option. type: integer intermediateCommitSize: description: | The maximum total size of operations after which an intermediate commit is performed automatically. - You can configure the default with the `--rocksdb.intermediate-commit-size` startup option. + Default: Controlled by `--rocksdb.intermediate-commit-size` startup option. type: integer intermediateCommitCount: description: | The maximum number of operations after which an intermediate commit is performed automatically. - You can configure the default with the `--rocksdb.intermediate-commit-count` startup option. + Default: Controlled by the `--rocksdb.intermediate-commit-count` startup option. type: integer skipInaccessibleCollections: description: | @@ -665,6 +676,7 @@ paths: execute AQL queries on that graph. You can naturally limit the accessible results by changing the access rights of users on collections. type: boolean + default: false allowDirtyReads: description: | If you set this option to `true` and execute the query against a cluster @@ -675,7 +687,13 @@ paths: namely obsolete revisions of documents because changes have not yet been replicated to the follower, as well as changes to documents before they are officially committed on the leader. + + The option is ignored if this operation is part of a Stream Transaction + (`x-arango-trx-id` header). The `x-arango-allow-dirty-read` header set + when creating the transaction decides about dirty reads for the entire + transaction, not the individual read operations. type: boolean + default: false responses: '201': description: | @@ -1870,143 +1888,6 @@ assert(response.code === 404); logJsonResponse(response); ``` -### Read the next batch from a cursor (deprecated) - -```openapi -paths: - /_db/{database-name}/_api/cursor/{cursor-identifier}: - put: - operationId: getNextAqlQueryCursorBatchPut - description: | - {{}} - This endpoint is deprecated in favor its functionally equivalent POST counterpart. - {{}} - - If the cursor is still alive, returns an object with the following - attributes: - - - `id`: a `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 - - `code`: an HTTP status code - - `error`: a boolean flag to indicate whether an error occurred - - `errorNum`: a server error number (if `error` is `true`) - - `errorMessage`: a descriptive error message (if `error` is `true`) - - `extra`: an object with additional information about the query result, with - the nested objects `stats` and `warnings`. Only delivered as part of the last - batch in case of a cursor with the `stream` option enabled. - - 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. - - If the cursor is not fully consumed, the time-to-live for the cursor - is renewed by this API call. - parameters: - - name: database-name - in: path - required: true - example: _system - description: | - The name of the database. - schema: - type: string - - name: cursor-identifier - in: path - required: true - description: | - The name of the cursor - schema: - type: string - responses: - '200': - description: | - Successfully fetched the batch. - '400': - description: | - The cursor identifier is missing. - '404': - description: | - A cursor with the specified identifier cannot be found. - '410': - description: | - A server which processes the query or the leader of a shard which is - used in the query stops responding, but the connection has not been closed. - '503': - description: | - A server which processes the query or the leader of a shard which is used - in the query is down, either for going through a restart, a failure, - or connectivity issues. - tags: - - Queries -``` - -**Examples** - -```curl ---- -description: |- - Valid request for next batch -name: RestCursorForLimitReturnCont ---- -var url = "/_api/cursor"; -var cn = "products"; -db._drop(cn); -db._create(cn); - -db.products.save({"hello1":"world1"}); -db.products.save({"hello2":"world1"}); -db.products.save({"hello3":"world1"}); -db.products.save({"hello4":"world1"}); -db.products.save({"hello5":"world1"}); - -var url = "/_api/cursor"; -var body = { - query: "FOR p IN products LIMIT 5 RETURN p", - count: true, - batchSize: 2 -}; -var response = logCurlRequest('POST', url, body); - -response = logCurlRequest('PUT', url + '/' + response.parsedBody.id, ''); -assert(response.code === 200); - -logJsonResponse(response); -db._drop(cn); -``` - -```curl ---- -description: |- - Missing identifier -name: RestCursorMissingCursorIdentifier ---- -var url = "/_api/cursor"; - -var response = logCurlRequest('PUT', url, ''); - -assert(response.code === 400); - -logJsonResponse(response); -``` - -```curl ---- -description: |- - Unknown identifier -name: RestCursorInvalidCursorIdentifier ---- -var url = "/_api/cursor/123123"; - -var response = logCurlRequest('PUT', url, ''); - -assert(response.code === 404); - -logJsonResponse(response); -``` - ### Read a batch from the cursor again ```openapi @@ -2674,7 +2555,7 @@ paths: If set to `true`, then queries are tracked. If set to `false`, neither regular queries nor slow queries are tracked. - You can configure the default value with the `--query.tracking` startup option. + Default: Controlled by the `--query.tracking` startup option. type: boolean trackSlowQueries: description: | @@ -2683,14 +2564,14 @@ paths: `slowQueryThreshold`. In order for slow queries to be tracked, the `enabled` property must also be set to `true`. - You can configure the default value with the `--query.tracking-slow-queries` startup option. + Default: Controlled by the `--query.tracking-slow-queries` startup option. type: boolean trackBindVars: description: | If set to `true`, then the bind variables used in queries are tracked along with queries. - You can configure the default value with the `--query.tracking-with-bindvars` startup option. + Default: Controlled by the `--query.tracking-with-bindvars` startup option. type: boolean maxSlowQueries: description: | @@ -2698,13 +2579,14 @@ paths: of slow queries. If the list of slow queries is full, the oldest entry is discarded when additional slow queries occur. type: integer + default: 64 slowQueryThreshold: description: | The threshold value for treating a query as slow (in seconds). A query with a runtime greater or equal to this threshold value is put into the list of slow queries if slow query tracking is enabled. - You can configure the default value with the `--query.slow-threshold` startup option. + Default: Controlled by the `--query.slow-threshold` startup option. type: integer slowStreamingQueryThreshold: description: | @@ -2713,7 +2595,7 @@ paths: threshold value is put into the list of slow queries if slow query tracking is enabled. - You can configure the default value with the `--query.slow-streaming-threshold` startup option. + Default: Controlled by the `--query.slow-streaming-threshold` startup option. type: integer maxQueryStringLength: description: | @@ -3085,8 +2967,8 @@ paths: # explainRegisters allPlans: description: | - if set to `true`, all possible execution plans will be returned. - The default is `false`, meaning only the optimal plan will be returned. + If set to `true`, all possible execution plans are returned. + The default is `false`, meaning only the optimal plan is returned. type: boolean default: false maxNumberOfPlans: @@ -3094,6 +2976,8 @@ paths: The maximum number of plans that the optimizer is allowed to generate. Setting this attribute to a low value allows to put a cap on the amount of work the optimizer does. + + Default: Controlled by the `--query.optimizer-max-plans` startup option. type: integer fullCount: description: | @@ -3109,14 +2993,16 @@ paths: If set to `2`, the response includes the time it took to process each optimizer rule under `stats.rules`. type: integer + default: 0 maxNodesPerCallstack: description: | The number of execution nodes in the query plan after that stack splitting is - performed to avoid a potential stack overflow. Defaults to the configured value - of the startup option `--query.max-nodes-per-callstack`. + performed to avoid a potential stack overflow. This option is only useful for testing and debugging and normally does not need any adjustment. + + Default: Controlled by the `--query.max-nodes-per-callstack` startup option. type: integer maxWarningCount: description: | @@ -3131,8 +3017,8 @@ paths: early. When the attribute is set to `false`, warnings are not propagated to exceptions and are returned with the query result. - You can use the `--query.fail-on-warning` startup option to adjust the - default value for `failOnWarning` so you don't need to set it on a per-query basis. + Default: Controlled by the `--query.fail-on-warning` startup option, + so you don't need to set it on a per-query basis. type: boolean optimizer: description: | @@ -3141,10 +3027,13 @@ paths: properties: rules: description: | - A list of to-be-included or to-be-excluded optimizer rules can be put into this - attribute, telling the optimizer to include or exclude specific rules. To disable - a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is - also a pseudo-rule `all`, which matches all optimizer rules. `-all` disables all rules. + A list of optimizer rules, telling the optimizer to + include or exclude specific rules. See the + [List of optimizer rules](../../../aql/execution-and-performance/query-optimization.md#list-of-optimizer-rules). + + To disable a rule, prefix its name with `-`. To enable a rule, + prefix it with `+`. There is also a pseudo-rule `all` that + matches all optimizer rules. `-all` disables all rules. type: array items: type: string diff --git a/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md b/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md index fd3fa6932c..6be038563f 100644 --- a/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md +++ b/site/content/3.13/develop/http-api/queries/aql-query-results-cache.md @@ -225,9 +225,6 @@ paths: mode: description: | The mode the AQL query results cache operates in. - - You can configure the default value with the - `--query.cache-mode` startup option. type: string # Unquoted on and off are booleans in YAML 1.1! enum: ["off", "on", "demand"] @@ -235,32 +232,20 @@ paths: description: | The maximum number of query results that are stored per database-specific cache. - - You can configure the default value with the - `--query.cache-entries` startup option. type: integer maxResultsSize: description: | The maximum cumulated size of query results that are stored per database-specific cache (in bytes). - - You can configure the default value with the - `--query.cache-entries-max-size` startup option. type: integer maxEntrySize: description: | The maximum individual result size of queries that are stored per database-specific cache (in bytes). - - You can configure the default value with the - `--query.cache-entry-max-size` startup option. includeSystem: description: | Whether results of queries that involve system collections are stored in the query results cache. - - You can configure the default value with the - `--query.cache-include-system-collections` startup option. type: boolean '400': description: | @@ -318,6 +303,8 @@ paths: mode: description: | The mode the AQL query cache shall operate in. + + Default: Controlled by the `--query.cache-mode` startup option. type: string # Unquoted on and off are booleans in YAML 1.1! enum: ["off", "on", "demand"] @@ -325,21 +312,30 @@ paths: description: | The maximum number of query results that are stored per database-specific cache. + + Default: Controlled by the `--query.cache-entries` startup option. type: integer maxResultsSize: description: | The maximum cumulated size of query results that are stored per database-specific cache (in bytes). + + Default: Controlled by the `--query.cache-entries-max-size` startup option. type: integer maxEntrySize: description: | The maximum individual size of query results that are stored per database-specific cache (in bytes). + + Default: Controlled by the `--query.cache-entry-max-size` startup option. type: integer includeSystem: description: | Whether to store results of queries that involve system collections in the cache. + + Default: Controlled by the `--query.cache-include-system-collections` + startup option type: boolean responses: '200': diff --git a/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md b/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md index cf497ebdf8..25f9b271c1 100644 --- a/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md +++ b/site/content/3.13/develop/http-api/queries/user-defined-aql-functions.md @@ -202,13 +202,15 @@ paths: in: query required: false description: | + Possible values: - `true`: The function name provided in `name` is treated as a namespace prefix, and all functions in the specified namespace will be deleted. The returned number of deleted functions may become 0 if none matches the string. - `false`: The function name provided in `name` must be fully qualified, including any namespaces. If none matches the `name`, HTTP 404 is returned. schema: - type: string + type: boolean + default: false responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/replication/replication-dump.md b/site/content/3.13/develop/http-api/replication/replication-dump.md index 32ce89dd72..240f70b647 100644 --- a/site/content/3.13/develop/http-api/replication/replication-dump.md +++ b/site/content/3.13/develop/http-api/replication/replication-dump.md @@ -112,16 +112,19 @@ paths: in: query required: false description: | - Include system collections in the result. The default value is `true`. + Include system collections in the result. schema: type: boolean + default: true - name: global in: query required: false description: | - Include all databases in the response. Only works on `_system` The default value is `false`. + Include all databases in the response. Only works in the context of + the `_system` database. schema: type: boolean + default: false - name: batchId in: query required: true @@ -197,7 +200,7 @@ paths: in: query required: false description: | - setting `state` to true will make the response also contain + Setting `state` to `true` makes the response also contain a `state` attribute with information about the leader state. This is used only internally during the replication process and should not be used by client applications. @@ -969,9 +972,10 @@ paths: in: query required: false description: | - Include system collections in the result. The default value is `true`. + Include system collections in the result. schema: type: boolean + default: true responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/replication/replication-logger.md b/site/content/3.13/develop/http-api/replication/replication-logger.md index 17b3d74b98..32d1199cd6 100644 --- a/site/content/3.13/develop/http-api/replication/replication-logger.md +++ b/site/content/3.13/develop/http-api/replication/replication-logger.md @@ -244,9 +244,10 @@ paths: in: query required: false description: | - Include system collections in the result. The default value is `true`. + Include system collections in the result. schema: type: boolean + default: true responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/replication/write-ahead-log.md b/site/content/3.13/develop/http-api/replication/write-ahead-log.md index 50bd2833dc..b4bcfda59d 100644 --- a/site/content/3.13/develop/http-api/replication/write-ahead-log.md +++ b/site/content/3.13/develop/http-api/replication/write-ahead-log.md @@ -270,9 +270,10 @@ paths: description: | Whether operations for all databases should be included. If set to `false`, only the operations for the current database are included. The value `true` is - only valid on the `_system` database. The default is `false`. + only valid on the `_system` database. schema: type: boolean + default: false - name: from in: query required: false diff --git a/site/content/3.13/develop/http-api/tasks.md b/site/content/3.13/develop/http-api/tasks.md index e1443c7e86..63056e0ea3 100644 --- a/site/content/3.13/develop/http-api/tasks.md +++ b/site/content/3.13/develop/http-api/tasks.md @@ -249,14 +249,15 @@ paths: description: | The name of the task. type: string + default: "user-defined task" command: description: | The JavaScript code to be executed. type: string params: description: | - The parameters to be passed to the command. - type: string + The value to be passed to the command. + It can be of any type. period: description: | The number of seconds between the executions. @@ -265,6 +266,7 @@ paths: description: | The number of seconds for the initial delay. type: integer + default: 0 responses: '200': description: | @@ -397,8 +399,8 @@ paths: type: string params: description: | - The parameters to be passed to the command. - type: string + The value to be passed to the command. + It can be of any type. period: description: | The number of seconds between the executions. @@ -407,6 +409,7 @@ paths: description: | The number of seconds for the initial delay. type: integer + default: 0 responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/transactions/javascript-transactions.md b/site/content/3.13/develop/http-api/transactions/javascript-transactions.md index 50423b214c..1443242a78 100644 --- a/site/content/3.13/develop/http-api/transactions/javascript-transactions.md +++ b/site/content/3.13/develop/http-api/transactions/javascript-transactions.md @@ -92,7 +92,7 @@ paths: properties: collections: description: | - `collections` must be a JSON object that can have one or all sub-attributes + Must be a JSON object that can have one or all sub-attributes `read`, `write` or `exclusive`, each being an array of collection names or a single collection name as string. Collections that will be written to in the transaction must be declared with the `write` or `exclusive` attribute or it @@ -101,42 +101,65 @@ paths: to let transactions fail in case of undeclared collections for reading. Collections for reading should be fully declared if possible, to avoid deadlocks. - type: string + type: object + properties: + read: + description: | + A single collection or a list of collections to use in + the transaction in read-only mode. + # type: [string, array] + # items: + # type: string + write: + description: | + A single collection or a list of collections to use in + the transaction in write or read mode. + # type: [string, array] + # items: + # type: string + exclusive: + description: | + A single collection or a list of collections to acquire + exclusive write access for. + # type: [string, array] + # items: + # type: string action: description: | - the actual transaction operations to be executed, in the - form of stringified JavaScript code. The code will be executed on server + The actual transaction operations to be executed, in the + form of stringified JavaScript code. The code is executed on the 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` + value returned is also returned by the REST API in the `result` attribute if the transaction committed successfully. type: string waitForSync: description: | - an optional boolean flag that, if set, will force the + An optional boolean flag that, if set, forces the transaction to write all data to disk before returning. type: boolean allowImplicit: description: | Allow reading from undeclared collections. type: boolean + default: true lockTimeout: description: | - an optional numeric value that can be used to set a - timeout in seconds for waiting on collection locks. This option is only - meaningful when using exclusive locks. If not specified, a default value of - 900 seconds will be used. Setting `lockTimeout` to `0` will make ArangoDB - not time out waiting for a lock. + The timeout in seconds for waiting on collection locks. + This option is only meaningful when using exclusive locks. + Set `lockTimeout` to `0` to make ArangoDB not time out + waiting for a lock. type: integer + default: 900 params: description: | - optional arguments passed to `action`. - type: string + Optional argument passed to `action`. Can be of any type. maxTransactionSize: description: | Transaction size limit in bytes. type: integer + default: 18446744073709551615 # Max value of uint64_t responses: '200': description: | diff --git a/site/content/3.13/develop/http-api/transactions/stream-transactions.md b/site/content/3.13/develop/http-api/transactions/stream-transactions.md index 147d446747..0deab59187 100644 --- a/site/content/3.13/develop/http-api/transactions/stream-transactions.md +++ b/site/content/3.13/develop/http-api/transactions/stream-transactions.md @@ -22,7 +22,7 @@ ArangoDB. No `action` attribute is supported. The Stream Transaction API works in *conjunction* with other APIs in ArangoDB. To use the transaction for a supported operation a client needs to specify the transaction identifier in the `x-arango-trx-id` HTTP header on each request. -This will automatically cause these operations to use the specified transaction. +This automatically causes these operations to use the specified transaction. Supported transactional API operations include: @@ -51,7 +51,7 @@ paths: until the entire transaction times out. The transaction description must be passed in the body of the POST request. - If the transaction can be started on the server, *HTTP 201* will be returned. + If the transaction can be started on the server, *HTTP 201* is returned. For successfully started transactions, the returned JSON object has the following properties: @@ -66,9 +66,9 @@ paths: - `status`: containing the string 'running' If the transaction specification is either missing or malformed, the server - will respond with *HTTP 400* or *HTTP 404*. + responds with *HTTP 400* or *HTTP 404*. - The body of the response will then contain a JSON object with additional error + The body of the response then contains 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) @@ -108,33 +108,59 @@ paths: properties: collections: description: | - `collections` must be a JSON object that can have one or all sub-attributes + Must be a JSON object that can have one or all sub-attributes `read`, `write` or `exclusive`, each being an array of collection names or a single collection name as string. Collections that will be written to in the transaction must be declared with the `write` or `exclusive` attribute or it will fail, whereas non-declared collections from which is solely read will be added lazily. type: object + properties: + read: + description: | + A single collection or a list of collections to use in + the transaction in read-only mode. + # type: [string, array] + # items: + # type: string + write: + description: | + A single collection or a list of collections to use in + the transaction in write or read mode. + # type: [string, array] + # items: + # type: string + exclusive: + description: | + A single collection or a list of collections to acquire + exclusive write access for. + # type: [string, array] + # items: + # type: string waitForSync: description: | - an optional boolean flag that, if set, will force the + An optional boolean flag that, if set, forces the transaction to write all data to disk before returning. type: boolean allowImplicit: description: | Allow reading from undeclared collections. type: boolean + default: true lockTimeout: description: | - an optional numeric value that can be used to set a - timeout in seconds for waiting on collection locks. This option is only - meaningful when using exclusive locks. If not specified, a default - value will be used. Setting `lockTimeout` to `0` will make ArangoDB - not time out waiting for a lock. + The timeout in seconds for waiting on collection locks. + This option is only meaningful when using exclusive locks. + Set `lockTimeout` to `0` to make ArangoDB not time out + waiting for a lock. type: integer + default: 900 maxTransactionSize: description: | Transaction size limit in bytes. + + Default: Controlled by the `--transaction.streaming-max-transaction-size` + startup option. type: integer skipFastLockRound: description: | @@ -301,7 +327,7 @@ paths: Commit a running server-side transaction. Committing is an idempotent operation. It is not an error to commit a transaction more than once. - If the transaction can be committed, *HTTP 200* will be returned. + If the transaction can be committed, *HTTP 200* is returned. The returned JSON object has the following properties: - `error`: boolean flag to indicate if an error occurred (`false` @@ -315,9 +341,9 @@ paths: If the transaction cannot be found, committing is not allowed or the transaction was aborted, the server - will respond with *HTTP 400*, *HTTP 404* or *HTTP 409*. + responds with *HTTP 400*, *HTTP 404* or *HTTP 409*. - The body of the response will then contain a JSON object with additional error + The body of the response then contains 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) @@ -402,7 +428,7 @@ paths: Abort a running server-side transaction. Aborting is an idempotent operation. It is not an error to abort a transaction more than once. - If the transaction can be aborted, *HTTP 200* will be returned. + If the transaction can be aborted, *HTTP 200* is returned. The returned JSON object has the following properties: - `error`: boolean flag to indicate if an error occurred (`false` @@ -416,9 +442,9 @@ paths: If the transaction cannot be found, aborting is not allowed or the transaction was already committed, the server - will respond with *HTTP 400*, *HTTP 404* or *HTTP 409*. + responds with *HTTP 400*, *HTTP 404* or *HTTP 409*. - The body of the response will then contain a JSON object with additional error + The body of the response then contains 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) @@ -502,7 +528,7 @@ paths: description: | The result is an object with the `transactions` attribute, which contains an array of transactions. - In a cluster the array will contain the transactions from all Coordinators. + In a cluster, the array contains the transactions from all Coordinators. Each array entry contains an object with the following attributes: diff --git a/site/content/3.13/develop/http-api/users.md b/site/content/3.13/develop/http-api/users.md index 38cd9d12e2..c527c88f83 100644 --- a/site/content/3.13/develop/http-api/users.md +++ b/site/content/3.13/develop/http-api/users.md @@ -55,7 +55,6 @@ paths: type: object required: - user - - passwd properties: user: description: | @@ -63,9 +62,10 @@ paths: type: string passwd: description: | - The user password as a string. If not specified, it will default to an empty + The user password as a string. If not specified, it default to an empty string. type: string + default: "" active: description: | Whether the user account should be able to log in to the database system. @@ -125,7 +125,8 @@ paths: put: operationId: replaceUserData description: | - Replaces the data of an existing user. You need server access level + Replaces the data of an existing user. This resets the user's + access levels for databases and collections. You need server access level *Administrate* in order to execute this REST call. Additionally, users can change their own data. parameters: @@ -151,14 +152,13 @@ paths: application/json: schema: type: object - required: - - passwd properties: passwd: description: | - The user password as a string. If not specified, it will default to an empty + The user password as a string. If not specified, it defaults to an empty string. type: string + default: "" active: description: | Whether the user account should be able to log in to the database system. @@ -246,8 +246,6 @@ paths: application/json: schema: type: object - required: - - passwd properties: passwd: description: | diff --git a/site/content/3.13/develop/http-api/views/arangosearch-views.md b/site/content/3.13/develop/http-api/views/arangosearch-views.md index 9f6f0185bb..f585052364 100644 --- a/site/content/3.13/develop/http-api/views/arangosearch-views.md +++ b/site/content/3.13/develop/http-api/views/arangosearch-views.md @@ -46,8 +46,28 @@ paths: links: description: | Expects an object with the attribute keys being names of to be linked collections, - and the link properties as attribute values. See - [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) + and the link properties as attribute values. Example: + + ```json + { + "name": "arangosearch", + "links": { + "coll": { + "fields": { + "my_attribute": { + "fields": { + "my_sub_attribute": { + "analyzers": ["text_en"] + } + } + } + } + } + } + } + ``` + + See [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) for details. type: object primarySort: @@ -63,6 +83,7 @@ paths: (attribute path) and a sort direction: `[ { "field": "attr", "direction": "asc"}, … ]` type: array + default: [] items: type: object required: @@ -142,6 +163,7 @@ paths: Example: `["BM25(@doc) DESC", "TFIDF(@doc, true) DESC"]` type: array + default: [] items: type: string storedValues: @@ -180,6 +202,7 @@ paths: The `storedValues` option is not to be confused with the `storeValues` option, which allows to store meta data about attribute values in the View index. type: array + default: [] items: type: object required: @@ -1289,8 +1312,28 @@ paths: links: description: | Expects an object with the attribute keys being names of to be linked collections, - and the link properties as attribute values. See - [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) + and the link properties as attribute values. Example: + + ```json + { + "name": "arangosearch", + "links": { + "coll": { + "fields": { + "my_attribute": { + "fields": { + "my_sub_attribute": { + "analyzers": ["text_en"] + } + } + } + } + } + } + } + ``` + + See [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) for details. type: object cleanupIntervalStep: @@ -1781,8 +1824,28 @@ paths: links: description: | Expects an object with the attribute keys being names of to be linked collections, - and the link properties as attribute values. See - [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) + and the link properties as attribute values. Example: + + ```json + { + "name": "arangosearch", + "links": { + "coll": { + "fields": { + "my_attribute": { + "fields": { + "my_sub_attribute": { + "analyzers": ["text_en"] + } + } + } + } + } + } + } + ``` + + See [`arangosearch` View Link Properties](../../../index-and-search/arangosearch/arangosearch-views-reference.md#link-properties) for details. type: object cleanupIntervalStep: diff --git a/site/content/3.13/develop/http-api/views/search-alias-views.md b/site/content/3.13/develop/http-api/views/search-alias-views.md index ed4015ac5d..9ac1ae3fdf 100644 --- a/site/content/3.13/develop/http-api/views/search-alias-views.md +++ b/site/content/3.13/develop/http-api/views/search-alias-views.md @@ -1035,6 +1035,18 @@ paths: The name of the View to rename. schema: type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + description: | + The new name for the View. + type: string responses: '200': description: | diff --git a/site/content/3.13/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md b/site/content/3.13/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md index ae5b4dc316..6feb707e61 100644 --- a/site/content/3.13/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md +++ b/site/content/3.13/index-and-search/indexing/working-with-indexes/geo-spatial-indexes.md @@ -76,7 +76,7 @@ _longitude_. The `geoJson` flag is implicitly _false_ in this mode. Alternatively you can specify only one field: -`collection.ensureIndex({ type: "geo", fields: [ "location" ], geoJson:false })` +`collection.ensureIndex({ type: "geo", fields: [ "location" ], geoJson: false })` It creates a geospatial index on all documents using `location` as the path to the coordinates. The value of the attribute has to be an array with at least two