Arango logo

ArangoDB v4.x is under development and not released yet.

This documentation is not final and potentially incomplete.

arangosearch View HTTP API

The HTTP API for Views lets you manage arangosearch Views, including handling the general View properties and View links

Create an arangosearch View

POST http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view
Creates a new View with a given name and properties if it does not already exist.
Path Parameters

  • The name of the database.

    Example: _system

Query Parameters
    HTTP Headers
      Request Body application/json object

      • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disable). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value causes a lot of disk space to be wasted. For the case where the consolidation policies rarely merge segments (i.e. few inserts/deletes), a higher value impacts performance without any added benefits.

        Also see ArangoSearch cleanup.

      • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disable). For the case where there are a lot of inserts/updates, a higher value causes the index not to account for them and memory usage continues to grow until the commit. A lower value impacts performance, including the case where there are no or only a few inserts/updates because of synchronous locking, and it wastes disk space for each commit call.

        Also see ArangoSearch commits.

      • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disable). For the case where there are a lot of data modification operations, a higher value could potentially have the data store consume more space and file handles. For the case where there are a few data modification operations, a lower value impacts performance due to no segment candidates being available for consolidation.

        Also see ArangoSearch consolidation.

      • The consolidation policy to apply for selecting which segments should be merged.

        • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
        • If the bytes_accum type is used, then the threshold property is available.

        Also see ArangoSearch consolidation.

        • Introduced in: v3.12.7

          The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

          A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

          On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

          Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

        • Introduced in: v3.12.7

          The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

          The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

          The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

          During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

        • Maximum allowed size of all consolidated segments in bytes.

        • A value in the range [0.0, 1.0].

        • Possible values: "tier", "bytes_accum"

          The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

          • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
          • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

      • Expects an object with the attribute keys being names of to be linked collections, and the link properties as attribute values. Example:

        {
  "name": "arangosearch",
  "links": {
    "coll": {
      "fields": {
        "my_attribute": {
          "fields": {
            "my_sub_attribute": {
              "analyzers": ["text_en"]
            }
          }
        }
      }
    }
  }
}

        See arangosearch View Link Properties for details.

      • The name of the View.

      • Introduced in: v3.12.0

        An array of strings defining sort expressions that you want to optimize. This is also known as WAND optimization.

        This option is immutable.

        If you query a View with the SEARCH operation in combination with a SORT and LIMIT operation, search results can be retrieved faster if the SORT expression matches one of the optimized expressions.

        Only sorting by highest rank is supported, that is, sorting by the result of a scoring function in descending order (DESC). Use @doc in the expression where you would normally pass the document variable emitted by the SEARCH operation to the scoring function.

        You can define up to 64 expressions per View.

        Example: ["BM25(@doc) DESC", "TFIDF(@doc, true) DESC"]

      • Introduced in: v3.9.6, v3.10.2

        If you enable this option, then the primary key columns are always cached in memory. This can improve the performance of queries that return many documents. Otherwise, these values are memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory.

        This option is immutable.

        See the --arangosearch.columns-cache-limit startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the --arangosearch.columns-cache-only-leader startup option (introduced in v3.10.6).

      • You can define a primary sort order to enable an AQL optimization. If a query iterates over all documents of a View, wants to sort them by attribute values and the (left-most) fields to sort by as well as their sorting direction match with the primarySort definition, then the SORT operation is optimized away. This option is immutable.

        Expects an array of objects, each specifying a field (attribute path) and a sort direction: [ { "field": "attr", "direction": "asc"}, … ]

        • Possible values: "asc", "desc"

          The sort direction.

          • "asc" for ascending
          • "desc" for descending

        • An attribute path. The . character denotes sub-attributes.

      • Introduced in: v3.9.6, v3.10.2

        If you enable this option, then the primary sort columns are always cached in memory. This can improve the performance of queries that utilize the primary sort order. Otherwise, these values are memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory.

        This option is immutable.

        See the --arangosearch.columns-cache-limit startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the --arangosearch.columns-cache-only-leader startup option (introduced in v3.10.6).

      • Possible values: "lz4", "none"

        Defines how to compress the primary sort data.

        • "lz4": use LZ4 fast compression.
        • "none": disable compression to trade space for speed.

        This option is immutable.

      • An array of objects to describe which document attributes to store in the View index. It can then cover search queries, which means the data can be taken from the index directly and accessing the storage engine can be avoided.

        This option is immutable.

        Each object is expected in the following form:

        { "fields": [ "attr1", "attr2", ... "attrN" ], "compression": "none", "cache": false }

        You may use the following shorthand notations on View creation instead of an array of objects as described above. The default compression and cache settings are used in this case:

        • An array of strings, like ["attr1", "attr2"], to place each attribute into a separate column of the index.

        • An array of arrays of strings, like [["attr1", "attr2"]], to place the attributes into a single column of the index, or [["attr1"], ["attr2"]] to place each attribute into a separate column. You can also mix it with the full form:

          [
  ["attr1"],
  ["attr2", "attr3"],
  { "fields": ["attr4", "attr5"], "cache": true }
]

        The storedValues option is not to be confused with the storeValues option, which allows you to store meta data about attribute values in the View index.

        • Introduced in: v3.9.5, v3.10.2

          Whether to always cache stored values in memory. This can improve the query performance if stored values are involved. Otherwise, these values are memory-mapped and it is up to the operating system to load them from disk into memory and to evict them from memory.

          See the --arangosearch.columns-cache-limit startup option to control the memory consumption of this cache. You can reduce the memory usage of the column cache in cluster deployments by only using the cache for leader shards, see the --arangosearch.columns-cache-only-leader startup option (introduced in v3.10.6).

        • Possible values: "lz4", "none"

          Defines the compression type used for the internal column-store.

          • "lz4": LZ4 fast compression
          • "none": no compression

        • An array of strings with one or more document attribute paths. The specified attributes are placed into a single column of the index. A column with all fields that are involved in common search queries is ideal for performance. The column should not include too many unneeded fields, however.

      • The type of the View. Needs to be set to "arangosearch". This option is immutable.

        Example: "arangosearch"

      • Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers (segments) finish (immutable, 0 = disable).

      • Maximum number of writers (segments) cached in the pool (immutable, 0 = disable).

      • Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. The value 0 turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (ArangoDB server startup option). This should be used carefully due to high potential memory consumption (immutable, 0 = disable).

      Responses

      • The View has been created.

          Response Body application/json object

        • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disabled).

        • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disabled).

        • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disabled).

        • The consolidation policy to apply for selecting which segments should be merged.

          • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
          • If the bytes_accum type is used, then the threshold property is available.

          • Introduced in: v3.12.7

            The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

            A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

            On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

            Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

          • Introduced in: v3.12.7

            The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

            The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

            The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

            During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

          • Maximum allowed size of all consolidated segments in bytes.

          • A value in the range [0.0, 1.0]

          • Possible values: "tier", "bytes_accum"

            The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

            • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
            • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

        • A unique identifier of the View. This is an internal property.

        • A unique identifier of the View (deprecated).

        • The name of the View.

          Example: "coll"

        • Introduced in: v3.12.0

          An array of strings defining sort expressions that can be optimized. This is also known as WAND optimization.

        • Introduced in: v3.9.6, v3.10.2

          Whether the primary key columns are always cached in memory.

        • The primary sort order, described by an array of objects, each specifying a field (attribute path) and a sort direction.

          • The sort direction.

            • true for ascending
            • false for descending

          • An attribute path. The . character denotes sub-attributes.

        • Introduced in: v3.9.6, v3.10.2

          Whether the primary sort columns are always cached in memory.

        • Possible values: "lz4", "none"

          Defines how the primary sort data is compressed.

          • "lz4": LZ4 fast compression
          • "none": no compression

        • An array of objects that describes which document attributes are stored in the View index for covering search queries, which means the data can be taken from the index directly and accessing the storage engine can be avoided.

          • Introduced in: v3.9.5, v3.10.2

            Whether stored values are always cached in memory.

          • Possible values: "lz4", "none"

            The compression type used for the internal column-store.

            • "lz4": LZ4 fast compression
            • "none": no compression

          • An array of strings with one or more document attribute paths.

        • The type of the View ("arangosearch").

          Example: "arangosearch"

        • Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers (segments) finish (0 = disabled).

        • Maximum number of writers (segments) cached in the pool (0 = disabled).

        • Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. 0 value turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (0 = disabled).

      • The name or type attribute is missing or invalid.

          Response Body application/json object

        • The HTTP response status code.

          Example: 400

        • A flag indicating that an error occurred.

          Example: true

        • A descriptive error message.

        • The ArangoDB error number for the error that occurred.

      • A View called name already exists.

          Response Body application/json object

        • The HTTP response status code.

          Example: 409

        • A flag indicating that an error occurred.

          Example: true

        • A descriptive error message.

        • The ArangoDB error number for the error that occurred.

      Examples

      curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view
{
  "name": "products",
  "type": "arangosearch"
}
      Show output
      HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 489
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "globallyUniqueId" : "h7F0F0D5E4468/70945", 
  "id" : "70945", 
  "name" : "products", 
  "type" : "arangosearch", 
  "cleanupIntervalStep" : 2, 
  "commitIntervalMsec" : 1000, 
  "consolidationIntervalMsec" : 1000, 
  "consolidationPolicy" : { 
    "type" : "tier", 
    "segmentsBytesFloor" : 2097152, 
    "segmentsBytesMax" : 5368709120, 
    "segmentsMax" : 10, 
    "segmentsMin" : 1, 
    "minScore" : 0 
  }, 
  "optimizeTopK" : [ ], 
  "primarySort" : [ ], 
  "primarySortCompression" : "lz4", 
  "storedValues" : [ ], 
  "writebufferActive" : 0, 
  "writebufferIdle" : 64, 
  "writebufferSizeMax" : 33554432, 
  "links" : { 
  } 
}

      Get information about a View

      GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view/:view-name
      Returns the basic information about a specific View.
      Path Parameters

      • The name of the database.

        Example: _system

      • The name of the View.

      Query Parameters
        HTTP Headers
          Responses

          • The basic information about the View.

              Response Body application/json object

            • The HTTP response status code.

              Example: 200

            • A flag indicating that no error occurred.

              Example: false

            • A unique identifier of the View. This is an internal property.

            • A unique identifier of the View (deprecated).

            • The name of the View.

              Example: "coll"

            • The type of the View ("arangosearch").

              Example: "arangosearch"

          • A View called view-name could not be found.

              Response Body application/json object

            • The HTTP response status code.

              Example: 404

            • A flag indicating that an error occurred.

              Example: true

            • A descriptive error message.

            • The ArangoDB error number for the error that occurred.

          Examples

          Using an identifier:

          curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/71063
          Show output
          HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 124
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "type" : "arangosearch", 
  "name" : "productsView", 
  "id" : "71063", 
  "globallyUniqueId" : "h7F0F0D5E4468/71063" 
}

          Using a name:

          curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView
          Show output
          HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 124
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "type" : "arangosearch", 
  "name" : "productsView", 
  "id" : "71203", 
  "globallyUniqueId" : "h7F0F0D5E4468/71203" 
}

          Get the properties of a View

          GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view/:view-name/properties
          Returns an object containing the definition of the View identified by view-name.
          Path Parameters

          • The name of the database.

            Example: _system

          • The name of the View.

          Query Parameters
            HTTP Headers
              Responses

              • An object with a full description of the specified View, including arangosearch View type-dependent properties.

                  Response Body application/json object

                • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disabled).

                • The HTTP response status code.

                  Example: 200

                • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disabled).

                • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disabled).

                • The consolidation policy to apply for selecting which segments should be merged.

                  • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
                  • If the bytes_accum type is used, then the threshold property is available.

                  • Introduced in: v3.12.7

                    The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

                    A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

                    On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

                    Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

                  • Introduced in: v3.12.7

                    The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

                    The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

                    The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

                    During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

                  • Maximum allowed size of all consolidated segments in bytes.

                  • A value in the range [0.0, 1.0]

                  • Possible values: "tier", "bytes_accum"

                    The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

                    • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
                    • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

                • A flag indicating that no error occurred.

                  Example: false

                • A unique identifier of the View. This is an internal property.

                • A unique identifier of the View (deprecated).

                • The name of the View.

                  Example: "coll"

                • Introduced in: v3.12.0

                  An array of strings defining sort expressions that can be optimized. This is also known as WAND optimization.

                • Introduced in: v3.9.6, v3.10.2

                  Whether the primary key columns are always cached in memory.

                • The primary sort order, described by an array of objects, each specifying a field (attribute path) and a sort direction.

                  • The sort direction.

                    • true for ascending
                    • false for descending

                  • An attribute path. The . character denotes sub-attributes.

                • Introduced in: v3.9.6, v3.10.2

                  Whether the primary sort columns are always cached in memory.

                • Possible values: "lz4", "none"

                  Defines how the primary sort data is compressed.

                  • "lz4": LZ4 fast compression
                  • "none": no compression

                • An array of objects that describes which document attributes are stored in the View index for covering search queries, which means the data can be taken from the index directly and accessing the storage engine can be avoided.

                  • Introduced in: v3.9.5, v3.10.2

                    Whether stored values are always cached in memory.

                  • Possible values: "lz4", "none"

                    The compression type used for the internal column-store.

                    • "lz4": LZ4 fast compression
                    • "none": no compression

                  • An array of strings with one or more document attribute paths.

                • The type of the View ("arangosearch").

                  Example: "arangosearch"

                • Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers (segments) finish (0 = disabled).

                • Maximum number of writers (segments) cached in the pool (0 = disabled).

                • Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. 0 value turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (0 = disabled).

              • The view-name path parameter is missing or invalid.

                  Response Body application/json object

                • The HTTP response status code.

                  Example: 400

                • A flag indicating that an error occurred.

                  Example: true

                • A descriptive error message.

                • The ArangoDB error number for the error that occurred.

              • A View called view-name could not be found.

                  Response Body application/json object

                • The HTTP response status code.

                  Example: 404

                • A flag indicating that an error occurred.

                  Example: true

                • A descriptive error message.

                • The ArangoDB error number for the error that occurred.

              Examples

              Using an identifier:

              curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/71321/properties
              Show output
              HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 670
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "writebufferSizeMax" : 33554432, 
  "writebufferIdle" : 64, 
  "id" : "71321", 
  "storedValues" : [ ], 
  "name" : "productsView", 
  "type" : "arangosearch", 
  "consolidationPolicy" : { 
    "type" : "tier", 
    "segmentsBytesFloor" : 2097152, 
    "segmentsBytesMax" : 5368709120, 
    "segmentsMax" : 10, 
    "segmentsMin" : 1, 
    "minScore" : 0 
  }, 
  "writebufferActive" : 0, 
  "links" : { 
    "books" : { 
      "analyzers" : [ 
        "identity" 
      ], 
      "fields" : { 
        "title" : { 
          "analyzers" : [ 
            "text_en" 
          ] 
        } 
      }, 
      "includeAllFields" : false, 
      "storeValues" : "none", 
      "trackListPositions" : false 
    } 
  }, 
  "commitIntervalMsec" : 1000, 
  "consolidationIntervalMsec" : 1000, 
  "optimizeTopK" : [ ], 
  "globallyUniqueId" : "h7F0F0D5E4468/71321", 
  "cleanupIntervalStep" : 2, 
  "primarySort" : [ ], 
  "primarySortCompression" : "lz4" 
}

              Using a name:

              curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView/properties
              Show output
              HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 670
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "writebufferSizeMax" : 33554432, 
  "writebufferIdle" : 64, 
  "id" : "71433", 
  "storedValues" : [ ], 
  "name" : "productsView", 
  "type" : "arangosearch", 
  "consolidationPolicy" : { 
    "type" : "tier", 
    "segmentsBytesFloor" : 2097152, 
    "segmentsBytesMax" : 5368709120, 
    "segmentsMax" : 10, 
    "segmentsMin" : 1, 
    "minScore" : 0 
  }, 
  "writebufferActive" : 0, 
  "links" : { 
    "books" : { 
      "analyzers" : [ 
        "identity" 
      ], 
      "fields" : { 
        "title" : { 
          "analyzers" : [ 
            "text_en" 
          ] 
        } 
      }, 
      "includeAllFields" : false, 
      "storeValues" : "none", 
      "trackListPositions" : false 
    } 
  }, 
  "commitIntervalMsec" : 1000, 
  "consolidationIntervalMsec" : 1000, 
  "optimizeTopK" : [ ], 
  "globallyUniqueId" : "h7F0F0D5E4468/71433", 
  "cleanupIntervalStep" : 2, 
  "primarySort" : [ ], 
  "primarySortCompression" : "lz4" 
}

              List all Views

              GET http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view
              Returns an object containing a listing of all Views in the current database, regardless of their type.
              Path Parameters

              • The name of the database.

                Example: _system

              Query Parameters
                HTTP Headers
                  Responses

                  • The list of Views.

                      Response Body application/json object

                    • The HTTP response status code.

                      Example: 200

                    • A flag indicating that no error occurred.

                      Example: false

                    • The result object.

                      • A unique identifier of the View. This is an internal property.

                      • A unique identifier of the View (deprecated).

                      • The name of the View.

                        Example: "coll"

                      • Possible values: "arangosearch", "search-alias"

                        The type of the View.

                  Examples

                  Return information about all Views:

                  curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view
                  Show output
                  HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 328
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : [ 
    { 
      "globallyUniqueId" : "h7F0F0D5E4468/181", 
      "id" : "181", 
      "name" : "demoView", 
      "type" : "arangosearch" 
    }, 
    { 
      "globallyUniqueId" : "h7F0F0D5E4468/71572", 
      "id" : "71572", 
      "name" : "productsView", 
      "type" : "search-alias" 
    }, 
    { 
      "globallyUniqueId" : "h7F0F0D5E4468/71573", 
      "id" : "71573", 
      "name" : "reviewsView", 
      "type" : "arangosearch" 
    } 
  ] 
}

                  Replace the properties of an arangosearch View

                  PUT http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view/:view-name/properties
                  Changes all properties of a View by replacing them, except for immutable properties.
                  Path Parameters

                  • The name of the database.

                    Example: _system

                  • The name of the View.

                  Query Parameters
                    HTTP Headers
                      Request Body application/json object

                      • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disable). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value causes a lot of disk space to be wasted. For the case where the consolidation policies rarely merge segments (i.e. few inserts/deletes), a higher value impacts performance without any added benefits.

                        Also see ArangoSearch cleanup.

                      • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disable). For the case where there are a lot of inserts/updates, a higher value causes the index not to account for them and memory usage continues to grow until the commit. A lower value impacts performance, including the case where there are no or only a few inserts/updates because of synchronous locking, and it wastes disk space for each commit call.

                        Also see ArangoSearch commits.

                      • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disable). For the case where there are a lot of data modification operations, a higher value could potentially have the data store consume more space and file handles. For the case where there are a few data modification operations, a lower value impacts performance due to no segment candidates being available for consolidation.

                        Also see ArangoSearch consolidation.

                      • The consolidation policy to apply for selecting which segments should be merged.

                        • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
                        • If the bytes_accum type is used, then the threshold property is available.

                        Also see ArangoSearch consolidation.

                        • Introduced in: v3.12.7

                          The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

                          A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

                          On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

                          Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

                        • Introduced in: v3.12.7

                          The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

                          The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

                          The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

                          During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

                        • Maximum allowed size of all consolidated segments in bytes.

                        • A value in the range [0.0, 1.0].

                        • Possible values: "tier", "bytes_accum"

                          The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

                          • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
                          • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

                      • Expects an object with the attribute keys being names of to be linked collections, and the link properties as attribute values. Example:

                        {
  "name": "arangosearch",
  "links": {
    "coll": {
      "fields": {
        "my_attribute": {
          "fields": {
            "my_sub_attribute": {
              "analyzers": ["text_en"]
            }
          }
        }
      }
    }
  }
}

                        See arangosearch View Link Properties for details.

                      Responses

                      • The View has been updated successfully.

                          Response Body application/json object

                        • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disabled).

                        • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disabled).

                        • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disabled).

                        • The consolidation policy to apply for selecting which segments should be merged.

                          • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
                          • If the bytes_accum type is used, then the threshold property is available.

                          • Introduced in: v3.12.7

                            The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

                            A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

                            On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

                            Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

                          • Introduced in: v3.12.7

                            The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

                            The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

                            The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

                            During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

                          • Maximum allowed size of all consolidated segments in bytes.

                          • A value in the range [0.0, 1.0]

                          • Possible values: "tier", "bytes_accum"

                            The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

                            • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
                            • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

                        • A unique identifier of the View. This is an internal property.

                        • A unique identifier of the View (deprecated).

                        • The name of the View.

                          Example: "coll"

                        • Introduced in: v3.12.0

                          An array of strings defining sort expressions that can be optimized. This is also known as WAND optimization.

                        • Introduced in: v3.9.6, v3.10.2

                          Whether the primary key columns are always cached in memory.

                        • The primary sort order, described by an array of objects, each specifying a field (attribute path) and a sort direction.

                          • The sort direction.

                            • true for ascending
                            • false for descending

                          • An attribute path. The . character denotes sub-attributes.

                        • Introduced in: v3.9.6, v3.10.2

                          Whether the primary sort columns are always cached in memory.

                        • Possible values: "lz4", "none"

                          Defines how the primary sort data is compressed.

                          • "lz4": LZ4 fast compression
                          • "none": no compression

                        • An array of objects that describes which document attributes are stored in the View index for covering search queries, which means the data can be taken from the index directly and accessing the storage engine can be avoided.

                          • Introduced in: v3.9.5, v3.10.2

                            Whether stored values are always cached in memory.

                          • Possible values: "lz4", "none"

                            The compression type used for the internal column-store.

                            • "lz4": LZ4 fast compression
                            • "none": no compression

                          • An array of strings with one or more document attribute paths.

                        • The type of the View ("arangosearch").

                          Example: "arangosearch"

                        • Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers (segments) finish (0 = disabled).

                        • Maximum number of writers (segments) cached in the pool (0 = disabled).

                        • Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. 0 value turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (0 = disabled).

                      • The view-name path parameter is missing or invalid.

                          Response Body application/json object

                        • The HTTP response status code.

                          Example: 400

                        • A flag indicating that an error occurred.

                          Example: true

                        • A descriptive error message.

                        • The ArangoDB error number for the error that occurred.

                      • A View called view-name could not be found.

                          Response Body application/json object

                        • The HTTP response status code.

                          Example: 404

                        • A flag indicating that an error occurred.

                          Example: true

                        • A descriptive error message.

                        • The ArangoDB error number for the error that occurred.

                      Examples

                      Replace the properties of an arangosearch View including any links with new properties. All mutable properties that are not specified are reset to their default values.

                      curl -X PUT --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/view/productsView/properties' <<'EOF'
{
  "cleanupIntervalStep": 12,
  "links": {
    "products": {
      "fields": {
        "description": {
          "analyzers": [
            "text_en"
          ]
        }
      }
    }
  }
}
EOF
                      Show output
                      HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 655
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "globallyUniqueId" : "h4F83C58DC4C5/71959", 
  "id" : "71959", 
  "name" : "productsView", 
  "type" : "arangosearch", 
  "cleanupIntervalStep" : 12, 
  "commitIntervalMsec" : 1000, 
  "consolidationIntervalMsec" : 1000, 
  "consolidationPolicy" : { 
    "type" : "tier", 
    "segmentsBytesFloor" : 2097152, 
    "segmentsBytesMax" : 5368709120, 
    "segmentsMax" : 10, 
    "segmentsMin" : 1, 
    "minScore" : 0 
  }, 
  "optimizeTopK" : [ ], 
  "primarySort" : [ ], 
  "primarySortCompression" : "lz4", 
  "storedValues" : [ ], 
  "writebufferActive" : 0, 
  "writebufferIdle" : 64, 
  "writebufferSizeMax" : 33554432, 
  "links" : { 
    "products" : { 
      "analyzers" : [ 
        "identity" 
      ], 
      "fields" : { 
        "description" : { 
          "analyzers" : [ 
            "text_en" 
          ] 
        } 
      }, 
      "includeAllFields" : false, 
      "storeValues" : "none", 
      "trackListPositions" : false 
    } 
  } 
}

                      Update the properties of an arangosearch View

                      PATCH http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view/:view-name/properties
                      Partially changes the properties of a View by updating the specified attributes.
                      Path Parameters

                      • The name of the database.

                        Example: _system

                      • The name of the View.

                      Query Parameters
                        HTTP Headers
                          Request Body application/json object

                          • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disable). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value causes a lot of disk space to be wasted. For the case where the consolidation policies rarely merge segments (i.e. few inserts/deletes), a higher value impacts performance without any added benefits.

                            Also see ArangoSearch cleanup.

                          • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disable). For the case where there are a lot of inserts/updates, a higher value causes the index not to account for them and memory usage continues to grow until the commit. A lower value impacts performance, including the case where there are no or only a few inserts/updates because of synchronous locking, and it wastes disk space for each commit call.

                            Also see ArangoSearch commits.

                          • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disable). For the case where there are a lot of data modification operations, a higher value could potentially have the data store consume more space and file handles. For the case where there are a few data modification operations, a lower value impacts performance due to no segment candidates being available for consolidation.

                            Also see ArangoSearch consolidation.

                          • The consolidation policy to apply for selecting which segments should be merged.

                            • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
                            • If the bytes_accum type is used, then the threshold property is available.

                            Also see ArangoSearch consolidation.

                            • Introduced in: v3.12.7

                              The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

                              A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

                              On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

                              Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

                            • Introduced in: v3.12.7

                              The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

                              The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

                              The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

                              During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

                            • Maximum allowed size of all consolidated segments in bytes.

                            • A value in the range [0.0, 1.0].

                            • Possible values: "tier", "bytes_accum"

                              The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

                              • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
                              • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

                          • Expects an object with the attribute keys being names of to be linked collections, and the link properties as attribute values. Example:

                            {
  "name": "arangosearch",
  "links": {
    "coll": {
      "fields": {
        "my_attribute": {
          "fields": {
            "my_sub_attribute": {
              "analyzers": ["text_en"]
            }
          }
        }
      }
    }
  }
}

                            See arangosearch View Link Properties for details.

                          Responses

                          • The View has been updated successfully.

                              Response Body application/json object

                            • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disabled).

                            • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disabled).

                            • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disabled).

                            • The consolidation policy to apply for selecting which segments should be merged.

                              • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
                              • If the bytes_accum type is used, then the threshold property is available.

                              • Introduced in: v3.12.7

                                The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

                                A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

                                On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

                                Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

                              • Introduced in: v3.12.7

                                The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

                                The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

                                The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

                                During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

                              • Maximum allowed size of all consolidated segments in bytes.

                              • A value in the range [0.0, 1.0]

                              • Possible values: "tier", "bytes_accum"

                                The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

                                • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
                                • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

                            • A unique identifier of the View. This is an internal property.

                            • A unique identifier of the View (deprecated).

                            • The name of the View.

                              Example: "coll"

                            • Introduced in: v3.12.0

                              An array of strings defining sort expressions that can be optimized. This is also known as WAND optimization.

                            • Introduced in: v3.9.6, v3.10.2

                              Whether the primary key columns are always cached in memory.

                            • The primary sort order, described by an array of objects, each specifying a field (attribute path) and a sort direction.

                              • The sort direction.

                                • true for ascending
                                • false for descending

                              • An attribute path. The . character denotes sub-attributes.

                            • Introduced in: v3.9.6, v3.10.2

                              Whether the primary sort columns are always cached in memory.

                            • Possible values: "lz4", "none"

                              Defines how the primary sort data is compressed.

                              • "lz4": LZ4 fast compression
                              • "none": no compression

                            • An array of objects that describes which document attributes are stored in the View index for covering search queries, which means the data can be taken from the index directly and accessing the storage engine can be avoided.

                              • Introduced in: v3.9.5, v3.10.2

                                Whether stored values are always cached in memory.

                              • Possible values: "lz4", "none"

                                The compression type used for the internal column-store.

                                • "lz4": LZ4 fast compression
                                • "none": no compression

                              • An array of strings with one or more document attribute paths.

                            • The type of the View ("arangosearch").

                              Example: "arangosearch"

                            • Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers (segments) finish (0 = disabled).

                            • Maximum number of writers (segments) cached in the pool (0 = disabled).

                            • Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. 0 value turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (0 = disabled).

                          • The view-name path parameter is missing or invalid.

                              Response Body application/json object

                            • The HTTP response status code.

                              Example: 400

                            • A flag indicating that an error occurred.

                              Example: true

                            • A descriptive error message.

                            • The ArangoDB error number for the error that occurred.

                          • A View called view-name could not be found.

                              Response Body application/json object

                            • The HTTP response status code.

                              Example: 404

                            • A flag indicating that an error occurred.

                              Example: true

                            • A descriptive error message.

                            • The ArangoDB error number for the error that occurred.

                          Examples

                          Update the properties of an arangosearch View, only changing one setting and removing a link. All other mutable properties that are not specified keep their current values.

                          curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - 'http://localhost:8529/_api/view/productsView/properties' <<'EOF'
{
  "cleanupIntervalStep": 12,
  "links": {
    "products": null
  }
}
EOF
                          Show output
                          HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 610
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "globallyUniqueId" : "h4F83C58DC4C5/72087", 
  "id" : "72087", 
  "name" : "productsView", 
  "type" : "arangosearch", 
  "cleanupIntervalStep" : 12, 
  "commitIntervalMsec" : 666, 
  "consolidationIntervalMsec" : 666, 
  "consolidationPolicy" : { 
    "type" : "tier", 
    "segmentsBytesFloor" : 2097152, 
    "segmentsBytesMax" : 5368709120, 
    "segmentsMax" : 10, 
    "segmentsMin" : 1, 
    "minScore" : 0 
  }, 
  "optimizeTopK" : [ ], 
  "primarySort" : [ ], 
  "primarySortCompression" : "lz4", 
  "storedValues" : [ ], 
  "writebufferActive" : 0, 
  "writebufferIdle" : 64, 
  "writebufferSizeMax" : 33554432, 
  "links" : { 
    "users" : { 
      "analyzers" : [ 
        "identity" 
      ], 
      "fields" : { 
      }, 
      "includeAllFields" : true, 
      "storeValues" : "none", 
      "trackListPositions" : false 
    } 
  } 
}

                          Rename a View

                          PUT http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view/:view-name/rename

                          Renames a View.

                          Renaming Views is not supported in cluster deployments.
                          Path Parameters

                          • The name of the database.

                            Example: _system

                          • The name of the View to rename.

                          Query Parameters
                            HTTP Headers
                              Request Body application/json object

                              • The new name for the View.

                              Responses

                              • The View has been renamed successfully.

                                  Response Body application/json object

                                • Wait at least this many commits between removing unused files in the ArangoSearch data directory (0 = disabled).

                                • Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (0 = disabled).

                                • Wait at least this many milliseconds between applying consolidationPolicy to consolidate the View data store and possibly release space on the filesystem (0 = disabled).

                                • The consolidation policy to apply for selecting which segments should be merged.

                                  • If the tier type is used, then the maxSkewThreshold and minDeletionRatio properties are available.
                                  • If the bytes_accum type is used, then the threshold property is available.

                                  • Introduced in: v3.12.7

                                    The skew describes how much segment files vary in file size. It is a number between 0.0 and 1.0 and is calculated by dividing the largest file size of a set of segment files by the total size. For example, the skew of a 200 MiB, 300 MiB, and 500 MiB segment file is 0.5 (500 / 1000).

                                    A large maxSkewThreshold value allows merging large segment files with smaller ones, consolidation occurs more frequently, and there are fewer segment files on disk at all times. While this may potentially improve the read performance and use fewer file descriptors, frequent consolidations cause a higher write load and thus a higher write amplification.

                                    On the other hand, a small threshold value triggers the consolidation only when there are a large number of segment files that don’t vary in size a lot. Consolidation occurs less frequently, reducing the write amplification, but it can result in a greater number of segment files on disk.

                                    Multiple combinations of candidate segments are checked and the one with the lowest skew value is selected for consolidation. The selection process picks the greatest number of segments that together have the lowest skew value while ensuring that the size of the new consolidated segment remains under the configured segmentsBytesMax.

                                  • Introduced in: v3.12.7

                                    The minDeletionRatio represents the minimum required deletion ratio in one or more segments to perform a cleanup of those segments. It is a number between 0.0 and 1.0.

                                    The deletion ratio is the percentage of deleted documents across one or more segment files and is calculated by dividing the number of deleted documents by the total number of documents in a segment or a group of segments. For example, if there is a segment with 1000 documents of which 300 are deleted and another segment with 1000 documents of which 700 are deleted, the deletion ratio is 0.5 (50%, calculated as 1000 / 2000).

                                    The minDeletionRatio threshold must be carefully selected. A smaller value leads to earlier cleanup of deleted documents from segments and thus reclamation of disk space but it generates a higher write load. A very large value lowers the write amplification but at the same time the system can be left with a large number of segment files with a high percentage of deleted documents that occupy disk space unnecessarily.

                                    During cleanup, the segment files are first arranged in decreasing order of their individual deletion ratios. Then the largest subset of segments whose collective deletion ratio is greater than or equal to minDeletionRatio is picked.

                                  • Maximum allowed size of all consolidated segments in bytes.

                                  • A value in the range [0.0, 1.0]

                                  • Possible values: "tier", "bytes_accum"

                                    The segment candidates for the “consolidation” operation are selected based upon several possible configurable formulas as defined by their types. The currently supported types are:

                                    • "tier": Consolidate based on segment byte size skew and live document count as dictated by the customization attributes.
                                    • "bytes_accum": Consolidate if and only if {threshold} > (segment_bytes + sum_of_merge_candidate_segment_bytes) / all_segment_bytes i.e. the sum of all candidate segment byte size is less than the total segment byte size multiplied by the {threshold}.

                                • A unique identifier of the View. This is an internal property.

                                • A unique identifier of the View (deprecated).

                                • The name of the View.

                                  Example: "coll"

                                • Introduced in: v3.12.0

                                  An array of strings defining sort expressions that can be optimized. This is also known as WAND optimization.

                                • Introduced in: v3.9.6, v3.10.2

                                  Whether the primary key columns are always cached in memory.

                                • The primary sort order, described by an array of objects, each specifying a field (attribute path) and a sort direction.

                                  • The sort direction.

                                    • true for ascending
                                    • false for descending

                                  • An attribute path. The . character denotes sub-attributes.

                                • Introduced in: v3.9.6, v3.10.2

                                  Whether the primary sort columns are always cached in memory.

                                • Possible values: "lz4", "none"

                                  Defines how the primary sort data is compressed.

                                  • "lz4": LZ4 fast compression
                                  • "none": no compression

                                • An array of objects that describes which document attributes are stored in the View index for covering search queries, which means the data can be taken from the index directly and accessing the storage engine can be avoided.

                                  • Introduced in: v3.9.5, v3.10.2

                                    Whether stored values are always cached in memory.

                                  • Possible values: "lz4", "none"

                                    The compression type used for the internal column-store.

                                    • "lz4": LZ4 fast compression
                                    • "none": no compression

                                  • An array of strings with one or more document attribute paths.

                                • The type of the View ("arangosearch").

                                  Example: "arangosearch"

                                • Maximum number of concurrent active writers (segments) that perform a transaction. Other writers (segments) wait till current active writers (segments) finish (0 = disabled).

                                • Maximum number of writers (segments) cached in the pool (0 = disabled).

                                • Maximum memory byte size per writer (segment) before a writer (segment) flush is triggered. 0 value turns off this limit for any writer (buffer) and data is flushed periodically based on the value defined for the flush thread (0 = disabled).

                              • The view-name path parameter is missing or invalid.

                                  Response Body application/json object

                                • The HTTP response status code.

                                  Example: 400

                                • A flag indicating that an error occurred.

                                  Example: true

                                • A descriptive error message.

                                • The ArangoDB error number for the error that occurred.

                              • A View called view-name could not be found.

                                  Response Body application/json object

                                • The HTTP response status code.

                                  Example: 404

                                • A flag indicating that an error occurred.

                                  Example: true

                                • A descriptive error message.

                                • The ArangoDB error number for the error that occurred.

                              Examples

                              curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/productsView/rename
{
  "name": "catalogView"
}
                              Show output
                              HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 492
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "globallyUniqueId" : "h7F0F0D5E4468/71887", 
  "id" : "71887", 
  "name" : "catalogView", 
  "type" : "arangosearch", 
  "cleanupIntervalStep" : 2, 
  "commitIntervalMsec" : 1000, 
  "consolidationIntervalMsec" : 1000, 
  "consolidationPolicy" : { 
    "type" : "tier", 
    "segmentsBytesFloor" : 2097152, 
    "segmentsBytesMax" : 5368709120, 
    "segmentsMax" : 10, 
    "segmentsMin" : 1, 
    "minScore" : 0 
  }, 
  "optimizeTopK" : [ ], 
  "primarySort" : [ ], 
  "primarySortCompression" : "lz4", 
  "storedValues" : [ ], 
  "writebufferActive" : 0, 
  "writebufferIdle" : 64, 
  "writebufferSizeMax" : 33554432, 
  "links" : { 
  } 
}

                              Drop a View

                              DELETE http://<EXTERNAL_ENDPOINT>:8529/_arango/v1/_db/:database-name/_api/view/:view-name
                              Deletes the View identified by view-name.
                              Path Parameters

                              • The name of the database.

                                Example: _system

                              • The name of the View to drop.

                              Query Parameters
                                HTTP Headers
                                  Responses

                                  • The View has been dropped successfully.

                                      Response Body application/json object

                                    • The HTTP response status code.

                                      Example: 200

                                    • A flag indicating that no error occurred.

                                      Example: false

                                    • The value true.

                                      Example: true

                                  • The view-name path parameter is missing or invalid.

                                      Response Body application/json object

                                    • The HTTP response status code.

                                      Example: 400

                                    • A flag indicating that an error occurred.

                                      Example: true

                                    • A descriptive error message.

                                    • The ArangoDB error number for the error that occurred.

                                  • A View called view-name could not be found.

                                      Response Body application/json object

                                    • The HTTP response status code.

                                      Example: 404

                                    • A flag indicating that an error occurred.

                                      Example: true

                                    • A descriptive error message.

                                    • The ArangoDB error number for the error that occurred.

                                  Examples

                                  Using an identifier:

                                  curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/view/72027
                                  Show output
                                  HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : true 
}

                                  Using a name:

                                  curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/view/productsView
                                  Show output
                                  HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 40
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff

{ 
  "error" : false, 
  "code" : 200, 
  "result" : true 
}

                                  On this page