ArangoDB v3.4 reached End of Life (EOL) and is no longer supported.

This documentation is outdated. Please see the most recent version here: Latest Docs

ArangoSearch View

A natively integrated AQL extension that allows one to:

  • evaluate together documents located in different collections
  • search documents based on AQL boolean expressions and functions
  • sort the result set based on how closely each document matched the search condition

Creating an ArangoSearch View

The ArangoSearch specific JSON definition for creating of a view is as follows:

Create an ArangoSearch view

creates an ArangoSearch view

POST /_api/view#ArangoSearch

A JSON object with these properties is required:

  • name: The name of the view.

  • type: The type of the view. must be equal to “arangosearch”

  • properties: The view properties. If specified, then properties should be a JSON object containing the following attributes:

    • cleanupIntervalStep: Wait at least this many commits between removing unused files in the ArangoSearch data directory (default: 10, to disable use: 0). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value will cause 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 will impact performance without any added benefits.
      Background: With every “commit” or “consolidate” operation a new state of the view internal data-structures is created on disk. Old states/snapshots are released once there are no longer any users remaining. However, the files for the released states/snapshots are left on disk, and only removed by “cleanup” operation.

    • consolidationIntervalMsec: Wait at least this many milliseconds between committing view data store changes and making documents visible to queries (default: 60000, to disable use: 0). For the case where there are a lot of inserts/updates, a lower value, until commit, will cause the index not to account for them and memory usage would continue to grow. For the case where there are a few inserts/updates, a higher value will impact performance and waste disk space for each commit call without any added benefits.
      Background: For data retrieval ArangoSearch views follow the concept of “eventually-consistent”, i.e. eventually all the data in ArangoDB will be matched by corresponding query expressions. The concept of ArangoSearch view “commit” operation is introduced to control the upper-bound on the time until document addition/removals are actually reflected by corresponding query expressions. Once a “commit” operation is complete all documents added/removed prior to the start of the “commit” operation will be reflected by queries invoked in subsequent ArangoDB transactions, in-progress ArangoDB transactions will still continue to return a repeatable-read state.

    • consolidationPolicy: The consolidation policy to apply for selecting which segments should be merged (default: {})
      Background: With each ArangoDB transaction that inserts documents one or more ArangoSearch internal segments gets created. Similarly for removed documents the segments that contain such documents will have these documents marked as ‘deleted’. Over time this approach causes a lot of small and sparse segments to be created. A “consolidation” operation selects one or more segments and copies all of their valid documents into a single new segment, thereby allowing the search algorithm to perform more optimally and for extra file handles to be released once old segments are no longer used.

    • type: 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 (default: “bytes_accum”):
    • bytes_accum: consolidate if and only if ({threshold} range [0.0, 1.0]): {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}

    • tier: consolidate based on segment byte size and live document count as dictated by the customization attributes.

    • links: The set of collection names associated with the properties.

    • [collection-name]: The link properties. If specified, then properties should be a JSON object containing the following attributes:

    • analyzers: The list of analyzers to be used for indexing of string values (default: [“identity”]).

    • fields: The field properties. If specified, then properties should be a JSON object containing the following attributes:

    • field-name: This is a recursive structure for the specific attribute path, potentially containing any of the following attributes: analyzers, includeAllFields, trackListPositions, storeValues Any attributes not specified are inherited from the parent.

    • includeAllFields: The flag determines whether or not to index all fields on a particular level of depth (default: false).

    • trackListPositions: The flag determines whether or not values in a lists should be treated separate (default: false).

    • storeValues: How should the view track the attribute values, this setting allows for additional value retrieval optimizations, one of:
    • none: Do not store values by the view
    • id: Store only information about value presence, to allow use of the EXISTS() function (default “none”).

Creates a new view with a given name and properties if it does not already exist.

Note: view can’t be created with the links. Please use PUT/PATCH for links management.

Return codes

  • 400: If the view-name is missing, then a HTTP 400 is returned.

  • 404: If the view-name is unknown, then a HTTP 404 is returned.

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view <<EOF
{ 
  "name" : "testViewBasics", 
  "type" : "arangosearch" 
}
EOF

