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

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

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.