Referência da API de SQL do Snowflake

Este tópico documenta as operações, solicitações e respostas para a API de SQL.

Neste tópico:

Operações

POST /api/v2/statements

Para enviar uma ou mais instruções SQL para execução, envie uma solicitação POST para /api/v2/statements. Você pode especificar que a instrução deve ser executada de forma assíncrona.

Sintaxe da solicitação

POST /api/v2/statements
(request body)
Copy

Parâmetros de consulta

Parâmetro

Descrição

requestId

(Opcional) ID única (uma UUID) da solicitação da API. Consulte Como reenviar uma solicitação para executar instruções SQL.

async

(Opcional) Definir como true para executar a instrução de forma assíncrona e retornar o identificador da instrução.

Se o parâmetro não for especificado ou for definido como falso, uma instrução é executada e os resultados são retornados se a execução for concluída em 45 segundos. Se a execução da instrução demorar mais tempo para ser concluída, o identificador da instrução é retornado.

nullable

(Opcional) Definir como false para retornar um valor NULL de SQL como a cadeia de caracteres "null", e não como o valor null.

Nota

Você não pode especificar esse parâmetro em uma solicitação GET.

Por padrão, valores NULL de SQL são retornados como o valor null:

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

A definição desse parâmetro de consulta como falso (por exemplo, /api/v2/statements?nullable=false retorna um valor NULL de SQL como a cadeia de caracteres "null":

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

Cabeçalhos de solicitação

A solicitação deve incluir os cabeçalhos listados em Cabeçalhos de solicitação para todas as operações.

Corpo da solicitação

(Obrigatório) O corpo da solicitação deve conter o objeto especificado em Corpo da solicitação POST para /api/v2/statements/.

Resposta

Essa operação pode retornar os códigos de resposta listados abaixo.

Código

Descrição

200

A instrução foi executada com sucesso.

Para esse código de resposta, a resposta pode ter os seguintes cabeçalhos:

Se uma única instrução SQL tiver sido apresentada na solicitação, o corpo da resposta conterá um objeto ResultSet com os dados solicitados.

Nota

Se o campo code na resposta for definido como 391908, o conjunto de resultados definido é grande demais . e a resposta não incluirá todo o resultado definido.

A seguir, veja um exemplo de uma resposta para uma única instrução SQL na qual os resultados são retornados em uma única partição. {handle} é o identificador da instrução e {id1}, {id2}, e {id3} são IDs de solicitações geradas de forma única:

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:06:24 GMT
Content-Type: application/json
Link:
  </api/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=0>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 4,
    "format" : "jsonv2",
    "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
    } ],
    "partitionInfo": [{
      "rowCount": 4,
      "uncompressedSize": 1438,
    }]
  },
  "data" : [ [ "test", "2" ], [ "test", "3" ], [ "test", "4" ], [ "test", "5" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id3}&partition=0",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151584132
}
Copy

A seguir, veja um exemplo de uma resposta para uma única instrução SQL na qual os resultados precisam ser retornados em várias partições, onde {handle} é o identificador da instrução e {id1}, {id2}, {id3} e {id4} são IDs de solicitações geradas de forma única:

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 18:08:15 GMT
Content-Type: application/json
Link:
  </api/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=1>; rel="next",
  </api/v2/statements/{handle}?requestId={id3}&partition=1>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 56090,
    "format" : "jsonv2",
    "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
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
      "rowCount": 43746,
      "uncompressedSize": 43748274,
      "compressedSize": 746323
    }]
  },
  "data" : [ [ "0", "QqKow2xzdJ....." ],.... [ "98", "ZugTcURrcy...." ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id4}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}
Copy

Se várias instruções SQL tiverem sido apresentadas na solicitação, o corpo da resposta conterá um objeto ResultSet com detalhes sobre o status da execução das diversas instruções.

Nesse caso, a resposta não conterá os dados solicitados. Em vez disso, o campo data conterá apenas a mensagem “Multiple statements executed successfully”.

A resposta contém o campo statementHandles, que é uma array de identificadores de instruções que você pode usar para obter os resultados de instruções.

