SDBQL Queries
POST
/_api/database/:db/cursor
Execute an SDBQL query.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| query | string | The SDBQL query string. | Yes |
| bindVars | object | Key-value pairs for bind parameters. | No |
| batchSize | integer | Max documents per batch. Default: 100. | No |
{"query": "FOR d IN users RETURN d", "batchSize": 50}
Response
200 OK
application/json
{
"result": [{"_key": "...", "...": "..."}, "..."],
"count": 50,
"hasMore": true,
"id": "cursor_123",
"executionTimeMs": 1.5
}
POST
/_api/database/:db/explain
Explain query execution plan.
Request Body Options
| Field | Type | Description | Required |
|---|---|---|---|
| query | string | The SDBQL query to explain. | Yes |
| bindVars | object | Key-value pairs for bind parameters. | No |
PUT
/_api/cursor/:id
Fetch next batch of results for a cursor.
Response
200 OK
application/json
{
"result": ["...", "..."],
"count": 50,
"hasMore": false,
"id": null,
"cached": true
}
DELETE
/_api/cursor/:id
Close a cursor and free resources.
Response
204 No Content
SQL Compatibility
Execute SQL queries that get translated to SDBQL automatically.
POST
/_api/database/:db/sql
Execute a SQL query by translating it to SDBQL and running it.
Request Body
| Field | Type | Description | Required |
|---|---|---|---|
| query | string | The SQL query string. | Yes |
| bind_vars | object | Key-value pairs for bind parameters. | No |
| dry_run | boolean | If true, return translated SDBQL without executing. | No |
Example Request
{"query": "SELECT * FROM users WHERE age > 18 ORDER BY name LIMIT 10"}
Response
200 OK
application/json
{
"result": [{"_key": "123", "name": "Alice", "age": 25}, ...],
"sdbql": "FOR doc IN users FILTER doc.age > 18 SORT doc.name LIMIT 10 RETURN doc"
}
POST
/_api/sql/translate
Translate SQL to SDBQL without executing. Useful for learning SDBQL or debugging.
Example Request
{"query": "SELECT name, email FROM users WHERE active = true"}
Response
200 OK
application/json
{
"sql": "SELECT name, email FROM users WHERE active = true",
"sdbql": "FOR doc IN users FILTER doc.active == true RETURN {name: doc.name, email: doc.email}"
}
Supported SQL Features
SELECT / SELECT DISTINCT
WHERE clauses
ORDER BY
LIMIT / OFFSET
GROUP BY
HAVING
JOIN (INNER/LEFT)
Aggregate functions