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:

Nota

A execução de várias instruções em uma única consulta requer que um warehouse válido esteja disponível em uma sessão.

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

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

Onde

  • actual_count é o número de instruções especificado no campo statement.

  • desired_count é o valor de MULTI_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.
Copy

Nota

Atualmente, o Snowflake não oferece suporte à vinculação de variáveis em solicitações SQL de múltiplas instruções.

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

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

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
...
Copy
GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02416
...
Copy

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

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

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.

Linguagem: Português