A seguir, você vê um exemplo de resposta para uma solicitação que especifica múltiplas instruções SQL, onde:

  • {handle} é o identificador de instrução para o conjunto de instruções.

  • {handle1} {handle2}, e {handle3} são os identificadores para as instruções SQL individuais na solicitação.

  • {id1} {id2}, e {id3} são IDs de solicitações geradas de forma única:

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

{
  "resultSetMetaData" : {
  "numRows" : 56090,
  "format" : "jsonv2",
  "rowType" : [ {
      "name" : "multiple statement execution",
      "database" : "",
      "schema" : "",
      "table" : "",
      "type" : "text",
      "scale" : null,
      "precision" : null,
      "byteLength" : 16777216,
      "nullable" : false,
      "collation" : null,
      "length" : 16777216
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
     "rowCount": 43746,
     "uncompressedSize": 43748274,
     "compressedSize": 746323
    }]
  },
  "data" : [ [ "Multiple statements executed successfully." ] ],
  "code" : "090001",
  "statementHandles" : [ "{handle1}", "{handle2}", "{handle3}" ],
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id3}",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1622501430333
}
Copy

202

A execução da instrução ainda está em andamento. Use GET /api/v2/statements/{statementHandle} para verificar o status da execução da instrução. Consulte GET /api/v2/statements/{statementHandle} para obter mais detalhes.

O corpo da resposta contém um objeto QueryStatus com detalhes sobre o status da execução da instrução.

A seguir você vê um exemplo de resposta:

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/v2/statements/019c06a4-0000-df4f-0000-00100006589e"
}
Copy

408

A execução da instrução excedeu o período de tempo limite. A execução da instrução foi cancelada.

O corpo da resposta contém um objeto QueryStatus com detalhes sobre o cancelamento da execução da instrução.

422

Ocorreu um erro ao executar a instrução. Verifique o código de erro e a mensagem de erro para obter detalhes.

O corpo da resposta contém um objeto QueryFailureStatus com detalhes sobre o erro.

A seguir você vê um exemplo de resposta:

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"
}
Copy

Para obter os outros códigos de resposta retornados por essa operação, consulte Códigos de resposta para todas as operações.

GET /api/v2/statements/{statementHandle}

Para verificar o status da execução de uma instrução, envie uma solicitação GET para /api/v2/statements/{statementHandle}. Se a instrução tiver sido executada com sucesso, o corpo da resposta incluirá um objeto ResultSet contendo os dados solicitados.

Sintaxe da solicitação

GET /api/v2/statements/{statementHandle}
Copy

Parâmetros de caminho

Parâmetro

Descrição

statementHandle

(Necessário) O identificador da instrução que você deseja verificar. Você pode obter esse identificador do objeto QueryStatus retornado na resposta à solicitação para executar a instrução.

Parâmetros de consulta

requestId

(Opcional) ID única (uma UUID) da solicitação da API. Consulte Como reenviar uma solicitação para executar instruções SQL.

partition

(Opcional) O número de partição a ser retornado. O tamanho de cada partição é determinado pelo Snowflake.

Consulte Como obter os resultados da resposta para obter mais informações.

Cabeçalhos de solicitação

A solicitação deve incluir os cabeçalhos listados em Cabeçalhos de solicitação para todas as operações.

Resposta

Essa operação pode retornar os códigos de resposta listados abaixo.

Código

Descrição

200

A instrução foi executada com sucesso.

Para esse código de resposta, a resposta pode ter os seguintes cabeçalhos:

O corpo da resposta tem um objeto ResultSet contendo os dados solicitados.

