--- title: "Create cursor from C8QL query" method: POST path: "/_fabric/{fabric}/_api/cursor" tags: ["Query"] --- # Create cursor from C8QL query `POST /_fabric/{fabric}/_api/cursor` ## Request - The document declares no server URL. - Auth: one of: - API key in header `Authorization` - HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) 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. ## Path parameters - `fabric` string, string, required ## Request body - ApiCursor - `batchSize` integer: 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*. - `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. - `options` ApiCursorOpts: Key/value object with extra options for the query. - `failOnWarning` boolean: When set to *true*, the query throws an exception and abort instead of producing a warning. This option should be used during development to catch potential issues early. When the attribute is set to *false*, warnings are not propagated to exceptions and are returned with the query result. - `fullCount` boolean: If set to *true* and the query contains a *LIMIT* clause, the result has an *extra* attribute with the sub-attributes *stats* and *fullCount*, `{ ... , "extra": { "stats": { "fullCount": 123 } } }`. The *fullCount* attribute contains the number of documents in the result before the last top-level LIMIT in the query is applied. It can be used to count the number of documents that match certain filter criteria, but only return a subset of them, in one go. It is thus similar to MySQL's *SQL_CALC_FOUND_ROWS* hint. Note that setting the option disables a few LIMIT optimizations and may lead to more documents being processed and thus make queries run longer. Note that the *fullCount* attribute may only be present in the result if the query has a top-level LIMIT clause and the LIMIT clause is actually used in the query. - `intermediateCommitCount` integer: Maximum number of operations after which an intermediate commit is performed automatically. **Note:** Use this option cautiously. The transactions are commited after every specific record count. In case of error, already commited records are not rolled back. - `intermediateCommitSize` integer: Maximum total size of operations after which an intermediate commit is performed automatically. **Note:** Use this option cautiously. The transactions are commited after every specific query memory size. In case of error, already commited records are not rolled back. - `maxTransactionSize` integer: Transaction size limit in bytes. - `maxWarningCount` integer: Limits the maximum number of warnings returned by a query. - `profile` integer: If set to *true* or *1*, the additional query profiling information is returned in the sub-attribute *profile* of the *extra* return attribute, if the query result is not served from the query cache. If set to *2* the query includes execution stats per query plan node in sub-attribute *stats.nodes* of the *extra* return attribute. Additionally the query plan is returned in the sub-attribute *extra.plan*. - `skipInaccessibleCollections` boolean: C8QL queries (especially graph traversals) treat collections to which a user has no access rights as if these collections were empty. Instead of returning a forbidden access error, your query runs normally. - `stream` boolean: Specify *true* and the query runs as a **stream**. The query result is not stored on the server, but calculated on the fly. *Warnnig*: long-running queries need to hold the collection locks for as long as the query cursor exists. When set to *false* a query is run right away in its entirety. In that case query results are either returned right away (if the result set is small enough), or stored on the database instance and accessible via the cursor API (with respect to the `ttl`). It is advisable to *only* use this option on short-running queries or without exclusive locks. Query statistics, warnings and profiling data is only available after the query is finished. - `optimizer.rules` string[]: An array of to-be-included or to-be-excluded optimizer rules can be put into this attribute, telling the optimizer to include or exclude specific rules. To disable a rule, prefix its name with a `-`, to enable a rule, prefix it with a `+`. There is also a pseudo-rule `all`, which matches all optimizer rules. - `query` string, required: Contains the query string to be run. - `ttl` integer: 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 ## 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)