ArangoSearch View

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”. This option is immutable.

  • links: Expects an object with the attribute keys being names of to be linked collections, and the link properties as attribute values. See ArangoSearch View Link Properties for details.

  • primarySort: A primary sort order can be defined 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 ("asc for ascending, "desc" for descending): [ { "field": "attr", "direction": "asc"}, … ]

  • cleanupIntervalStep: Wait at least this many commits between removing unused files in the ArangoSearch data directory (default: 2, 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.

  • commitIntervalMsec: Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (default: 1000, 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.

  • consolidationIntervalMsec: Wait at least this many milliseconds between applying ‘consolidationPolicy’ to consolidate View data store and possibly release space on the filesystem (default: 10000, to disable use: 0). 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 will impact performance due to no segment candidates available for consolidation.
    Background: For data modification ArangoSearch Views follow the concept of a “versioned data store”. Thus old versions of data may be removed once there are no longer any users of the old data. The frequency of the cleanup and compaction operations are governed by ‘consolidationIntervalMsec’ and the candidates for compaction are selected via ‘consolidationPolicy’.

  • 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.
    Sub-properties:
  • type (string, optional): 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" (default): consolidate based on segment byte size and live document count as dictated by the customization attributes. If this type is used, then below segments* and minScore properties are available.
    • "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}. If this type is used, then below threshold property is available.
  • threshold (number, optional): value in the range [0.0, 1.0]
  • segmentsBytesFloor (number, optional): Defines the value (in bytes) to treat all smaller segments as equal for consolidation selection (default: 2097152)
  • segmentsBytesMax (number, optional): Maximum allowed size of all consolidated segments in bytes (default: 5368709120)
  • segmentsMax (number, optional): The maximum number of segments that will be evaluated as candidates for consolidation (default: 10)
  • segmentsMin (number, optional): The minimum number of segments that will be evaluated as candidates for consolidation (default: 1)
  • minScore (number, optional): (default: 0)

  • writebufferIdle: Maximum number of writers (segments) cached in the pool (default: 64, use 0 to disable, immutable)

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

  • writebufferSizeMax: 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 will be flushed periodically based on the value defined for the flush thread (ArangoDB server startup option). 0 value should be used carefully due to high potential memory consumption (default: 33554432, use 0 to disable, immutable)

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

Return codes

  • 400: If the name or type attribute are missing or invalid, then an HTTP 400 error is returned.

  • 409: If a View called name already exists, then an HTTP 409 error 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
x-content-type-options: nosniff
content-type: application/json

Show response body

Return information about a View

returns a View

GET /_api/view/{view-name}

Path Parameters

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

The result is an object briefly describing the View with the following attributes:

  • id: The identifier of the View
  • name: The name of the View
  • type: The type of the View as string

Return codes

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

Examples

Using an identifier:

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/72025

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body

Using a name:

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/testView

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body

Read properties of a View

reads the properties of the specified View

GET /_api/view/{view-name}/properties

Path Parameters

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

Returns an object containing the definition of the View identified by view-name.

The result is an object with a full description of a specific View, including View type dependent 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

Using an identifier:

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/72033/properties

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body

Using a name:

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view/products/properties

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body

List all Views

returns all Views

GET /_api/view

Returns an object containing a listing of all Views in a database, regardless of their type. It is an array of objects with the following attributes:

  • id
  • name
  • type

Return codes

  • 200: The list of Views

Examples

Return information about all Views:

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/view

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body

Change properties of an ArangoSearch View

changes all 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:

  • links: Expects an object with the attribute keys being names of to be linked collections, and the link properties as attribute values. See ArangoSearch View Link Properties for details.

  • cleanupIntervalStep: Wait at least this many commits between removing unused files in the ArangoSearch data directory (default: 2, 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.

  • commitIntervalMsec: Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (default: 1000, 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.

  • consolidationIntervalMsec: Wait at least this many milliseconds between applying ‘consolidationPolicy’ to consolidate View data store and possibly release space on the filesystem (default: 10000, to disable use: 0). 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 will impact performance due to no segment candidates available for consolidation.
    Background: For data modification ArangoSearch Views follow the concept of a “versioned data store”. Thus old versions of data may be removed once there are no longer any users of the old data. The frequency of the cleanup and compaction operations are governed by ‘consolidationIntervalMsec’ and the candidates for compaction are selected via ‘consolidationPolicy’.

  • 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.
    Sub-properties:
  • type (string, optional): 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" (default): consolidate based on segment byte size and live document count as dictated by the customization attributes. If this type is used, then below segments* and minScore properties are available.
    • "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}. If this type is used, then below threshold property is available.
  • threshold (number, optional): value in the range [0.0, 1.0]
  • segmentsBytesFloor (number, optional): Defines the value (in bytes) to treat all smaller segments as equal for consolidation selection (default: 2097152)
  • segmentsBytesMax (number, optional): Maximum allowed size of all consolidated segments in bytes (default: 5368709120)
  • segmentsMax (number, optional): The maximum number of segments that will be evaluated as candidates for consolidation (default: 10)
  • segmentsMin (number, optional): The minimum number of segments that will be evaluated as candidates for consolidation (default: 1)
  • minScore (number, optional): (default: 0)

Changes the properties of a View by replacing them.

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
x-content-type-options: nosniff
content-type: application/json

Show response body

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:

  • links: Expects an object with the attribute keys being names of to be linked collections, and the link properties as attribute values. See ArangoSearch View Link Properties for details.

  • cleanupIntervalStep: Wait at least this many commits between removing unused files in the ArangoSearch data directory (default: 2, 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.

  • commitIntervalMsec: Wait at least this many milliseconds between committing View data store changes and making documents visible to queries (default: 1000, 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.

  • consolidationIntervalMsec: Wait at least this many milliseconds between applying ‘consolidationPolicy’ to consolidate View data store and possibly release space on the filesystem (default: 10000, to disable use: 0). 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 will impact performance due to no segment candidates available for consolidation.
    Background: For data modification ArangoSearch Views follow the concept of a “versioned data store”. Thus old versions of data may be removed once there are no longer any users of the old data. The frequency of the cleanup and compaction operations are governed by ‘consolidationIntervalMsec’ and the candidates for compaction are selected via ‘consolidationPolicy’.

  • 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.
    Sub-properties:
  • type (string, optional): 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" (default): consolidate based on segment byte size and live document count as dictated by the customization attributes. If this type is used, then below segments* and minScore properties are available.
    • "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}. If this type is used, then below threshold property is available.
  • threshold (number, optional): value in the range [0.0, 1.0]
  • segmentsBytesFloor (number, optional): Defines the value (in bytes) to treat all smaller segments as equal for consolidation selection (default: 2097152)
  • segmentsBytesMax (number, optional): Maximum allowed size of all consolidated segments in bytes (default: 5368709120)
  • segmentsMax (number, optional): The maximum number of segments that will be evaluated as candidates for consolidation (default: 10)
  • segmentsMin (number, optional): The minimum number of segments that will be evaluated as candidates for consolidation (default: 1)
  • minScore (number, optional): (default: 0)

Changes the properties of a View by updating the specified attributes.

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
x-content-type-options: nosniff
content-type: application/json

Show response body

Rename a View

renames a View

PUT /_api/view/{view-name}/rename

Path Parameters

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

Renames a View. Expects an object with the attribute(s)

  • name: The new name

It returns an object with the attributes

  • id: The identifier of the View.
  • name: The new name of the View.
  • type: The View type.

Note: This method is not available in a cluster.

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/products1/rename <<EOF
{ 
  "name" : "viewNewName" 
}
EOF

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body

Drops a View

drops a View

DELETE /_api/view/{view-name}

Path Parameters

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

Drops the View identified by view-name.

If the View was successfully dropped, an object is returned with the following attributes:

  • error: false
  • id: The identifier of the dropped View

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

Using an identifier:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/view/72017

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body

Using a name:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/view/testView

HTTP/1.1 OK
x-content-type-options: nosniff
content-type: application/json

Show response body