Enviar uma solicitação para executar instruções SQL¶
Este tópico explica como apresentar uma solicitação à API do SQL.
Neste tópico:
Para enviar instruções SQL para execução, envie uma solicitação POST
para o ponto de extremidade /api/v2/statements/
. Consulte POST /api/v2/statements para obter mais detalhes.
POST /api/v2/statements HTTP/1.1
(request body)
Como configurar a solicitação¶
Na URL de solicitação, você pode definir parâmetros de consulta para:
Especifique uma ID de solicitação que distingue essa solicitação de outras solicitações.
Execute a instrução de forma assíncrona.
Para o corpo da solicitação, defina os seguintes campos:
Defina o campo
statement
para a instrução SQL que você deseja executar. Por exemplo:{ "statement": "select * from my_table", ... }
Se você quiser apresentar várias instruções em uma única solicitação, use um ponto-e-vírgula (
;
) entre as instruções. Consulte Envio de múltiplas instruções SQL em apenas uma solicitação para obter mais detalhes.Se você incluir variáveis de vinculação (placeholders
?
) na instrução, defina o campobindings
como um objeto que especifique os valores e tipos de dados do Snowflake correspondentes para cada variável.Para obter mais detalhes, consulte Como usar variáveis de vinculação em uma instrução.
Para especificar o warehouse, banco de dados, esquema e função a usar, defina os campos
warehouse
,database
,schema
erole
.Os valores nesses campos diferenciam entre maiúsculas e minúsculas.
Se você omitir esses campos, a API do SQL utilizará os valores das propriedades correspondentes para o usuário (isso é, as propriedades
DEFAULT_WAREHOUSE
,DEFAULT_NAMESPACE
eDEFAULT_ROLE
do usuário).Para definir um tempo limite para a execução da instrução, defina o campo
timeout
com o número máximo de segundos a esperar. Se o campotimeout
não estiver definido, será usado o tempo limite especificado pelo parâmetro STATEMENT_TIMEOUT_IN_SECONDS.
Exemplo de uma solicitação¶
Por exemplo, o seguinte comando curl
envia uma instrução SQL para execução. O exemplo usa o arquivo request-body.json
para especificar o corpo da solicitação.
curl -i -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <jwt>" \
-H "Accept: application/json" \
-H "User-Agent: myApplicationName/1.0" \
-H "X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT" \
-d "@request-body.json" \
"https://<account_identifier>.snowflakecomputing.com/api/v2/statements"
onde:
myApplicationName
é um exemplo de um identificador para seu aplicativo.account_identifier
é seu identificador da conta.
Neste exemplo, request-body.json
contém o corpo da solicitação:
{
"statement": "select * from T where c1=?",
"timeout": 60,
"database": "TESTDB",
"schema": "TESTSCHEMA",
"warehouse": "TESTWH",
"role": "TESTROLE",
"bindings": {
"1": {
"type": "FIXED",
"value": "123"
}
}
}
No corpo da solicitação no exemplo acima:
O campo
statement
especifica a instrução SQL a ser executada.A instrução inclui uma variável de vinculação (o ponto de interrogação em
"cl=?"
), que é avaliada como a primeira vinculação ("1"
) especificada no campobindings
.O campo
timeout
especifica que o servidor permite 60 segundos para que a instrução seja executada.Os campos
database
,schema
,warehouse
erole
especificam que a o banco de dadosTESTDB
, o esquemaTESTSCHEMA
, o warehouseTESTWH
e a funçãoTESTROLE
devem ser usadas ao executar a instrução.
Como usar variáveis de vinculação em uma instrução¶
Se você quiser usar variáveis de vinculação (placeholders ?
) na instrução, use o campo bindings
para especificar os valores que devem ser inseridos.
Defina este campo como um objeto JSON que especifique o tipo de dados do Snowflake e valor para cada variável de vinculação.
...
"statement": "select * from T where c1=?",
...
"bindings": {
"1": {
"type": "FIXED",
"value": "123"
}
},
...
Escolha o tipo de vinculação que corresponde ao tipo do valor que você está vinculando. Por exemplo, se o valor for uma cadeia de caracteres representando uma data (por exemplo, 2021-04-15
) e você quiser inserir o valor em uma coluna DATE, use o tipo de vinculação TEXT
.
A tabela a seguir especifica os valores do campo type
que você pode usar para vincular a diferentes tipos de dados do Snowflake para esta versão preliminar.
A primeira coluna à esquerda especifica os tipos de vinculação que você pode usar.
O resto das colunas especificam o tipo de dados do Snowflake da coluna onde você pretende inserir os dados.
Cada célula especifica o tipo de valor que você pode usar com um tipo de vinculação para inserir dados em uma coluna de um determinado tipo de dados do Snowflake.
Se a célula para um tipo de vinculação e tipo de dados do Snowflake estiver vazia, não será possível usar o tipo de vinculação especificado para inserir dados em uma coluna desse tipo de dados do Snowflake.
Tipos de dados do Snowflake |
INT / NUMBER |
FLOAT |
VARCHAR |
BINARY |
BOOLEAN |
DATE |
TIME |
TIMESTAMP_TZ |
TIMESTAMP_LTZ |
TIMESTAMP_NTZ |
---|---|---|---|---|---|---|---|---|---|---|
Tipos de . vinculação |
||||||||||
FIXED |
inteiro |
inteiro |
inteiro |
0 (falso) / não zero (verdadeiro) |
||||||
REAL |
inteiro |
int ou float |
int ou float |
0/não-0 |
||||||
TEXT |
inteiro |
int ou float |
qualquer texto |
hexdec |
|
consulte as notas abaixo |
consulte as notas abaixo |
consulte as notas abaixo |
consulte as notas abaixo |
consulte as notas abaixo |
BINARY |
hexdec |
|||||||||
BOOLEAN |
verdadeiro/falso, 0/1 |
verdadeiro/falso |
||||||||
DATE |
época (ms) |
época (ms) |
época (ms) |
época (ms) |
época (ms) |
|||||
TIME |
época (nano) |
época (nano) |
||||||||
TIMESTAMP_TZ |
época (nano) |
época (nano) |
época (nano) |
época (nano) |
||||||
TIMESTAMP_LTZ |
época (nano) |
época (nano) |
época (nano) |
época (nano) |
época (nano) |
época (nano) |
||||
TIMESTAMP_NTZ |
época (nano) |
época (nano) |
época (nano) |
época (nano) |
época (nano) |
época (nano) |
Observe o seguinte:
Os valores das variáveis de vinculação devem ser cadeias de caracteres (por exemplo,
"1.0"
para o valor 1.0).Ao utilizar o tipo de vinculação DATE, especifique o número de milissegundos desde a época.
Ao utilizar o tipo de vinculação TIME ou TIMESTAMP*, especifique o número de nanossegundos desde a época.
Ao utilizar o tipo de vinculação TIMESTAMP_TZ, especifique o número de nanossegundos desde a época, seguido por um espaço e a diferença de fuso horário em minutos (por exemplo,
1616173619000000000 960
).Ao utilizar o tipo de vinculação
TEXT
:Para inserir dados em uma coluna DATE, você pode usar qualquer formato de data que seja suportado pela detecção AUTO.
Para inserir dados em uma coluna TIME, você pode usar qualquer formato de tempo que seja suportado pela detecção AUTO.
Para inserir dados em uma coluna TIMEZONE*, você pode usar qualquer formato de data-hora que seja suportado pela detecção AUTO.
Se o valor estiver em um formato não suportado pelo Snowflake, a API retornará um erro:
{
code: "100037",
message: "<bind type> value '<value>' is not recognized",
sqlState: "22018",
statementHandle: "<ID>"
}
Nota
Atualmente, o Snowflake não oferece suporte à vinculação de variáveis em solicitações SQL de múltiplas instruções.
Envio de solicitações simultâneas¶
A API do SQL no Snowflake oferece suporte para o envio de solicitações simultâneas ao servidor. Os limites de simultaneidade da API são determinados pelos limites de simultaneidade impostos pelo Snowflake.
Dependendo da carga atual do servidor, você pode ter um erro HTTP 429, que indica que o servidor está recebendo solicitações demais no momento.
Para garantir que seu aplicativo trate corretamente os erros 429, insira as solicitações simultâneas dentro de uma lógica de nova tentativa.
Como reenviar uma solicitação para executar instruções SQL¶
Em alguns casos, pode não estar claro se o Snowflake executou a instrução SQL em uma solicitação à API (por exemplo, devido a um erro na rede ou a um timeout). Você pode optar por reenviar a mesma solicitação ao Snowflake novamente caso o Snowflake não tenha executado a instrução.
Entretanto, se o Snowflake já tiver executado a instrução na solicitação inicial e você reenviar a solicitação, a instrução será executada duas vezes. Para alguns tipos de solicitações, a execução repetida da mesma instrução pode ter consequências não intencionais (por exemplo, a inserção de dados duplicados em uma tabela).
Para evitar que o Snowflake execute a mesma instrução duas vezes quando você reenvia uma solicitação, você pode usar uma ID de solicitação para distinguir sua solicitação de outras. Se você especificar a mesma ID de solicitação na solicitação inicial junto com o parâmetro retry=true
na solicitação reenviada, o Snowflake não executará a instrução novamente se a instrução já tiver sido executada com sucesso.
Para especificar uma ID de solicitação, gere um identificador único universal (UUID). Depois disso, você poderá incluir esse identificador no parâmetro de consulta requestId
. Você também deve especificar o parâmetro retry=true
como parte da solicitação, como mostrado no exemplo a seguir.
POST /api/v2/statements?requestId=ea7b46ed-bdc1-8c32-d593-764fcad64e83&retry=true HTTP/1.1
Se o Snowflake não processar uma solicitação, você poderá enviar a mesma solicitação novamente com a mesma ID de solicitação. Usar a mesma ID de solicitação indica ao servidor que você está enviando a mesma solicitação novamente.
Nota
O parâmetro retry=true
adiciona gastos ao processamento da instrução SQL porque o Snowflake precisa percorrer e corresponder a uma instrução no histórico de instruções. Somente use esse parâmetro quando for necessário tentar novamente a instrução.