HTTP/1.1 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Modifying an ArangoSearch View

The ArangoSearch specific JSON definition for modification of a view is as follows:

Update of All Possible Properties

All modifiable properties of a view may be set to the specified definition, (i.e. “make the view exactly like this”), via:

Change properties of an ArangoSearch view

changes properties of an ArangoSearch view

PUT /_api/view/{view-name}/properties#ArangoSearch

Path Parameters

  • view-name (required): The name of the view.

A JSON object with these properties is required:

  • properties: The view properties. If specified, then properties should be a JSON object containing the following attributes:

    • cleanupIntervalStep: Wait at least this many commits between removing unused files in the ArangoSearch data directory (default: 10, to disable use: 0). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value will cause 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 will impact performance without any added benefits.
      Background: With every “commit” or “consolidate” operation a new state of the view internal data-structures is created on disk. Old states/snapshots are released once there are no longer any users remaining. However, the files for the released states/snapshots are left on disk, and only removed by “cleanup” operation.

    • consolidationIntervalMsec: Wait at least this many milliseconds between committing view data store changes and making documents visible to queries (default: 60000, to disable use: 0). For the case where there are a lot of inserts/updates, a lower value, until commit, will cause the index not to account for them and memory usage would continue to grow. For the case where there are a few inserts/updates, a higher value will impact performance and waste disk space for each commit call without any added benefits.
      Background: For data retrieval ArangoSearch views follow the concept of “eventually-consistent”, i.e. eventually all the data in ArangoDB will be matched by corresponding query expressions. The concept of ArangoSearch view “commit” operation is introduced to control the upper-bound on the time until document addition/removals are actually reflected by corresponding query expressions. Once a “commit” operation is complete all documents added/removed prior to the start of the “commit” operation will be reflected by queries invoked in subsequent ArangoDB transactions, in-progress ArangoDB transactions will still continue to return a repeatable-read state.

    • consolidationPolicy: The consolidation policy to apply for selecting which segments should be merged (default: {})
      Background: With each ArangoDB transaction that inserts documents one or more ArangoSearch internal segments gets created. Similarly for removed documents the segments that contain such documents will have these documents marked as ‘deleted’. Over time this approach causes a lot of small and sparse segments to be created. A “consolidation” operation selects one or more segments and copies all of their valid documents into a single new segment, thereby allowing the search algorithm to perform more optimally and for extra file handles to be released once old segments are no longer used.

    • type: 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 (default: “bytes_accum”):
    • bytes_accum: consolidate if and only if ({threshold} range [0.0, 1.0]): {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}

    • tier: consolidate based on segment byte size and live document count as dictated by the customization attributes.

    • links: The set of collection names associated with the properties.

    • [collection-name]: The link properties. If specified, then properties should be a JSON object containing the following attributes:

    • analyzers: The list of analyzers to be used for indexing of string values (default: [“identity”]).

    • fields: The field properties. If specified, then properties should be a JSON object containing the following attributes:

    • field-name: This is a recursive structure for the specific attribute path, potentially containing any of the following attributes: analyzers, includeAllFields, trackListPositions, storeValues Any attributes not specified are inherited from the parent.

    • includeAllFields: The flag determines whether or not to index all fields on a particular level of depth (default: false).

    • trackListPositions: The flag determines whether or not values in a lists should be treated separate (default: false).

    • storeValues: How should the view track the attribute values, this setting allows for additional value retrieval optimizations, one of:
    • none: Do not store values by the view
    • id: Store only information about value presence, to allow use of the EXISTS() function (default “none”).

Changes the properties of a view.

On success an object with the following attributes is returned:

  • id: The identifier of the view
  • name: The name of the view
  • type: The view type
  • all additional arangosearch view implementation specific properties

Return codes

  • 400: If the view-name is missing, then a HTTP 400 is returned.

  • 404: If the view-name is unknown, then a HTTP 404 is returned.

Examples

