Snowflake SQL API Reference

This topic documents the operations, requests, and responses for the SQL API.

In this Topic:

Operations

POST /api/statements

To submit one or more SQL statements for execution, send a POST request to /api/statements. You can specify that the statement should be executed asynchronously, and you can specify the number of rows to return per page.

Request Syntax

POST /api/statements
(request body)

Query Parameters

Parameter

Description

requestId

(Optional) Unique ID (a UUID) of the API request. See Assigning a Unique Request ID for Resubmitting Requests.

async

(Optional) Set to true to execute the statement asynchronously and return the statement handle.

If the parameter is not specified or is set to false, a statement is executed and the results are returned if the execution is completed in 45 seconds. If the statement execution takes longer to complete, the statement handle is returned.

Note that if statement execution completes, the results include at most the number of rows specified by the pageSize parameter. If the numRows field in ResultSet_resultSetMetaData indicates that there are additional rows of results, see Retrieving Additional Pages of Results.

pageSize

(Optional) Number of rows to return per page. The page size can range from the minimum supported number (10) to the maximum supported number (10000) of rows per page. By default, the number of rows returned varies, depending on the execution of the statement.

Note: If the query returns a large number of rows, set this parameter. Otherwise, the number of rows may exceed the default number of rows in a page.

nullable

(Optional) Set to false to return a SQL NULL value as the string "null", rather than as the value null.

By default, SQL NULL values are returned as the value null:

"data" : [ [ "0", null ], ... ]

Setting this query parameter to false (e.g. /api/statements?nullable=false returns a SQL NULL value as the string "null":

"data" : [ [ "0", "null" ], ... ]

Request Headers

The request must include the headers listed in Request Headers for All Operations.

Request Body

(Required) The request body must contain the object specified in Body of the POST Request to /api/statements/.

Response

This operation can return the response codes listed below.

Code

Description

200

The statement was executed successfully.

For this response code, the response can have the following headers:

If a single SQL statement was submitted in the request, the body of the response contains a ResultSet object containing the requested data.

Note

If the code field in the response is set to 391908, the result set is too large, . and the response does not include the entire result set.

See Determining If the Result Set Page Size Exceeds the Limit for details.

The following is an example of a response for a single SQL statement in which the results fit in a single page, where {handle} is the statement handle and {id1}, {id2}, and {id3} are uniquely generated request IDs:

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:06:24 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=10>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=10>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 0,
    "pageSize" : 10,
    "numPages" : 1,
    "numRows" : 4,
    "format" : "json",
    "rowType" : [ {
      "name" : "COLUMN1",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 4,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16,
      "collation" : null
    }, {
      "name" : "COLUMN2",
      "database" : "",
      "schema" : "",
      "table" : "\"VALUES\"",
      "scale" : 0,
      "precision" : 1,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    } ]
  },
  "data" : [ [ "0", "test", "2" ], [ "1", "test", "3" ], [ "2", "test", "4" ], [ "3", "test", "5" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id3}&pageSize=10",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151584132
}

The following is an example of a response for a single SQL statement in which the results need to be returned in multiple pages, where {handle} is the statement handle and {id1}, {id2}, {id3}, and {id4} are uniquely generated request IDs:

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:08:15 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=1&pageSize=-1>; rel="next",
  </api/statements/{handle}?requestId={id3}&page=7&pageSize=-1>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 0,
    "numPages" : 8,
    "numRows" : 10000,
    "format" : "json",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ]
  },
  "data" : [ [ "0", "0", "QqKow2xzdJ....." ],.... [ "98", "98", "ZugTcURrcy...." ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id4}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}

If multiple SQL statements were submitted in the request, the body of the response contains a ResultSet object with details about the status of the execution of the multiple statements.

In this case, the response does not contain the requested data. Instead, the data field just contains the message “Multiple statements executed successfully”.

The response contains the statementHandles field, which is an array of statement handles that you can use to retrieve the results of the individual statements.

