Envio de múltiplas instruções SQL em apenas uma solicitação¶
Este tópico explica como enviar uma solicitação contendo múltiplas instruções à API de SQL do Snowflake.
Neste tópico:
Introdução¶
Em alguns casos, pode ser necessário especificar várias instruções SQL em um pedido. Por exemplo, você pode precisar:
Definir uma transação explícita
Definir e usar variáveis de sessão em instruções em uma solicitação
Criar e utilizar tabelas temporárias em instruções em uma solicitação
Alterar o banco de dados, esquema, warehouse ou função para instruções em uma solicitação
As seções a seguir explicam como apresentar uma solicitação contendo múltiplas instruções SQL.
Como especificar múltiplas instruções SQL na solicitação¶
Para enviar múltiplas instruções SQL em uma única solicitação:
No campo
statement
, use um ponto-e-vírgula (;
) entre cada instrução.No campo
parameters
, defina o campoMULTI_STATEMENT_COUNT
como o número de instruções SQL na solicitação.
Por exemplo:
POST /api/v2/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT
{
"statement": "alter session set QUERY_TAG='mytesttag'; select count(*) from mytable",
...
"parameters": {
"MULTI_STATEMENT_COUNT": "2"
}
}
Neste exemplo, MULTI_STATEMENT_COUNT
é definido como 2
, o que corresponde ao número de instruções SQL que estão sendo enviadas.
Para enviar um número variável de instruções SQL no campo statement
, defina MULTI_STATEMENT_COUNT
como 0
. Isso é útil em um aplicativo onde o número de instruções SQL enviadas não é conhecido no momento da execução.
Se o valor de MULTI_STATEMENT_COUNT
não corresponder ao número de instruções SQL especificadas no campo statement
, a API de SQL retorna o seguinte erro:
Actual statement count <actual_count> did not match the desired statement count <desired_count>.
Onde
actual_count
é o número de instruções especificado no campostatement
.desired_count
é o valor deMULTI_STATEMENT_COUNT
.
Se você especificar várias instruções SQL no campo statement
, mas não especificar o campo MULTI_STATEMENT_COUNT
, a API de SQL retorna o seguinte erro:
Actual statement count 3 did not match the desired statement count 1.
Como obter os resultados de cada instrução SQL na solicitação¶
Se uma solicitação que contém múltiplas instruções SQL for processada com sucesso, a resposta não incluirá os dados retornados da execução das instruções individuais. Em vez disso, a resposta conterá um campo statementHandles
com uma array dos identificadores das instruções individuais.
Nota
O campo statementHandles
é diferente do campo statementHandle
:
O campo
statementHandle
especifica o identificador para o conjunto de instruções SQL na solicitação.O campo
statementHandles
é uma array dos identificadores das instruções SQL individuais na solicitação.
Por exemplo, suponha que você envie uma solicitação que especifique duas instruções SQL para execução:
POST /api/v2/statements HTTP/1.1
Authorization: Bearer <jwt>
Content-Type: application/json
Accept: application/json
User-Agent: myApplication/1.0
X-Snowflake-Authorization-Token-Type: KEYPAIR_JWT
{
"statement": "select * from A; select * from B",
...
}
A resposta contém um campo statementHandles
com uma array dos identificadores das instruções individuais.
HTTP/1.1 200 OK
...
{
...
"statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
...
}
Para verificar o status e recuperar os dados para as instruções individuais, envie uma solicitação GET
ao ponto de extremidade /api/v2/statements/
e adicione o identificador para cada declaração ao caminho da URL. Consulte Como verificar o status de execução da instrução e obter os dados para obter mais detalhes.
GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02412
...
GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02416
...
Tratamento de erros na especificação de instruções múltiplas em uma solicitação¶
Se você tiver especificado várias instruções SQL na solicitação e um erro tiver ocorrido ao executar qualquer uma das instruções, o Snowflake retornará o código de resposta HTTP 422 com um objeto QueryFailureStatus.
Você pode obter detalhes sobre o erro a partir desse objeto.
Por exemplo, suponha que sua solicitação especifique as seguintes instruções nas quais a segunda instrução INSERT contém um erro:
{
"statement": "create or replace table table1 (i int); insert into table1 (i) values (1); insert into table1 (i) values ('This is not a valid integer.'); insert into table1 (i) values (2); select i from table1 order by i",
...
}
O Snowflake retorna uma resposta com o código de resposta HTTP 422 e com um objeto QueryFailureStatus
contendo os detalhes sobre o erro:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
...
{
"code" : "100132",
"message" : "JavaScript execution error: Uncaught Execution of multiple statements failed on statement \"insert into table1 (i) values ...\" (at line 1, position 75).\nNumeric value 'This is not a valid integer.' is not recognized in SYSTEM$MULTISTMT at ' throw `Execution of multiple statements failed on statement {0} (at line {1}, position {2}).`.replace('{1}', LINES[i])' position 4\nstackstrace: \nSYSTEM$MULTISTMT line: 10",
"sqlState" : "P0000",
"statementHandle" : "019d6e97-0502-317e-0000-096d0041f036"
}
No exemplo acima, a instrução INSERT com o erro começa na posição de caracteres 75 no valor do campo statement
.
As instruções antes da instrução com o erro são executadas com sucesso (a instrução CREATE TABLE e a primeira instrução INSERT nesse exemplo). As instruções após a instrução com o erro não são executadas.