shell> curl -X PUT --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/products/properties <<EOF
{ 
  "locale" : "en" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body

Update of Specific Properties (delta)

Specific modifiable properties of a view may be set to the specified values, (i.e. “change only these properties to the specified values”), via:

Partially changes properties of an ArangoSearch view

partially changes properties of an ArangoSearch view

PATCH /_api/view/{view-name}/properties#ArangoSearch

Path Parameters

  • view-name (required): The name of the view.

A JSON object with these properties is required:

  • properties: The view properties. If specified, then properties should be a JSON object containing the following attributes:

    • cleanupIntervalStep: Wait at least this many commits between removing unused files in the ArangoSearch data directory (default: 10, to disable use: 0). For the case where the consolidation policies merge segments often (i.e. a lot of commit+consolidate), a lower value will cause 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 will impact performance without any added benefits.
      Background: With every “commit” or “consolidate” operation a new state of the view internal data-structures is created on disk. Old states/snapshots are released once there are no longer any users remaining. However, the files for the released states/snapshots are left on disk, and only removed by “cleanup” operation.

    • consolidationIntervalMsec: Wait at least this many milliseconds between committing view data store changes and making documents visible to queries (default: 60000, to disable use: 0). For the case where there are a lot of inserts/updates, a lower value, until commit, will cause the index not to account for them and memory usage would continue to grow. For the case where there are a few inserts/updates, a higher value will impact performance and waste disk space for each commit call without any added benefits.
      Background: For data retrieval ArangoSearch views follow the concept of “eventually-consistent”, i.e. eventually all the data in ArangoDB will be matched by corresponding query expressions. The concept of ArangoSearch view “commit” operation is introduced to control the upper-bound on the time until document addition/removals are actually reflected by corresponding query expressions. Once a “commit” operation is complete all documents added/removed prior to the start of the “commit” operation will be reflected by queries invoked in subsequent ArangoDB transactions, in-progress ArangoDB transactions will still continue to return a repeatable-read state.

    • consolidationPolicy: The consolidation policy to apply for selecting which segments should be merged (default: {})
      Background: With each ArangoDB transaction that inserts documents one or more ArangoSearch internal segments gets created. Similarly for removed documents the segments that contain such documents will have these documents marked as ‘deleted’. Over time this approach causes a lot of small and sparse segments to be created. A “consolidation” operation selects one or more segments and copies all of their valid documents into a single new segment, thereby allowing the search algorithm to perform more optimally and for extra file handles to be released once old segments are no longer used.

    • type: 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 (default: “bytes_accum”):
    • bytes_accum: consolidate if and only if ({threshold} range [0.0, 1.0]): {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}

    • tier: consolidate based on segment byte size and live document count as dictated by the customization attributes.

    • links: The set of collection names associated with the properties.

    • [collection-name]: The link properties. If specified, then properties should be a JSON object containing the following attributes:

    • analyzers: The list of analyzers to be used for indexing of string values (default: [“identity”]).

    • fields: The field properties. If specified, then properties should be a JSON object containing the following attributes:

    • field-name: This is a recursive structure for the specific attribute path, potentially containing any of the following attributes: analyzers, includeAllFields, trackListPositions, storeValues Any attributes not specified are inherited from the parent.

    • includeAllFields: The flag determines whether or not to index all fields on a particular level of depth (default: false).

    • trackListPositions: The flag determines whether or not values in a lists should be treated separate (default: false).

    • storeValues: How should the view track the attribute values, this setting allows for additional value retrieval optimizations, one of:
    • none: Do not store values by the view
    • id: Store only information about value presence, to allow use of the EXISTS() function (default “none”).

Changes the properties of a view.

On success an object with the following attributes is returned:

  • id: The identifier of the view
  • name: The name of the view
  • type: The view type
  • all additional arangosearch view implementation specific properties

Return codes

  • 400: If the view-name is missing, then a HTTP 400 is returned.

  • 404: If the view-name is unknown, then a HTTP 404 is returned.

Examples

shell> curl -X PATCH --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/view/products/properties <<EOF
{ 
  "locale" : "en" 
}
EOF

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff
Show response body
❮  Retrieving

© ArangoDB - the native multi-model NoSQL database