Grist Octri Preview
POST/docs/{docId}/sql

Run an SQL query against a document, with options or parameters

Execute a read-only SQL SELECT query with support for parameterized queries and custom timeouts. All Grist documents are SQLite databases, and queries are executed directly against SQLite with security restrictions.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 3 body fields
docIdstringrequired
A string id (UUID)

Query options

argsarray<number>optional
Parameters for the query.
sqlstringrequired
The SQL query to run. Must be a single SELECT statement, with no trailing semicolon. WITH clauses are permitted. All Grist documents are currently SQLite databases, and the SQL query is interpreted and run by SQLite, with various defensive measures. Statements that would modify the database are not supported.
timeoutnumberoptional
Timeout after which operations on the document will be interrupted. Specified in milliseconds. Defaults to 1000 (1 second). This default is controlled by an optional environment variable read by the Grist app, GRIST_SQL_TIMEOUT_MSEC. The default cannot be exceeded, only reduced.

1 status code
200The result set for the query.
recordsarray<object>required
statementstringrequired
A copy of the SQL statement.