MAmacrometa
Query

Create cursor from C8QL query

Queries are executed on the server and the results are returned to the client.

If the resulting queries returned a number of documents less than the batchSize (attribute set in query), then all documents are returned in the result JSON attribute.

If there are more documents than the defined batchSize, then the hasMore JSON attribute is set to true and the id JSON attribute contains the cursor ID. The cursor ID is then used in subsequent calls to the cursor API to retrieve all documents. This is repeated until the hasMore JSON attribute is set to false. The cursor ID will cease to exist after the seconds specified in the ttl attribute.

In the event that a search view is used in the query and this search view has been paused due to resource constraints, the x-gdn-view header is set with the list of all paused views.

post/_fabric/{fabric}/_api/cursor

Request

Path parameters

fabricstring string required

The name of the fabric.

Request body

batchSizeinteger

Sets the batch size of queries. This batch size decides how many results are returned as part of query output. If this option is not specified, default value is used. Maximum allowed for this parameter is 1000.

bindVarsobject

Key/value pairs representing the bind parameters.

countboolean

Indicates whether the number of documents in the result set should be returned in the "count" attribute of the result. Calculating the "count" attribute might have a performance impact for some queries in the future so this option is turned off by default, and "count" is only returned when requested.

querystring required

Contains the query string to be run.

ttlinteger

The amount of time for which the cursor is valid. The maximum value which can be specified, can be determined using GET /_api/limits/default API

Example request

{
  "query": "for u in testCollection return u"
}

Response

Successfully created the cursor.

codeinteger

HTTP response code.

errorboolean required

Flag if there is an error in response. False for this response.

countinteger

The total number of result documents available (only available if the query is run with the count attribute set)

extraobject

(Optional) A JSON object with extra information about the query result contained in the stats sub-attribute. For data-modification queries, the extra.stats sub-attribute contains the number of modified documents. If the ignoreErrors query option is specified, extra.stats also includes the number of documents that could not be modified due to an error.

hasMoreboolean

True indicates there are more results available for the cursor on the server. False indicates there are no more results available.

idstring

(Optional) ID of temporary cursor created on the server.

cachedboolean

A boolean flag indicating whether the query result is served from the query cache or not. If the query result is served from the query cache, the extra return attribute does not contain any stats sub-attribute and no profile sub-attribute.

Example response

{
  "code": 201,
  "count": 1,
  "extra": {
    "stats": {
      "writesExecuted": 0,
      "writesIgnored": 0,
      "scannedFull": 7,
      "scannedIndex": 0,
      "filtered": 0,
      "httpRequests": 0,
      "executionTime": 0.0006868839263916016,
      "peakMemoryUsage": 18396
    },
    "warnings": []
  },
  "id": "11176313",
  "result": [
    {
      "_id": "xxx/8753330",
      "_key": "8753330",
      "_rev": "_dpDmoaa--_",
      "item1": "data2"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.