Skip to content
Developers
Get an API token

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

POST/api/v2/statements

Send 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.

Send a Snowflake programmatic access token as a bearer token on every request. Authentication
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

  • asyncbooleanOptional

    Set to true to 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-AgentstringRequired

    Your application's name and version, for example myApplication/1.0. Snowflake requires a value that complies with RFC 7231.

Request bodyRequired

application/json

  • statementstringOptional

    The SQL to run. Name views with their schema, for example NOVI_WELLS.WELL, or set schema.

  • timeoutintegerOptional

    Format int64≥ 0

    Seconds before Snowflake cancels the statement. 0 sets the maximum, 604800 seconds (7 days). If you leave it out, the account's STATEMENT_TIMEOUT_IN_SECONDS applies.

  • databasestringOptional

    Database to run in: NOVI_DATA_ACCESS. Case-sensitive. If you leave it out, your user's default namespace applies.

  • schemastringOptional

    Schema to run in, for example NOVI_WELLS. Case-sensitive. If you leave it out, your user's default namespace applies.

  • warehousestringOptional

    Warehouse that runs the query: NOVI_WH on 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.

  • rolestringOptional

    Role to run as: DATA_READER on 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.

  • bindingsobjectOptional

    Values for ? placeholders in statement, keyed by position from "1". Each value is a string, with a Snowflake binding type such as TEXT or FIXED. See bind variables for every type.

    ShowHide 2 child fields in each value
    • typestringOptional

    • valuestringOptional

  • parametersobjectOptional

    Session 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_formatstringOptional

      Format for DATE values.

    • time_output_formatstringOptional

      Format for TIME values.

    • timestamp_output_formatstringOptional

      Format for the TIMESTAMP data type alias.

    • timestamp_ltz_output_formatstringOptional

      Format for TIMESTAMP_LTZ values.

    • timestamp_ntz_output_formatstringOptional

      Format for TIMESTAMP_NTZ values.

    • timestamp_tz_output_formatstringOptional

      Format for TIMESTAMP_TZ values.

    • timezonestringOptional

      Time zone for the statement.

    • query_tagstringOptional

      A query tag to attach to the statement.

Responses

The query finished. The body holds partition 0 of the results and metadata for every partition.

  • codestringOptional

    Snowflake status code. 090001 means the statement ran successfully.

  • sqlStatestringOptional

  • messagestringOptional

  • statementHandlestringOptional

    Format uuid

    The statement's ID. Use it with Get results and Cancel a query.

  • createdOnintegerOptional

    Format int64

    When the statement started, in milliseconds since the epoch.

  • statementStatusUrlstringOptional

    Format uri-reference

    Path to the statement's status and results.

  • resultSetMetaDataobjectOptional

    Columns, row count and partitions of the whole result. Sent with the first partition only.

    ShowHide 4 child fields
    • numRowsintegerOptional

      Format int64

      Total rows across all partitions.

    • formatstringOptional

      Format of data. Always jsonv2.

      "jsonv2"
    • rowTypearray of objectsOptional

      One entry per column, in column order.

      ShowHide 6 child fields in each item
      • namestringOptional

        Column name.

      • typestringOptional

        Snowflake data type of the column.

      • lengthinteger or nullOptional

        Format int64

        Length of the column.

      • precisioninteger or nullOptional

        Format int64

        Precision of the column.

      • scaleinteger or nullOptional

        Format int64

        Scale of the column.

      • nullablebooleanOptional

        Whether the column can hold NULL.

    • partitionInfoarray of objectsOptional

      One entry per partition. The first describes the rows in this response.

      ShowHide 3 child fields in each item
      • rowCountintegerOptional

        Format int64≥ 0

        Rows in the partition.

      • uncompressedSizeintegerOptional

        Format int64≥ 0

        Partition size in bytes, uncompressed.

      • compressedSizeintegerOptional

        Format int64≥ 0

        Partition size in bytes, compressed. Not always present.

  • dataarray of arraysOptional

    Rows of this partition. Each row is an array of column values in rowType order, each a JSON string or null.

Errors

StatusWhen
408

The query ran longer than timeout, and Snowflake cancelled it.

422

The statement failed, for example with a SQL compilation error. code and message say why.

429

Too many requests, or too many at once. Retry with exponential backoff and jitter.

Shared errors400401403404500503504What they mean