MAmacrometa
Query

Create cursor from SQL query.

To more efficiently batch communication, results of SQL queries are returned as cursors. Each REST API call returns a portion of the documents in a batch and indicates if this is the final batch. Batches are sent until the batch with the final indicator.

Depending on the query, the total number of documents in the result set might not be known in advance.

In order to free resources, delete the cursor as soon as it is no longer needed.

post/_fabric/{fabric}/_api/cursor/sql

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.

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

Query to run.

ttlinteger

The cursor is automatically removed from the server after the specified amount of time. This is useful to ensure garbage collection of cursors that are not fully fetched by clients.

Example request

{
  "query": "SELECT name FROM users"
}

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.