O seguinte é um exemplo de resposta, onde {handle} é o identificador da instrução e {id1}, {id2}, {id3}, {id4}, e {id5}} são IDs de solicitações geradas de forma única:

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 20:25:46 GMT
Content-Type: application/json
Link:
  </api/v2/statements/{handle}?requestId={id1}&partition=0>; rel="first",
  </api/v2/statements/{handle}?requestId={id2}&partition=0>; rel="prev",
  </api/v2/statements/{handle}?requestId={id3}&partition=1>; rel="next",
  </api/v2/statements/{handle}?requestId={id4}&partition=10>; rel="last"
{
  "resultSetMetaData" : {
    "numRows" : 10000,
    "format" : "jsonv2",
    "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
    } ],
    "partitionInfo": [{
      "rowCount": 12344,
      "uncompressedSize": 14384873,
    },{
      "rowCount": 43746,
      "uncompressedSize": 43748274,
      "compressedSize": 746323
    }]
  },
  "data" : [ [ "10", "lJPPMTSwps......" ], ... [ "19", "VJKoHmUFJz......" ] ],
  "code" : "090001",
  "statementStatusUrl" : "/api/v2/statements/{handle}?requestId={id5}&partition=10",
  "sqlState" : "00000",
  "statementHandle" : "{handle}",
  "message" : "Statement executed successfully.",
  "createdOn" : 1620151693299
}
Copy

202

A execução da instrução ainda está em andamento. Repita a solicitação para verificar o status da execução da instrução.

O corpo da resposta contém um objeto QueryStatus com detalhes sobre o status da execução da instrução.

A seguir você vê um exemplo de resposta:

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/v2/statements/019c07a7-0000-df4f-0000-001000067872"
}
Copy

422

Ocorreu um erro ao executar a instrução. Verifique o código de erro e a mensagem de erro para obter detalhes.

O corpo da resposta contém um objeto QueryFailureStatus com detalhes sobre o erro.

Para obter os outros códigos de resposta retornados por essa operação, consulte Códigos de resposta para todas as operações.

POST /api/v2/statements/{statementHandle}/cancel

Para cancelar a execução de uma instrução, envie uma solicitação POST para /api/v2/statements/{statementHandle}/cancel.

Sintaxe da solicitação

POST /api/v2/statements/{statementHandle}/cancel
Copy

Parâmetros de caminho

Parâmetro

Descrição

statementHandle

(Necessário) O identificador da instrução que você deseja verificar. Você pode obter esse identificador do objeto QueryStatus retornado na resposta à solicitação para executar a instrução.

Parâmetros de consulta

Parâmetro

Descrição

requestId

(Opcional) ID única (uma UUID) da solicitação da API. Consulte Como reenviar uma solicitação para executar instruções SQL.

Cabeçalhos de solicitação

A solicitação deve incluir os cabeçalhos listados em Cabeçalhos de solicitação para todas as operações.

Resposta

Essa operação pode retornar os códigos de resposta listados abaixo.

Código

Descrição

200

A execução da instrução foi cancelada com sucesso.

O corpo da resposta contém um objeto CancelStatus que contém informações sobre o cancelamento da instrução.

A seguir você vê um exemplo de resposta:

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/v2/statements/019c07bc-0000-df4f-0000-001000067c3e"
}
Copy

422

Ocorreu um erro ao executar a instrução. Verifique o código de erro e a mensagem de erro para obter detalhes.

O corpo da resposta contém um objeto QueryFailureStatus com detalhes sobre o erro.

A seguir você vê um exemplo de resposta:

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"
}
Copy

Para obter os outros códigos de resposta retornados por essa operação, consulte Códigos de resposta para todas as operações.

Cabeçalhos de solicitação para todas as operações

Os seguintes cabeçalhos de solicitação se aplicam a todas as operações:

Cabeçalho

Obrigatório ou opcional?

Descrição

Authorization

Obrigatório

Defina esse valor como Bearer seguido pelo símbolo token usado para autenticar ao Snowflake.

Por exemplo:

Authorization: Bearer token

Consulte Autenticação no servidor.

Accept

Obrigatório

