Novi UDM Data (v4) API
Run a query
Send a SQL statement and get the first part of the results back as JSON.
Run a query
/api/v2/statementsSend a SQL statement and get the first part of the results back as JSON. Snowflake waits up to 45 seconds for the query to finish. If it is still running, the answer is 202 with a statementHandle: poll Get results with it.
Reader account
Use warehouse NOVI_WH, database NOVI_DATA_ACCESS and role DATA_READER.
Your own Snowflake account
Use database NOVI_DATA_ACCESS with the warehouse and role from your setup script.
Headers
Send Authorization: Bearer <token>, Content-Type: application/json, Accept: application/json and a User-Agent that names your application.
Long queries
Set async=true to get the handle at once. Handle 202 either way: without async=true, Snowflake does not guarantee a synchronous answer.
Context
Set database, schema, warehouse and role in the body. USE and ALTER SESSION work only inside a multi-statement request.
Reading values
Every value in data is a JSON string, whatever the column type, or null for SQL NULL. Convert them yourself. DATE values come back as a count of days since the epoch and timestamps as epoch numbers, unless you set an output format in parameters, for example "date_output_format": "YYYY-MM-DD".
Large results
Snowflake splits results into partitions and sizes them itself. This response holds partition 0. resultSetMetaData.partitionInfo lists every partition: fetch the others with Get results and partition=1, partition=2 and so on.
Parameters
Query parameters
asyncbooleanOptionalSet to
trueto return the statement handle at once. Otherwise Snowflake returns the results if the query finishes within 45 seconds, and the handle if it does not.
Header parameters
User-AgentstringRequiredYour application's name and version, for example
myApplication/1.0. Snowflake requires a value that complies with RFC 7231.
Request body
application/json
statementstringOptionalThe SQL to run. Name views with their schema, for example
NOVI_WELLS.WELL, or setschema.timeoutintegerOptionalFormat
int64≥ 0Seconds before Snowflake cancels the statement.
0sets the maximum, 604800 seconds (7 days). If you leave it out, the account'sSTATEMENT_TIMEOUT_IN_SECONDSapplies.databasestringOptionalDatabase to run in:
NOVI_DATA_ACCESS. Case-sensitive. If you leave it out, your user's default namespace applies.schemastringOptionalSchema to run in, for example
NOVI_WELLS. Case-sensitive. If you leave it out, your user's default namespace applies.warehousestringOptionalWarehouse that runs the query:
NOVI_WHon a reader account, or the warehouse from your setup script on your own Snowflake account. Case-sensitive. If you leave it out, your user's default warehouse applies.rolestringOptionalRole to run as:
DATA_READERon a reader account, or the role from your setup script on your own Snowflake account. Case-sensitive. If you leave it out, your user's default role applies.bindingsobjectOptionalValues for
?placeholders instatement, keyed by position from"1". Each value is a string, with a Snowflake bindingtypesuch asTEXTorFIXED. See bind variables for every type.ShowHide 2 child fields in each value
typestringOptionalvaluestringOptional
parametersobjectOptionalSession parameters for this request. Snowflake ignores account and user settings for the output formats, so set them here. Snowflake's reference lists every parameter the SQL API accepts.
ShowHide 8 child fields
date_output_formatstringOptionalFormat for DATE values.
time_output_formatstringOptionalFormat for TIME values.
timestamp_output_formatstringOptionalFormat for the TIMESTAMP data type alias.
timestamp_ltz_output_formatstringOptionalFormat for TIMESTAMP_LTZ values.
timestamp_ntz_output_formatstringOptionalFormat for TIMESTAMP_NTZ values.
timestamp_tz_output_formatstringOptionalFormat for TIMESTAMP_TZ values.
timezonestringOptionalTime zone for the statement.
query_tagstringOptionalA query tag to attach to the statement.
Responses
The query finished. The body holds partition 0 of the results and metadata for every partition.
codestringOptionalSnowflake status code.
090001means the statement ran successfully.sqlStatestringOptionalmessagestringOptionalstatementHandlestringOptionalFormat
uuidThe statement's ID. Use it with Get results and Cancel a query.
createdOnintegerOptionalFormat
int64When the statement started, in milliseconds since the epoch.
statementStatusUrlstringOptionalFormat
uri-referencePath to the statement's status and results.
resultSetMetaDataobjectOptionalColumns, row count and partitions of the whole result. Sent with the first partition only.
ShowHide 4 child fields
numRowsintegerOptionalFormat
int64Total rows across all partitions.
formatstringOptionalFormat of
data. Alwaysjsonv2."jsonv2"rowTypearray of objectsOptionalOne entry per column, in column order.
ShowHide 6 child fields in each item
namestringOptionalColumn name.
typestringOptionalSnowflake data type of the column.
lengthinteger or nullOptionalFormat
int64Length of the column.
precisioninteger or nullOptionalFormat
int64Precision of the column.
scaleinteger or nullOptionalFormat
int64Scale of the column.
nullablebooleanOptionalWhether the column can hold NULL.
partitionInfoarray of objectsOptionalOne entry per partition. The first describes the rows in this response.
ShowHide 3 child fields in each item
rowCountintegerOptionalFormat
int64≥ 0Rows in the partition.
uncompressedSizeintegerOptionalFormat
int64≥ 0Partition size in bytes, uncompressed.
compressedSizeintegerOptionalFormat
int64≥ 0Partition size in bytes, compressed. Not always present.
dataarray of arraysOptionalRows of this partition. Each row is an array of column values in
rowTypeorder, each a JSON string ornull.
Still running after 45 seconds, or you set async=true. Poll Get results with the statementHandle.
statementHandlestringRequiredFormat
uuidThe statement's ID. Use it with Get results and Cancel a query.
codestringOptionalSnowflake status code.
333334means the query is still running.sqlStatestringOptionalmessagestringOptionalcreatedOnintegerOptionalFormat
int64When the statement started, in milliseconds since the epoch.
statementStatusUrlstringOptionalFormat
uri-referencePath to the statement's status and results.
Errors
| Status | When |
|---|---|
| 408 | The query ran longer than |
| 422 | The statement failed, for example with a SQL compilation error. |
| 429 | Too many requests, or too many at once. Retry with exponential backoff and jitter. |
Shared errors400401403404500503504What they mean