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 0e449df6df..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: | @@ -241,15 +241,26 @@ 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 + be sharded independently. + - `"single"`: Create a OneShard database where all collections have a + single shard and all leader shards are co-located on the same DB-Server. type: string + enum: ["", flexible, single] + default: "" 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: | @@ -260,7 +271,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`. @@ -269,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 @@ -287,21 +298,21 @@ 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: 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 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/documents.md b/site/content/3.11/develop/http-api/documents.md index 5c9e7dfbd5..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 @@ -475,6 +478,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,18 +503,21 @@ 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 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 @@ -518,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 @@ -530,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 @@ -867,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 @@ -882,6 +892,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -890,6 +901,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -901,6 +913,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -909,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 @@ -1171,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 @@ -1185,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 @@ -1200,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 @@ -1215,6 +1231,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -1223,6 +1240,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1234,6 +1252,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1242,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 @@ -1468,6 +1488,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1479,6 +1500,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1487,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 @@ -1738,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 @@ -1915,6 +1938,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -1923,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 @@ -1935,6 +1960,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -1946,6 +1972,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,18 +1997,21 @@ 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 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 @@ -1989,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 @@ -2001,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 @@ -2228,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 @@ -2243,6 +2276,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2251,6 +2285,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2263,6 +2298,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2271,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 @@ -2433,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 @@ -2447,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 @@ -2462,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 @@ -2477,6 +2516,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2485,6 +2525,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2497,6 +2538,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2505,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 @@ -2668,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 @@ -2681,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..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 @@ -282,11 +285,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 +300,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 +1176,7 @@ paths: dropped if they are not used in other graphs. schema: type: boolean + default: false responses: '202': description: | @@ -2877,6 +2883,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 +3349,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 +3740,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -3744,14 +3753,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: | @@ -4024,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 @@ -4053,31 +4059,22 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - 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. - 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 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 HTTP status code 412 is returned. schema: type: string - - name: if-none-match + - 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 @@ -4134,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: @@ -4272,7 +4268,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -4333,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 @@ -4380,6 +4379,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4388,6 +4388,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4396,13 +4397,14 @@ 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 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 HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -4417,14 +4419,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 +4710,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -4776,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 @@ -4823,6 +4824,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4831,6 +4833,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4839,13 +4842,14 @@ 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 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 @@ -4860,14 +4864,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 +5155,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -5221,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 @@ -5265,13 +5268,14 @@ 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 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 @@ -5487,7 +5491,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -5589,6 +5594,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -5601,6 +5607,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 @@ -5967,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 @@ -5996,31 +6006,22 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - 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. - 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 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 HTTP status code 412 is returned. schema: type: string - - name: if-none-match + - 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 @@ -6087,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: @@ -6225,7 +6225,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -6287,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 @@ -6350,13 +6353,14 @@ 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 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 HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -6371,14 +6375,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 +6727,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -6791,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 @@ -6854,13 +6857,14 @@ 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 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 @@ -6875,6 +6879,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 +7245,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -7306,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 @@ -7350,13 +7360,13 @@ 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 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 @@ -7592,7 +7602,8 @@ paths: type: string '412': description: | - Returned if 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.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 ``` 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..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,23 +320,25 @@ paths: # forceOneShardAttributeValue query: description: | - contains the query string to be executed + The AQL query string to execute. 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: | @@ -2679,6 +2724,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2750,6 +2796,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2793,6 +2840,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2841,12 +2889,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 +3013,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 +3027,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 +3045,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/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 561aa5bc38..38cd9d12e2 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 @@ -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.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/http-api/collections.md b/site/content/3.12/develop/http-api/collections.md index 163849bf28..e3390aed1e 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 db9e47e89a..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: | @@ -241,15 +241,26 @@ 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 + be sharded independently. + - `"single"`: Create a OneShard database where all collections have a + single shard and all leader shards are co-located on the same DB-Server. type: string + enum: ["", flexible, single] + default: "" 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: | @@ -267,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 @@ -285,21 +296,21 @@ 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: 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 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/documents.md b/site/content/3.12/develop/http-api/documents.md index 59f80e2b47..8fb1a797b1 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 @@ -465,6 +468,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,18 +493,21 @@ 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 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 @@ -508,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 @@ -520,6 +528,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -885,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 @@ -900,6 +910,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -908,6 +919,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -919,6 +931,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -927,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 @@ -957,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 @@ -1214,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 @@ -1228,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 @@ -1243,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 @@ -1258,6 +1274,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -1266,6 +1283,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1277,6 +1295,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1285,6 +1304,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -1315,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 @@ -1536,6 +1556,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1547,6 +1568,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1555,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 @@ -1806,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 @@ -1973,6 +1996,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -1981,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 @@ -1993,6 +2018,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -2004,6 +2030,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,18 +2055,21 @@ 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 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 @@ -2047,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 @@ -2059,6 +2090,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2314,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 @@ -2329,6 +2362,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2337,6 +2371,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2349,6 +2384,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2357,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 @@ -2544,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 @@ -2558,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 @@ -2573,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 @@ -2588,6 +2627,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2596,6 +2636,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2608,6 +2649,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2616,6 +2658,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2804,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 @@ -2817,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 b9e4d5b7c9..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 @@ -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 @@ -282,10 +285,12 @@ paths: description: | Define if the created graph should be smart. type: boolean + default: false isDisjoint: description: | Whether to create a Disjoint SmartGraph instead of a regular SmartGraph. type: boolean + default: false options: description: | a JSON object to define options for creating collections within this graph. @@ -294,7 +299,7 @@ paths: properties: smartGraphAttribute: description: | - Required if `isSmart` is true. + Required to create a SmartGraph. The attribute name that is used to smartly shard the vertices of a graph. Every vertex in this SmartGraph has to have this attribute. @@ -1165,6 +1170,7 @@ paths: dropped if they are not used in other graphs. schema: type: boolean + default: false responses: '202': description: | @@ -2871,6 +2877,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false requestBody: content: application/json: @@ -3336,6 +3343,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false responses: '201': description: | @@ -3726,6 +3734,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -3738,14 +3747,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: | @@ -4018,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 @@ -4047,31 +4053,22 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - 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. - 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 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 HTTP status code 412 is returned. schema: type: string - - name: if-none-match + - 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 @@ -4128,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: @@ -4266,7 +4262,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -4327,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 @@ -4374,6 +4373,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4382,6 +4382,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4390,13 +4391,14 @@ 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 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 HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -4411,14 +4413,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: | @@ -4706,7 +4704,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -4770,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 @@ -4817,6 +4818,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4825,6 +4827,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4833,13 +4836,14 @@ 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 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 @@ -4854,14 +4858,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: | @@ -5149,7 +5149,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -5215,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 @@ -5259,13 +5262,14 @@ 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 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 @@ -5481,7 +5485,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -5583,6 +5588,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -5595,6 +5601,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 @@ -5961,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 @@ -5990,31 +6000,22 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - 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. - 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 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 HTTP status code 412 is returned. schema: type: string - - name: if-none-match + - 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 @@ -6081,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: @@ -6219,7 +6219,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -6281,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 @@ -6344,13 +6347,14 @@ 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 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 HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -6365,14 +6369,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: | @@ -6721,7 +6721,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -6785,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 @@ -6848,13 +6851,14 @@ 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 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 @@ -6869,6 +6873,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 @@ -7232,7 +7239,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -7300,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 @@ -7344,13 +7354,13 @@ 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 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 @@ -7586,7 +7596,8 @@ paths: type: string '412': description: | - Returned if 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/queries/aql-queries.md b/site/content/3.12/develop/http-api/queries/aql-queries.md index 9898ecbd40..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,23 +320,25 @@ paths: # forceOneShardAttributeValue query: description: | - contains the query string to be executed + The AQL query string to execute. 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: | @@ -2638,43 +2668,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: | @@ -2682,7 +2721,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: | @@ -2756,6 +2799,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2827,6 +2871,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2870,6 +2915,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2918,12 +2964,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: | @@ -3041,6 +3088,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 @@ -3054,6 +3102,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. @@ -3071,9 +3120,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/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 561aa5bc38..38cd9d12e2 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 @@ -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/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/http-api/collections.md b/site/content/3.13/develop/http-api/collections.md index 8040b34b30..6c1658a9c8 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. @@ -5178,381 +5180,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 db9e47e89a..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: | @@ -241,15 +241,26 @@ 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 + be sharded independently. + - `"single"`: Create a OneShard database where all collections have a + single shard and all leader shards are co-located on the same DB-Server. type: string + enum: ["", flexible, single] + default: "" 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: | @@ -267,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 @@ -285,21 +296,21 @@ 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: 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 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/documents.md b/site/content/3.13/develop/http-api/documents.md index 59f80e2b47..8fb1a797b1 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 @@ -465,6 +468,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,18 +493,21 @@ 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 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 @@ -508,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 @@ -520,6 +528,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -885,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 @@ -900,6 +910,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -908,6 +919,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -919,6 +931,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -927,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 @@ -957,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 @@ -1214,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 @@ -1228,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 @@ -1243,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 @@ -1258,6 +1274,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -1266,6 +1283,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1277,6 +1295,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1285,6 +1304,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -1315,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 @@ -1536,6 +1556,7 @@ paths: document under the attribute `old` in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -1547,6 +1568,7 @@ paths: You can use this option to save network traffic. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -1555,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 @@ -1806,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 @@ -1973,6 +1996,7 @@ paths: in the result. schema: type: boolean + default: false - name: returnOld in: query required: false @@ -1981,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 @@ -1993,6 +2018,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: overwrite in: query required: false @@ -2004,6 +2030,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,18 +2055,21 @@ 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 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 @@ -2047,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 @@ -2059,6 +2090,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2314,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 @@ -2329,6 +2362,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2337,6 +2371,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2349,6 +2384,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2357,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 @@ -2544,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 @@ -2558,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 @@ -2573,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 @@ -2588,6 +2627,7 @@ paths: documents under the attribute `old` in the result. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -2596,6 +2636,7 @@ paths: in the result. schema: type: boolean + default: false - name: silent in: query required: false @@ -2608,6 +2649,7 @@ paths: to the inputs of your request. schema: type: boolean + default: false - name: refillIndexCaches in: query required: false @@ -2616,6 +2658,7 @@ paths: affect the edge index or cache-enabled persistent indexes. schema: type: boolean + default: false - name: versionAttribute in: query required: false @@ -2804,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 @@ -2817,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 b9e4d5b7c9..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 @@ -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 @@ -282,10 +285,12 @@ paths: description: | Define if the created graph should be smart. type: boolean + default: false isDisjoint: description: | Whether to create a Disjoint SmartGraph instead of a regular SmartGraph. type: boolean + default: false options: description: | a JSON object to define options for creating collections within this graph. @@ -294,7 +299,7 @@ paths: properties: smartGraphAttribute: description: | - Required if `isSmart` is true. + Required to create a SmartGraph. The attribute name that is used to smartly shard the vertices of a graph. Every vertex in this SmartGraph has to have this attribute. @@ -1165,6 +1170,7 @@ paths: dropped if they are not used in other graphs. schema: type: boolean + default: false responses: '202': description: | @@ -2871,6 +2877,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false requestBody: content: application/json: @@ -3336,6 +3343,7 @@ paths: The collection is only dropped if it is not used in other graphs. schema: type: boolean + default: false responses: '201': description: | @@ -3726,6 +3734,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -3738,14 +3747,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: | @@ -4018,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 @@ -4047,31 +4053,22 @@ paths: The `_key` attribute of the vertex. schema: type: string - - name: rev - 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. - 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 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 HTTP status code 412 is returned. schema: type: string - - name: if-none-match + - 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 @@ -4128,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: @@ -4266,7 +4262,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -4327,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 @@ -4374,6 +4373,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4382,6 +4382,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4390,13 +4391,14 @@ 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 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 HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -4411,14 +4413,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: | @@ -4706,7 +4704,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -4770,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 @@ -4817,6 +4818,7 @@ paths: of objects that are nested inside of arrays). schema: type: boolean + default: true - name: returnOld in: query required: false @@ -4825,6 +4827,7 @@ paths: be returned within the response object. schema: type: boolean + default: false - name: returnNew in: query required: false @@ -4833,13 +4836,14 @@ 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 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 @@ -4854,14 +4858,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: | @@ -5149,7 +5149,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -5215,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 @@ -5259,13 +5262,14 @@ 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 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 @@ -5481,7 +5485,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -5583,6 +5588,7 @@ paths: new version of the document. schema: type: boolean + default: false - name: x-arango-trx-id in: header required: false @@ -5595,6 +5601,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 @@ -5961,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 @@ -5990,31 +6000,22 @@ paths: The `_key` attribute of the edge. schema: type: string - - name: rev - 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. - 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 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 HTTP status code 412 is returned. schema: type: string - - name: if-none-match + - 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 @@ -6081,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: @@ -6219,7 +6219,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -6281,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 @@ -6344,13 +6347,14 @@ 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 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 HTTP status code 412 is returned. schema: type: string - name: x-arango-trx-id @@ -6365,14 +6369,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: | @@ -6721,7 +6721,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -6785,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 @@ -6848,13 +6851,14 @@ 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 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 @@ -6869,6 +6873,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 @@ -7232,7 +7239,8 @@ paths: type: string '412': description: | - Returned if 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: @@ -7300,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 @@ -7344,13 +7354,13 @@ 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 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 @@ -7586,7 +7596,8 @@ paths: type: string '412': description: | - Returned if 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/queries/aql-queries.md b/site/content/3.13/develop/http-api/queries/aql-queries.md index 9898ecbd40..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,23 +320,25 @@ paths: # forceOneShardAttributeValue query: description: | - contains the query string to be executed + The AQL query string to execute. 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: | @@ -2638,43 +2668,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: | @@ -2682,7 +2721,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: | @@ -2756,6 +2799,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2827,6 +2871,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2870,6 +2915,7 @@ paths: privileges. schema: type: boolean + default: false responses: '200': description: | @@ -2918,12 +2964,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: | @@ -3041,6 +3088,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 @@ -3054,6 +3102,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. @@ -3071,9 +3120,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/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 561aa5bc38..38cd9d12e2 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 @@ -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/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`.