The following is an example of a response for a request that specifies multiple SQL statements, where:

  • {handle} is the statement handle for the set of statements.

  • {handle1}, {handle2}, and {handle3 are the handles for the individual SQL statements in the request.

  • {id1}, {id2}, and {id3} are uniquely generated request IDs:

HTTP/1.1 200 OK
Date: Mon, 31 May 2021 22:50:31 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=-1>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=-1>; rel="last"

{
  "resultSetMetaData" : {
  "page" : 0,
  "numPages" : 1,
  "numRows" : 1,
  "format" : "json",
  "rowType" : [ {
      "name" : "multiple statement execution",
      "database" : "",
      "schema" : "",
      "table" : "",
      "type" : "text",
      "scale" : null,
      "precision" : null,
      "byteLength" : 16777216,
      "nullable" : false,
      "collation" : null,
      "length" : 16777216
    } ]
  },
  "data" : [ [ "0", "Multiple statements executed successfully." ] ],
  "code" : "090001",
  "statementHandles" : [ "{handle1}", "{handle2}", "{handle3}" ],
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id3}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1622501430333
}

202

The execution of the statement is still in progress. Use GET /api/statements/{statementHandle} to check the status of the statement execution. See GET /api/statements/{statementHandle} for details.

The body of the response contains a QueryStatus object with details about the status of the statement execution.

The following is an example of a response:

HTTP/1.1 202 Accepted
Date: Tue, 04 May 2021 18:12:37 GMT
Content-Type: application/json
Content-Length: 285
{
  "code" : "333334",
  "message" :
      "Asynchronous execution in progress. Use provided query id to perform query monitoring and management.",
  "statementHandle" : "019c06a4-0000-df4f-0000-00100006589e",
  "statementStatusUrl" : "/api/statements/019c06a4-0000-df4f-0000-00100006589e"
}

408

The execution of the statement exceeded the timeout period. The execution of the statement was cancelled.

The body of the response contains a QueryStatus object with details about the cancellation of the statement execution.

422

An error occurred when executing the statement. Check the error code and error message for details.

The body of the response contains a QueryFailureStatus object with details about the error.

The following is an example of a response:

HTTP/1.1 422 Unprocessable Entity
Date: Tue, 04 May 2021 20:24:11 GMT
Content-Type: application/json
{
  "code" : "000904",
  "message" : "SQL compilation error: error line 1 at position 7\ninvalid identifier 'AFAF'",
  "sqlState" : "42000",
  "statementHandle" : "019c0728-0000-df4f-0000-00100006606e"
}

For the other response codes returned by this operation, see Response Codes for All Operations.

GET /api/statements/{statementHandle}

To check the status of the execution of a statement, send a GET request to /api/statements/{statementHandle}. If the statement has been executed successfully, the body of the response includes a ResultSet object containing the requested data.

Request Syntax

GET /api/statements/{statementHandle}

Path Parameters

Parameter

Description

statementHandle

(Required) The handle of the statement that you want to check. You can get this handle from the QueryStatus object returned in the response to the request to execute the statement.

Query Parameters

requestId

(Optional) Unique ID (a UUID) of the API request. See Assigning a Unique Request ID for Resubmitting Requests.

page

(Optional) Number that identifies which page of results to return. The number can range from 0 to the total number of pages minus 1.

pageSize

(Optional) Number of rows to return per page. The page size can range from the minimum supported number (10) to the maximum supported number (10000) of rows per page. By default, the number of rows returned varies, depending on the execution of the statement.

Request Headers

The request must include the headers listed in Request Headers for All Operations.

Response

This operation can return the response codes listed below.

Code

Description

200

The statement was executed successfully.

For this response code, the response can have the following headers:

The body of the response has a ResultSet object containing the requested data.

