Referência da API de SQL do Snowflake¶

requestId

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

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.

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

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

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" ], ... ]

200

A instrução foi executada com sucesso.

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

• Link

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

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
}

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
}

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
}

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.

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.

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.

200

A instrução foi executada com sucesso.

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

• Link

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
}

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.

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.

requestId

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

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

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

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

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

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

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

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

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

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_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_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

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

code

Tipo: cadeia de caracteres

message

Exemplo: successfully cancelled

Tipo: cadeia de caracteres

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

code

Tipo: cadeia de caracteres

Exemplo: 0

message

Tipo: cadeia de caracteres

Exemplo: successfully executed

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

code

Tipo: cadeia de caracteres

Exemplo: 0

message

Tipo: cadeia de caracteres

Exemplo: successfully executed

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

code

Tipo: cadeia de caracteres

Exemplo: 0

message

Tipo: cadeia de caracteres

Exemplo: successfully executed

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" ]

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

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"]
]

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.

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.

format

Formato dos dados no conjunto de resultados.

Tipo: cadeia de caracteres

name

Nome da coluna.

Tipo: cadeia de caracteres

length

Comprimento da coluna.

Tipo: integer assinado de 64 bits

scale

Escala da coluna.

Tipo: integer assinado de 64 bits

numRowsInserted

Número de linhas que foram inseridas.

Tipo: integer assinado de 64 bits

Exemplo: 12

numRowsDeleted

Número de linhas que foram eliminadas.

Tipo: integer assinado de 64 bits

Exemplo: 8