---
title: "Create cursor from SQL query."
method: POST
path: "/_fabric/{fabric}/_api/cursor/sql"
tags: ["Query"]
---

# Create cursor from SQL query.

`POST /_fabric/{fabric}/_api/cursor/sql`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/macrometa/apis/macrometa-api-reference/docs/_fabric/:fabric/_api/cursor/sql/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Path parameters

- `fabric` string, string, required

## Request body

- SqlApiCursor
  - `batchSize` integer: Sets the batch size of queries. This batch size decides how many results are returned as part of query output.
  - `bindVars` object: Key/value pairs representing the bind parameters.
  - `count` boolean: 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.
  - `query` string, required: Query to run.
  - `ttl` integer: 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.

## Response `201`

Successfully created the cursor.

- ApiCursorRc201
  - `code` integer: HTTP response code.
  - `error` boolean, required: Flag if there is an error in response. *False* for this response.
  - `count` integer: The total number of result documents available (only available if the query is run with the *count* attribute set)
  - `extra` object: (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.
  - `hasMore` boolean: *True* indicates there are more results available for the cursor on the server. *False* indicates there are no more results available.
  - `id` string: (Optional) ID of temporary cursor created on the server.
  - `cached` boolean: 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.
  - `result` unknown[]: An array of result documents (might be empty if query has no results).
    - unknown

## Other responses

- `400`: Failed due to missing or malformed data. Verify that all parameters are complete.
- `404`: Failed to find specified fabric or collection.

---

[API](https://skmtc.dev/macrometa/apis/macrometa-api-reference.md) - [All operations](https://skmtc.dev/macrometa/apis/macrometa-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/macrometa/apis/macrometa-api-reference/revisions/2006b6d7f31d?raw)