diff --git a/api/grist.yml b/api/grist.yml index e7d7ec570..24fe3e01f 100644 --- a/api/grist.yml +++ b/api/grist.yml @@ -1077,6 +1077,72 @@ paths: 200: description: "Success." + /docs/{docId}/sql: + get: + tags: + - sql + summary: "Run an SQL query against a document" + parameters: + - in: path + name: docId + schema: + $ref: "#/components/schemas/DocKey" + required: true + - in: query + name: q + schema: + type: string + description: "The SQL query to run. This GET endpoint is a simplified version of the corresponding POST endpoint, without support for parameters or options. See the POST endpoint for details of what's allowed in the SQL query string." + responses: + 200: + description: "The result set for the query." + content: + application/json: + schema: + $ref: "#/components/schemas/SqlResultSet" + post: + tags: + - sql + summary: "Run an SQL query against a document, with options or parameters" + parameters: + - in: path + name: docId + schema: + $ref: "#/components/schemas/DocKey" + required: true + requestBody: + description: "Query options" + content: + application/json: + schema: + type: object + required: + - sql + properties: + sql: + type: string + description: "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." + example: "select * from Pets where popularity >= ?" + args: + type: array + items: + oneOf: + - type: number + - type: string + description: "Parameters for the query." + example: [ 50 ] + timeout: + type: number + description: "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." + example: 500 + responses: + 200: + description: "The result set for the query." + content: + application/json: + schema: + $ref: "#/components/schemas/SqlResultSet" + tags: - name: orgs description: "Team sites and personal spaces are called 'orgs' in the API." @@ -1966,6 +2032,36 @@ components: example: 1 fields: $ref: "#/components/schemas/AttachmentMetadata" + SqlResultSet: + type: object + required: + - statement + - records + properties: + statement: + type: string + description: "A copy of the SQL statement." + example: "select * from Pets ..." + records: + type: array + items: + type: object + required: + - fields + properties: + fields: + type: object + example: + - + fields: + id: 1 + pet: cat + popularity: 67 + - + fields: + id: 2 + pet: dog + popularity: 95 parameters: filterQueryParam: in: query diff --git a/help/api.md b/help/api.md index c26528204..478a9f08a 100644 --- a/help/api.md +++ b/help/api.md @@ -27,6 +27,9 @@ toc: - title: "/attachments" url: "#tag/attachments" + - + title: "/sql" + url: "#tag/sql" - title: "/webhooks" url: "#tag/webhooks" @@ -38,7 +41,7 @@ toc:
-
API docs by Redocly
API docs by Redocly
required
Array of objects

Responses

Request samples

Content type
application/json
{
  • "columns": [
    • {
      • "id": "pet",
      • "fields": {
        • "label": "Pet"
        }
      },
    • {
      • "id": "popularity",
      • "fields": {
        • "label": "Popularity ❤",
        • "type": "Int"
        }
      }
    ]
}

Add or update columns of a table

Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

tableId
required
string

name of a table (normalized)

-
query Parameters
noadd
boolean

Set to true to prohibit adding records.

-
noupdate
boolean

Set to true to prohibit updating records.

+
query Parameters
noadd
boolean

Set to true to prohibit adding columns.

+
noupdate
boolean

Set to true to prohibit updating columns.

replaceall
boolean

Set to true to remove existing columns (except the hidden ones) that are not specified in the request body.

Request Body schema: application/json

The columns to add or update. We check whether the specified column ID exists: if so, the column is updated with the provided data, otherwise a new column is created. Also note that some query parameters alter this behavior.

@@ -235,9 +238,18 @@ Also note that some query parameters alter this behavior.

webhookId
required
string

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Empty a document's queue of undelivered payloads

Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

Responses

+

sql

Run an SQL query against a document

Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

+
query Parameters
q
string

The SQL query to run. This GET endpoint is a simplified version of the corresponding POST endpoint, which allows specifying parameters and options in the request body.

+

Responses

Response samples

Content type
application/json
{
  • "statement": "select * from Pets ...",
  • "records": [
    • {
      • "fields": {
        • "id": 1,
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "id": 2,
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}

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

Authorizations:
API Key
path Parameters
docId
required
string (DocKey)

A string id (UUID)

+
Request Body schema: application/json

Query options

+
sql
required
string

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.

+
Array of numbers or strings

Parameters for the query.

+
timeout
number

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.

+

Responses

Request samples

Content type
application/json
{
  • "sql": "select * from Pets where popularity >= ?",
  • "args": [
    • 50
    ],
  • "timeout": 500
}

Response samples

Content type
application/json
{
  • "statement": "select * from Pets ...",
  • "records": [
    • {
      • "fields": {
        • "id": 1,
        • "pet": "cat",
        • "popularity": 67
        }
      },
    • {
      • "fields": {
        • "id": 2,
        • "pet": "dog",
        • "popularity": 95
        }
      }
    ]
}