The following is an example of a response, where {handle} is the statement handle and {id1}, {id2}, {id3}, {id4}, and {id5} are uniquely generated request IDs:

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 20:25:46 GMT
Content-Type: application/json
Link:
  </api/statements/{handle}?requestId={id1}&page=0&pageSize=10>; rel="first",
  </api/statements/{handle}?requestId={id2}&page=0&pageSize=10>; rel="prev",
  </api/statements/{handle}?requestId={id3}&page=2&pageSize=10>; rel="next",
  </api/statements/{handle}?requestId={id4}&page=999&pageSize=10>; rel="last"
{
  "resultSetMetaData" : {
    "page" : 1,
    "pageSize" : 10,
    "numPages" : 1000,
    "numRows" : 10000,
    "format" : "json",
    "rowType" : [ {
      "name" : "SEQ8()",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : 0,
      "precision" : 19,
      "length" : null,
      "type" : "fixed",
      "nullable" : false,
      "byteLength" : null,
      "collation" : null
    }, {
      "name" : "RANDSTR(1000, RANDOM())",
      "database" : "",
      "schema" : "",
      "table" : "",
      "scale" : null,
      "precision" : null,
      "length" : 16777216,
      "type" : "text",
      "nullable" : false,
      "byteLength" : 16777216,
      "collation" : null
    } ]
  },
  "data" : [ [ "10", "10", "lJPPMTSwps......" ], ... [ "19", "19", "VJKoHmUFJz......" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/statements/{handle}?requestId={id5}&pageSize=10",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}

202

The execution of the statement is still in progress. Repeat the request to check the status of the statement execution.

The body of the response contains a QueryStatus object with details about the status of the statement execution.

The following is an example of a response:

HTTP/1.1 202 Accepted
Date: Tue, 04 May 2021 22:31:33 GMT
Content-Type: application/json
Content-Length: 285
{
  "code" : "333334",
  "message" :
      "Asynchronous execution in progress. Use provided query id to perform query monitoring and management.",
  "statementHandle" : "019c07a7-0000-df4f-0000-001000067872",
  "statementStatusUrl" : "/api/statements/019c07a7-0000-df4f-0000-001000067872"
}

422

An error occurred when executing the statement. Check the error code and error message for details.

The body of the response contains a QueryFailureStatus object with details about the error.

For the other response codes returned by this operation, see Response Codes for All Operations.

POST /api/statements/{statementHandle}/cancel

To cancel the execution of a statement, send a POST request to /api/statements/{statementHandle}/cancel.

Request Syntax

POST /api/statements/{statementHandle}/cancel

Path Parameters

Parameter

Description

statementHandle

(Required) The handle of the statement that you want to check. You can get this handle from the QueryStatus object returned in the response to the request to execute the statement.

Query Parameters

Parameter

Description

requestId

(Optional) Unique ID (a UUID) of the API request. See Assigning a Unique Request ID for Resubmitting Requests.

Request Headers

The request must include the headers listed in Request Headers for All Operations.

Response

This operation can return the response codes listed below.

Code

Description

200

Execution of the statement was cancelled successfully.

The body of the response contains a CancelStatus object that contains information about the cancellation of the statement

The following is an example of a response:

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 22:52:15 GMT
Content-Type: application/json
Content-Length: 230
{
  "code" : "000604",
  "sqlState" : "57014",
  "message" : "SQL execution canceled",
  "statementHandle" : "019c07bc-0000-df4f-0000-001000067c3e",
  "statementStatusUrl" : "/api/statements/019c07bc-0000-df4f-0000-001000067c3e"
}

422

An error occurred when executing the statement. Check the error code and error message for details.

The body of the response contains a QueryFailureStatus object with details about the error.

The following is an example of a response:

HTTP/1.1 422 Unprocessable Entity
Date: Tue, 04 May 2021 22:52:49 GMT
Content-Type: application/json
Content-Length: 183
{
  "code" : "000709",
  "message" : "Statement 019c07bc-0000-df4f-0000-001000067c3e not found",
  "sqlState" : "02000",
  "statementHandle" : "019c07bc-0000-df4f-0000-001000067c3e"
}

For the other response codes returned by this operation, see Response Codes for All Operations.

Request Headers for All Operations

The following request headers are apply to all operations:

Header

Required or Optional?

Description

Authorization

Required

Set this to Bearer, followed by the token used to authenticate to Snowflake.

For example:

Authorization: Bearer token

See Authenticating to the Server.

Accept

Required

Set this to the list of media types (MIME types) that are acceptable in the body of the response. Include the type application/json (or, if all types are acceptable, set this to */*).

Content-Type

Required

Set this to the media type (MIME type) of the body of the request. Set this to application/json.

User-Agent

Required

Set this to the name and version of your application (e.g. applicationName/applicationVersion). You must use a value that complies with RFC 7231.

X-Snowflake-Authorization-Token-Type

Required for key pair authentication

Optional for OAuth

If you are using key pair authentication, this header is required. You must set this header to KEYPAIR_JWT.

If you are using OAuth for authentication, this header is optional. (If you choose to set this header, set it to OAUTH.)

Types of Objects in the Request Body

Body of the POST Request to /api/statements/

The body of a POST request to the /api/statements/ endpoint (see POST /api/statements) is a JSON object that you use to specify the SQL statement to execute, the statement context, and the format of data in the result set. You use this object in the body of a request to execute a statement.

Fields

Field

Description

statement

(Optional) SQL statement to execute. See Introduction for the lists of statements that are supported and not supported.

Type: string

timeout

(Optional) Timeout in seconds for statement execution. If the execution of a statement takes longer than the specified timeout, the execution is automatically canceled. To set the timeout to the maximum value (604800 seconds), set timeout to 0. If this field is not set, the timeout specified by the STATEMENT_TIMEOUT_IN_SECONDS parameter is used.

Type: 64-bit signed integer

Example: 10

resultSetMetaData

(Optional) Metadata about the result set to be returned.

Type: object (statements_resultSetMetaData)

database

(Optional) Database in which the statement should be executed. The value in this field is case-sensitive.

Type: string

Example: TESTDB

schema

(Optional) Schema in which the statement should be executed. The value in this field is case-sensitive.

Type: string

Example: TESTSCHEMA

warehouse

(Optional) Warehouse to use when executing the statement. The value in this field is case-sensitive.

Type: string

Example: TESTWH

role

(Optional) Role to use when executing the statement. The value in this field is case-sensitive.

Type: string

Example: TESTROLE

bindings

(Optional) Values of bind variables in the SQL statement. When executing the statement, Snowflake replaces placeholders (? and :name) in the statement with these specified values.

Note that the format of this field may change for the GA release of the SQL API.

Type: object

Example:

{"1":{"type":"FIXED","value":"123"},"2":{"type":"TEXT","value":"teststring"}}

parameters

(Optional) Session parameters that you want to set for this request.

Type: object (statements_parameters)

Example

The following is an example of the body object:

{
  "statement" : "select * from T where c1=?",
  "timeout" : 10,
  "resultSetMetaData" : {
    "format" : "json"
  },
  "database" : "TESTDB",
  "schema" : "TESTSCHEMA",
  "warehouse" : "TESTWH",
  "role" : "TESTROLE",
  "bindings" : {
    "1" : {
      "type" : "FIXED",
      "value" : "123"
    }
  }
}

statements_parameters

statements_parameters is a JSON object that you use to specify the session parameters that you want to set for this request. This object should be in the parameters field of the body of the POST request to the /api/statements endpoint (see Body of the POST Request to /api/statements/).

Fields

Field

Description

timezone

(Optional) Time zone to use when executing the statement. For details, see the documentation on the TIMEZONE parameter.

Type: string

Example: america/los_angeles

query_tag

(Optional) Query tag that you want to associate with the SQL statement. For details, see the documentation on the QUERY_TAG parameter.

Type: string

Example: tag-1234

statements_resultSetMetaData

statements_resultSetMetaData is a JSON object that you use to specify metadata about the result set that should be returned. This object should be in the resultSetMetaData field of the body of the POST request to the /api/statements endpoint (see Body of the POST Request to /api/statements/).

Fields

Field

Description

format

(Optional) Format of the data in the result set. The only supported value is json.

Type: string

Response Codes for All Operations

This section lists the response codes that apply to all operations.

Code

Description

400

Bad Request.

The request payload is invalid or malformed. This happens if the application didn’t send the correct request payload. The response body may include the error code and message indicating the actual cause. The application must reconstruct the request body for retry.

The following is an example of a response:

HTTP/1.1 400 Bad Request
Date: Tue, 04 May 2021 22:54:21 GMT
Content-Type: application/json
{
  "code" : "390142",
  "message" : "Incoming request does not contain a valid payload."
}

401

Unauthorized.

The request is not authorized. This happens if the attached access token is invalid or missing. The response body may include the error code and message indicating the actual cause, e.g., expired, invalid token. The application must obtain a new access token for retry.

See Authenticating to the Server.

The following is an example of a response:

HTTP/1.1 401 Unauthorized
Date: Tue, 04 May 2021 20:17:57 GMT
Content-Type: application/json
{
  "code" : "390303",
  "message" : "Invalid OAuth access token. ...TTTTTTTT"
}

403

Forbidden.

The request is forbidden. This happens if the request is made even if the API is not enabled.

404

Not Found.

The request endpoint is not valid. This happens if the API endpoint is wrong. For example, if the application requests /api/hello, which doesn’t exist, the server returns this code.

405

Method Not Allowed.

The request method doesn’t match the supported API. This happens, for example, if the application calls the API with the GET method but the endpoint accepts only POST. The application must use a supported method when sending the request.

The following is an example of a response:

HTTP/1.1 405 Method Not Allowed
Date: Tue, 04 May 2021 22:55:38 GMT
Content-Length: 0

415

The request header Content-Type includes unsupported media type.

The API supports application/json only. If no Content-Type is specified, the request payload is interpreted as JSON, but if any other media type is specified, this error is returned.

429

Limit Exceeded.

The number of requests hit the rate limit. The application must reduce the frequency of requests sent to the API endpoints.

The following is an example of a response:

HTTP/1.1 429 Too many requests
Content-Type: application/json
Content-Length: 69
{
  "code" : "390505",
  "message" : "Too many concurrent requests"
}

500

Internal Server Error.

The server encountered an unrecoverable system error. The response body may include the error code and message for further guidance.

503

Service Unavailable.

The request was not processed due to a timeout on the server. The application may retry with backoff. Exponentially jittered backoff is recommended.

504

Gateway Timeout.

The request was not processed due to a timeout on the server. The application may retry with backoff. Exponentially jittered backoff is recommended.

Response Headers for All Operations

Responses can contain the following headers:

Header

Description

Link

This header is in the 200 response for a request to execute the statement and a request to check the status of the execution of a statement.

This header provides links to other pages of results (e.g. the first page, the last page, etc.). The header can include multiple URL entries with different rel attribute values that specify the page to return (first, next, prev, and last).

For example:

Link: </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=1; rel="last">,
      </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=1; rel="next">,
      </api/statements/e127cc7c-7812-4e72-9a55-3b4d4f969840?page=0; rel="first">

Types of Objects in the Response Body

CancelStatus

CancelStatus is a JSON object that contains information about the cancellation of the execution of a statement. This object is returned in the body of the response for a cancellation request.

Fields

Field

Description

code

Type: string

sqlState

Type: string

message

Example: successfully cancelled

Type: string

statementHandle

Unique identifier for the statement being executed.

Type: string (a UUID)

Example: 536fad38-b564-4dc5-9892-a4543504df6c

statementStatusUrl

URL to get the statement status and result set.

Type: string (a URL)

Example: /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

Example

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully canceled",
  "statementHandle" : "536fad38-b564-4dc5-9892-a4543504df6c",
  "statementStatusUrl" : "/api/statements/536fad38-b564-4dc5-9892-a4543504df6c"
}

QueryFailureStatus

QueryFailureStatus is a JSON object that contains information about a failure to execute a statement. This object is returned in the body of the 422 response for a request to execute the statement.

Fields

Field

Description

code

Type: string

Example: 0

sqlState

Type: string

message

Type: string

Example: successfully executed

statementHandle

Unique identifier for the statement being executed.

Type: string (a UUID)

Example: 536fad38-b564-4dc5-9892-a4543504df6c

createdOn

Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch.

Type: 64-bit signed integer

Example: 1597090533987

statementStatusUrl

URL to get the statement status and result set.

Type: string (a URL)

Example: /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

Example

{
  "code" : "002140",
  "sqlState" : "42601",
  "message" : "SQL compilation error",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
}

QueryStatus

QueryStatus is a JSON object that contains information about the status of the execution of a statement. This object is returned in the following:

Fields

Field

Description

code

Type: string

Example: 0

sqlState

Type: string

message

Type: string

Example: successfully executed

statementHandle

Unique identifier for the statement being executed.

Type: string (a UUID)

Example: 536fad38-b564-4dc5-9892-a4543504df6c

createdOn

Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch.

Type: 64-bit signed integer

Example: 1597090533987

statementStatusUrl

URL to get the statement status and result set.

Type: string (a URL)

Example: /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

Example

{
  "code" : "0",
  "sqlState" : "",
  "message" : "successfully executed",
  "statementHandle" : "e4ce975e-f7ff-4b5e-b15e-bf25f59371ae",
  "statementStatusUrl" : "/api/statements/e4ce975e-f7ff-4b5e-b15e-bf25f59371ae"
}

ResultSet

ResultSet is a JSON object that contains the results of the execution of a statement. This object is returned in the body of the 200 response for a request to execute the statement and a request to check the status of the execution of a statement.

Fields

Field

Description

code

Type: string

Example: 0

Note

If code is set to 391908, see Determining If the Result Set Page Size Exceeds the Limit.

sqlState

Type: string

message

Type: string

Example: successfully executed

statementHandle

Unique identifier for the statement being executed.

If multiple statements were specified in the request, this handle corresponds to the set of those statements. For the handles of the individual statements in the request, see the statementHandles field.

Type: string (a UUID)

Example: 536fad38-b564-4dc5-9892-a4543504df6c

statementHandles

Array of unique identifiers for the statements being executed for this request.

Type: array of strings (UUID)

Example: [ "019c9f9a-0502-f25e-0000-438300e0d046", "019c9f9a-0502-f25e-0000-438300e0d04a", "019c9f9a-0502-f25e-0000-438300e0d04e" ]

createdOn

Timestamp that specifies when the statement execution started. The timestamp is expressed in milliseconds since the epoch.

Example: 1597090533987

statementStatusUrl

URL to get the statement status and result set.

Type: string (a URL)

Example: /api/statements/536fad38-b564-4dc5-9892-a4543504df6c

resultSetMetaData

Metadata about the result set returned.

Type: object (ResultSet_resultSetMetaData)

data

If the request contains a single SQL statement, this field contains the result set data.

A result set format is an array of arrays in JSON:

  • Each array corresponds to a single row.

  • The first element in a row is a JSON string containing a sequence ID that starts from 0.

  • The rest of elements in a row are the actual data.

  • The data is encoded as JSON strings, regardless of the Snowflake datatype.

Type: array of arrays

Example:

[
  ["0","customer1","1234 A Avenue","98765","1565481394123000000"],
  ["1","customer2","987 B Street","98765","1565516712912012345"],
  ["2","customer3","8777 C Blvd","98765","1565605431999999999"],
  ["3","customer4","64646 D Circle","98765","1565661272000000000"]
]

If the request contains multiple SQL statements, this field just contains the message “Multiple statements executed successfully”. To retrieve the results for each statement in the request, get the handles for these statements from the statementHandles field, and send requests to get the results of each statement.

stats

For DML statements, this field contains statistics about the number of rows affected by the operation.

Type: object (ResultSet_stats)

ResultSet_resultSetMetaData

ResultSet_resultSetMetaData is a JSON object that contains metadata about the results of the execution of a statement. This object is in the resultSetMetaData field of the ResultSet object.

Fields

Field

Description

page

The number that identifies the current page of results.

Type: 64-bit signed integer

Example: 12

pageSize

The number of rows per page. This field is set only if you specified the pageSize parameter in the request.

Type: 64-bit signed integer

Example: 10

numPages

The number of pages of results.

Type: 64-bit signed integer

Example: 10

numRows

The total number of rows of results.

Type: 64-bit signed integer

Example: 100

format

Format of the data in the result set. The only supported value is json.

Type: string

rowType

Array of ResultSet_resultSetMetaData_rowType objects that describe the columns in the set of results.

Type: array of ResultSet_resultSetMetaData_rowType.

Example:

[
 {"name":"ROWNUM","type":"FIXED","length":0,"precision":38,"scale":0,"nullable":false},
 {"name":"ACCOUNT_ID","type":"FIXED","length":0,"precision":38,"scale":0,"nullable":false},
 {"name":"ACCOUNT_NAME","type":"TEXT","length":1024,"precision":0,"scale":0,"nullable":false},
 {"name":"ADDRESS","type":"TEXT","length":16777216,"precision":0,"scale":0,"nullable":true},
 {"name":"ZIP","type":"TEXT","length":100,"precision":0,"scale":0,"nullable":true},
 {"name":"CREATED_ON","type":"TIMESTAMP_NTZ","length":0,"precision":0,"scale":3,"nullable":false}
]

ResultSet_resultSetMetaData_rowType

ResultSet_resultSetMetaData_rowType is a JSON object that describes a column in a set of results. An array of these objects is in the rowType field of the ResultSet_resultSetMetaData object.

Fields

Field

Description

name

Name of the column.

Type: string

type

Snowflake data type of the column.

Type: string

length

Length of the column.

Type: 64-bit signed integer

precision

Precision of the column.

Type: 64-bit signed integer

scale

Scale of the column.

Type: 64-bit signed integer

nullable

Specifies whether or not the column is nullable.

Type: boolean

Example

{
 "name":"ACCOUNT_NAME",
 "type":"TEXT",
 "length":1024,
 "precision":0,
 "scale":0,
 "nullable":false
}

ResultSet_stats

ResultSet_stats is a JSON object that contains statistics about the execution of a DML statement. This object is in the stats field of the ResultSet_resultSetMetaData object.

Fields

Field

Description

numRowsInserted

Number of rows that were inserted.

Type: 64-bit signed integer

Example: 12

numRowsUpdated

Number of rows that were updated.

Type: 64-bit signed integer

Example: 9

numRowsDeleted

Number of rows that were deleted.

Type: 64-bit signed integer

Example: 8

numDuplicateRowsUpdated

Number of duplicate rows that were updated.

Type: 64-bit signed integer

Example: 20