Defina esse valor como a lista de tipos de mídia (tipos MIME) que são aceitáveis no corpo da resposta. Inclua o tipo application/json (ou, se todos os tipos forem aceitáveis, defina esse valor como */*).

Content-Type

Obrigatório

Defina esse valor como o tipo de mídia (tipo MIME) do corpo da resposta. Defina esse valor como application/json.

User-Agent

Obrigatório

Defina esse valor como o nome e a versão de seu aplicativo (por exemplo, applicationName/applicationVersion). Você deve usar um valor que esteja de acordo com o RFC 7231.

X-Snowflake-Authorization-Token-Type

Necessário para autenticação com par de chaves

Opcional para OAuth

Se você estiver usando uma autenticação com par de chaves, esse cabeçalho é obrigatório. Você deve definir esse cabeçalho como KEYPAIR_JWT.

Se você estiver usando OAuth para autenticação, esse cabeçalho é opcional. (Se você escolher definir este cabeçalho, defina-o como OAUTH).

Tipos de objetos no corpo da solicitação

Corpo da solicitação POST para /api/v2/statements/

O corpo de uma solicitação POST para o ponto de extremidade /api/v2/statements/ (consulte POST /api/v2/statements) é um objeto JSON que você usa para especificar a instrução SQL a ser executada, o contexto da instrução e o formato dos dados no conjunto de resultados. Você usa esse objeto no corpo de uma solicitação para executar uma instrução.

Campos

Campo

Descrição

statement

(Opcional) Instrução SQL a executar. Consulte Limitações da API de SQL para obter as listas de instruções que são suportadas e não suportadas.

Tipo: cadeia de caracteres

timeout

(Opcional) Tempo limite em segundos para a execução da instrução. Se a execução de uma instrução demorar mais do que o tempo limite especificado, a execução é automaticamente cancelada. Para definir o tempo limite para o valor máximo (604800 segundos), defina o tempo limite como 0. Se esse campo não estiver definido, será usado o tempo limite especificado pelo parâmetro STATEMENT_TIMEOUT_IN_SECONDS.

Tipo: integer assinado de 64 bits

Exemplo: 10

database

(Opcional) Base de dados na qual a instrução deve ser executada. O valor nesse campo diferencia entre maiúsculas e minúsculas.

Se você omitir este campo, a API do SQL utilizará o banco de dados da propriedade DEFAULT_NAMESPACE do usuário.

Tipo: cadeia de caracteres

Exemplo: TESTDB

schema

(Opcional) Esquema no qual a instrução deve ser executada. O valor nesse campo diferencia entre maiúsculas e minúsculas.

Se você omitir este campo, a API do SQL utilizará o esquema do valor da propriedade DEFAULT_NAMESPACE do usuário.

Tipo: cadeia de caracteres

Exemplo: TESTSCHEMA

warehouse

(Opcional) Warehouse a ser usado ao executar a instrução. O valor nesse campo diferencia entre maiúsculas e minúsculas.

Se você omitir este campo, a API do SQL utilizará o valor da propriedade DEFAULT_WAREHOUSE do usuário.

Tipo: cadeia de caracteres

Exemplo: TESTWH

role

(Opcional) Função a ser usada ao executar a instrução. O valor nesse campo diferencia entre maiúsculas e minúsculas.

Se você omitir este campo, a API do SQL utilizará o valor da propriedade DEFAULT_ROLE do usuário.

Tipo: cadeia de caracteres

Exemplo: TESTROLE

bindings

(Opcional) Valores das variáveis de vinculação na instrução SQL. Ao executar a instrução, o Snowflake substitui os placeholders (? e :name) na instrução por esses valores especificados.

Observe que o formato desse campo pode mudar para o lançamento GA da API do SQL.

Tipo: objeto

Exemplo:

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

parameters

(Opcional) Parâmetros de sessão que você deseja definir para essa solicitação.

Tipo: objeto (statements_parameters)

Exemplo

A seguir, veja um exemplo do objeto do corpo:

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

statements_parameters

statements_parameters é um objeto JSON que você usa para especificar os parâmetros de sessão que você deseja definir para esta solicitação. Esse objeto deve estar no campo parameters do corpo da solicitação POST para o ponto de extremidade /api/v2/statements (consulte Corpo da solicitação POST para /api/v2/statements/).

Nota

A API do SQL somente oferecem suporte para os parâmetros de sessão listados na tabela a seguir.

Campos

Campo

Descrição

binary_output_format

(Opcional) Especifica o formato para valores VARCHAR retornados como saída por funções de conversão de BINARY para VARCHAR. Para obter mais detalhes, consulte BINARY_OUTPUT_FORMAT.

Tipo: cadeia de caracteres

Exemplo: HEX

client_result_chunk_size

(Opcional) Especifica o tamanho máximo de cada conjunto (ou parte) de resultados de consulta para download (em MB). Para obter mais detalhes, consulte CLIENT_RESULT_CHUNK_SIZE.

Tipo: inteiro

Exemplo: 100

date_output_format

(Opcional) Especifica o formato de exibição para o tipo de dados DATE. Para obter mais detalhes, consulte DATE_OUTPUT_FORMAT. Consulte Formatação da saída dos resultados da consulta para obter detalhes sobre o uso de parâmetros para determinar o formato de saída dos resultados da consulta.

Tipo: cadeia de caracteres

Exemplo: YYYY-MM-DD

multi_statement_count

(Obrigatório ao especificar mais de uma instrução SQL em uma solicitação) Especifica o número de instruções SQL a serem enviadas em uma solicitação ao usar a capacidade de múltiplas instruções. Os valores válidos são:

  • 0: Indica que um número variável de instruções pode ser incluído na solicitação.

  • 1: Indica que uma única instrução SQL pode ser incluída na solicitação. Esse é o valor padrão usado se você não especificar o campo MULTI_STATEMENT_COUNT.

  • > 1: Indica o número de instruções SQL enviadas na solicitação. Esse número deve corresponder ao número de instruções especificadas no campo statement.

Tipo: cadeia de caracteres

Exemplo: 2

query_tag

(Opcional) Tag de consulta que você deseja associar com a instrução SQL. Para obter mais detalhes, consulte o parâmetro QUERY_TAG.

Tipo: cadeia de caracteres

Exemplo: tag-1234

rows_per_resultset

(Opcional) Especifica o número máximo de linhas retornadas em um conjunto de resultados, com 0 (padrão) significando sem máximo. Para obter mais detalhes, consulte o parâmetro ROWS_PER_RESULTSET.

Tipo: inteiro

Exemplo: 200

time_output_format

(Opcional) Especifica o formato de exibição para o tipo de dados TIME. Para obter mais detalhes, consulte TIME_OUTPUT_FORMAT. Consulte Formatação da saída dos resultados da consulta para obter detalhes sobre o uso de parâmetros para determinar o formato de saída dos resultados da consulta.

Tipo: cadeia de caracteres

Exemplo: HH24:MI:SS

timestamp_ltz_output_format

(Opcional) Especifica o formato de exibição para o tipo de dados TIMESTAMP_LTZ. Para obter mais detalhes, consulte TIMESTAMP_LTZ_OUTPUT_FORMAT. Consulte Formatação da saída dos resultados da consulta para obter detalhes sobre o uso de parâmetros para determinar o formato de saída dos resultados da consulta.

Tipo: cadeia de caracteres

Exemplo: YYYY-MM-DD HH24:MI:SS.FF3

timestamp_ntz_output_format

(Opcional) Especifica o formato de exibição para o tipo de dados TIMESTAMP_NTZ. Para obter mais detalhes, consulte TIMESTAMP_NTZ_OUTPUT_FORMAT. Consulte Formatação da saída dos resultados da consulta para obter detalhes sobre o uso de parâmetros para determinar o formato de saída dos resultados da consulta.

Tipo: cadeia de caracteres

Exemplo: YYYY-MM-DD HH24:MI:SS.FF3

timestamp_output_format

(Opcional) Especifica o formato de exibição para o alias de tipo de dados TIMESTAMP. Para obter mais detalhes, consulte TIMESTAMP_OUTPUT_FORMAT. Consulte Formatação da saída dos resultados da consulta para obter detalhes sobre o uso de parâmetros para determinar o formato de saída dos resultados da consulta.

Tipo: cadeia de caracteres

Exemplo: YYYY-MM-DD HH24:MI:SS.FF3 TZHTZM

timestamp_tz_output_format

(Opcional) Especifica o formato de exibição para o tipo de dados TIMESTAMP_TZ. Para obter mais detalhes, consulte TIMESTAMP_TZ_OUTPUT_FORMAT. Consulte Formatação da saída dos resultados da consulta para obter detalhes sobre o uso de parâmetros para determinar o formato de saída dos resultados da consulta.

Tipo: cadeia de caracteres

Exemplo: YYYY-MM-DD HH24:MI:SS.FF3

timezone

(Opcional) Fuso horário a ser usado ao executar a instrução. Para obter mais detalhes, consulte o parâmetro TIMEZONE.

Tipo: cadeia de caracteres

Exemplo: america/los_angeles

use_cached_result

(Opcional) Se os resultados da consulta podem ser reutilizados entre sucessivas invocações da mesma consulta, desde que o resultado original não tenha expirado. Para obter mais detalhes, consulte o parâmetro USE_CACHED_RESULT

Tipo: cadeia de caracteres

Exemplo: true

Códigos de resposta para todas as operações

Esta seção lista os códigos de resposta que se aplicam a todas as operações.

Código

Descrição

400

Solicitação incorreta.

A carga útil da solicitação é inválida ou malformada. Isso acontece se o aplicativo não tiver enviado a carga útil de solicitação correta. O corpo de resposta pode incluir o código de erro e a mensagem indicando a causa real. O aplicativo deve reconstituir o corpo da solicitação para nova tentativa.

A seguir você vê um exemplo de resposta:

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."
}
Copy

401

Não autorizado.

O pedido não é autorizado. Isso acontece se o token de acesso anexado for inválido ou estiver faltando. O corpo de resposta pode incluir o código de erro e a mensagem indicando a causa real, como expirado ou token inválido. O aplicativo deve obter um novo token de acesso para nova tentativa.

Consulte Autenticação no servidor.

A seguir você vê um exemplo de resposta:

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"
}
Copy

403

Proibido.

A solicitação é proibida. Isso acontece se a solicitação for feito mesmo que a API não esteja habilitada.

404

Não encontrado.

O ponto de extremidade da solicitação não é válido. Isso acontece se o ponto de extremidade da API estiver errado. Por exemplo, se o aplicativo solicita /api/v2/hello, que não existe, o servidor retorna esse código.

405

Método não permitido.

O método de solicitação não corresponde à API suportada. Isso acontece, por exemplo, se o aplicativo chamar a API com o método GET, mas o ponto de extremidade aceitar apenas POST. O aplicativo deve usar um método suportado ao enviar o pedido.

A seguir você vê um exemplo de resposta:

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

415

O cabeçalho da solicitação Content-Type inclui um tipo de mídia não suportado.

A API somente oferece suporte para application/json. Se nenhum Content-Type for especificado, a carga útil da solicitação é interpretada como JSON, mas se qualquer outro tipo de mídia for especificado, esse erro é retornado.

429

Excesso de solicitações.

O número de solicitações atingiu o limite de taxa. O aplicativo deve reduzir a frequência das solicitações enviadas para os pontos de extremidade da API. O aplicativo pode tentar novamente com retirada. Recomenda-se usar uma retirada exponencial com jitter.

Essa resposta também pode ocorrer quando o servidor recebe solicitações simultâneas em excesso. Os limites de simultaneidade da API são determinados pelos limites de simultaneidade impostos pelo Snowflake.

A seguir você vê um exemplo de resposta:

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

500

Erro interno do servidor.

O servidor encontrou um erro irrecuperável no sistema. O corpo de resposta pode incluir o código e a mensagem do erro para maior orientação.

503

Serviço indisponível.

A solicitação não foi processada devido ao esgotamento do tempo limite no servidor. O aplicativo pode tentar novamente com retirada. Recomenda-se usar uma retirada exponencial com jitter.

504

Tempo limite do gateway.

A solicitação não foi processada devido ao esgotamento do tempo limite no servidor. O aplicativo pode tentar novamente com retirada. Recomenda-se usar uma retirada exponencial com jitter.

Cabeçalhos de resposta para todas as operações

As respostas podem conter os seguintes cabeçalhos:

Cabeçalho

Descrição

Link

Esse cabeçalho está na resposta 200 para uma solicitação para executar a instrução e uma solicitação para verificar o status da execução de uma instrução.

Esse cabeçalho fornece links para outras partições de resultados (por exemplo, a primeira partição, a última partição, etc.). O cabeçalho pode incluir múltiplas entradas de URL com diferentes valores de atributos rel que especificam a partição a retornar (first, next, prev e last).

Por exemplo:

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

Tipos de objetos no corpo de resposta

CancelStatus

CancelStatus é um objeto JSON que contém informações sobre o cancelamento da execução de uma instrução. Esse objeto é retornado no corpo da resposta para uma solicitação de cancelamento.

Campos

Campo

Descrição

code

Tipo: cadeia de caracteres

sqlState

Tipo: cadeia de caracteres

message

Exemplo: successfully cancelled

Tipo: cadeia de caracteres

statementHandle

Identificador único para a instrução que está sendo executada.

Tipo: cadeia de caracteres (uma UUID)

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

statementStatusUrl

URL para obter o status da instrução e o conjunto de resultados.

Tipo: cadeia de caracteres (uma URL)

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

Exemplo

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

QueryFailureStatus

QueryFailureStatus é um objeto JSON que contém informações sobre uma falha na execução de uma instrução. Esse objeto é retornado no corpo da resposta 422 para uma solicitação para executar a instrução.

Campos

Campo

Descrição

code

Tipo: cadeia de caracteres

Exemplo: 0

sqlState

Tipo: cadeia de caracteres

message

Tipo: cadeia de caracteres

Exemplo: successfully executed

statementHandle

Identificador único para a instrução que está sendo executada.

Tipo: cadeia de caracteres (uma UUID)

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

createdOn

Carimbo de data/hora que especifica quando a execução da instrução começou. O carimbo de data/hora é expresso em milissegundos desde a época.

Tipo: integer assinado de 64 bits

Exemplo: 1597090533987

statementStatusUrl

URL para obter o status da instrução e o conjunto de resultados.

Tipo: cadeia de caracteres (uma URL)

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

Exemplo

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

QueryStatus

QueryStatus é um objeto JSON que contém informações sobre o status da execução de uma instrução. Esse objeto é retornado no seguinte:

Campos

Campo

Descrição

code

Tipo: cadeia de caracteres

Exemplo: 0

sqlState

Tipo: cadeia de caracteres

message

Tipo: cadeia de caracteres

Exemplo: successfully executed

statementHandle

Identificador único para a instrução que está sendo executada.

Tipo: cadeia de caracteres (uma UUID)

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

createdOn

Carimbo de data/hora que especifica quando a execução da instrução começou. O carimbo de data/hora é expresso em milissegundos desde a época.

Tipo: integer assinado de 64 bits

Exemplo: 1597090533987

statementStatusUrl

URL para obter o status da instrução e o conjunto de resultados.

Tipo: cadeia de caracteres (uma URL)

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

Exemplo

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

ResultSet

ResultSet é um objeto JSON que contém os resultados da execução de uma instrução. Esse objeto é retornado no corpo da resposta 200 para uma solicitação para executar a instrução e uma solicitação para verificar o status da execução de uma instrução.

Campos

Campo

Descrição

code

Tipo: cadeia de caracteres

Exemplo: 0

sqlState

Tipo: cadeia de caracteres

message

Tipo: cadeia de caracteres

Exemplo: successfully executed

statementHandle

Identificador único para a instrução que está sendo executada.

Se várias instruções tiverem sido especificadas no pedido, esse identificador corresponderá ao conjunto dessas instruções. Para os identificadores das instruções individuais na solicitação, veja o campo statementHandles.

Tipo: cadeia de caracteres (uma UUID)

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

statementHandles

Conjunto de identificadores únicos para as instruções que estão sendo executadas para esta solicitação.

Tipo: array de cadeias de caracteres (UUID)

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

createdOn

Carimbo de data/hora que especifica quando a execução da instrução começou. O carimbo de data/hora é expresso em milissegundos desde a época.

Exemplo: 1597090533987

statementStatusUrl

URL para obter o status da instrução e o conjunto de resultados.

Tipo: cadeia de caracteres (uma URL)

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

resultSetMetaData

Metadados sobre o conjunto de resultados retornado.

Tipo: objeto (ResultSet_resultSetMetaData)

data

Se a solicitação contiver uma única instrução SQL, este campo contém os dados do conjunto de resultados.

Um formato de conjunto de resultados é um conjunto de arrays em JSON:

  • Cada conjunto corresponde a uma única linha.

  • Os elementos em uma linha correspondem aos valores nas colunas para essa linha.

  • Os dados são codificados como cadeias de caracteres JSON, independentemente do tipo de dados do Snowflake.

Tipo: array de arrays

Exemplo:

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

Se o pedido contiver múltiplas instruções SQL, este campo conterá apenas a mensagem “Multiple statements executed successfully”. Para obter os resultados de cada instrução no pedido, obtenha as identificadores para as instruções no campo statementHandles e envie solicitações para obter os resultados de cada instrução.

stats

Para instruções DML, esse campo contém estatísticas sobre o número de linhas afetadas pela operação.

Tipo: objeto (ResultSet_stats)

ResultSet_resultSetMetaData

ResultSet_resultSetMetaData é um objeto JSON que contém metadados sobre os resultados da execução de uma instrução. Esse objeto está no campo resultSetMetaData do objeto ResultSet.

Campos

Campo

Descrição

partition

O número do índice da partição que você deseja retornar (onde 0 especifica a primeira partição de dados). O Snowflake retorna dados em partições. O Snowflake determina o número de partições e o tamanho de cada partição durante a execução. Você pode obter a lista de partições do objeto resultSetMetaData na resposta à solicitação POST.

Consulte Como obter os resultados da resposta para obter mais informações.

numRows

O número total de linhas de resultados.

Tipo: integer assinado de 64 bits

Exemplo: 100

format

Formato dos dados no conjunto de resultados.

Tipo: cadeia de caracteres

rowType

Conjunto de objetos ResultSet_resultSetMetaData_rowType que descrevem as colunas no conjunto de resultados.

Tipo: array de ResultSet_resultSetMetaData_rowType.

Exemplo:

[
 {"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}
]
Copy

ResultSet_resultSetMetaData_rowType

ResultSet_resultSetMetaData_rowType é um objeto JSON que descreve uma coluna em um conjunto de resultados. Uma array desses objetos está no campo rowType do objeto ResultSet_resultSetMetaData.

Campos

Campo

Descrição

name

Nome da coluna.

Tipo: cadeia de caracteres

type

Tipo de dados do Snowflake da coluna.

Tipo: cadeia de caracteres

length

Comprimento da coluna.

Tipo: integer assinado de 64 bits

precision

Precisão da coluna.

Tipo: integer assinado de 64 bits

scale

Escala da coluna.

Tipo: integer assinado de 64 bits

nullable

Especifica se a coluna é ou não anulável.

Tipo: booleano

Exemplo

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

ResultSet_stats

ResultSet_stats é um objeto JSON que contém estatísticas sobre a execução de uma instrução DML. Esse objeto está no campo stats do objeto ResultSet_resultSetMetaData.

Campos

Campo

Descrição

numRowsInserted

Número de linhas que foram inseridas.

Tipo: integer assinado de 64 bits

Exemplo: 12

numRowsUpdated

Número de linhas que foram atualizadas.

Tipo: integer assinado de 64 bits

Exemplo: 9

numRowsDeleted

Número de linhas que foram eliminadas.

Tipo: integer assinado de 64 bits

Exemplo: 8

numDuplicateRowsUpdated

Número de linhas duplicadas que foram atualizadas.

Tipo: integer assinado de 64 bits

Exemplo: 20