Soumission de plusieurs instructions SQL dans une seule requête

Cette rubrique explique comment soumettre une requête contenant plusieurs instructions à l’API SQL Snowflake.

Dans ce chapitre :

Introduction

Parfois, vous pouvez avoir besoin de spécifier plusieurs instructions SQL dans une requête. Par exemple, vous pourriez avoir besoin de :

  • Définir une transaction explicite

  • Définir et utiliser des variables de session dans des instructions dans une requête

  • Créer et utiliser des tables temporaires dans des instructions dans une requête

  • Modifier la base de données, le schéma, l’entrepôt ou le rôle pour les instructions dans une requête

Les sections suivantes expliquent comment soumettre une requête contenant plusieurs instructions SQL.

Spécifier plusieurs instructions SQL dans la requête

Pour soumettre plusieurs instructions SQL dans une seule requête :

  • Dans le champ statement utilisez un point-virgule (;) entre chaque instruction.

  • Dans le champ parameters, définissez le champ MULTI_STATEMENT_COUNT sur le nombre de déclarations SQL dans l’instruction.

Par exemple :

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

Dans cet exemple, MULTI_STATEMENT_COUNT est défini sur 2 ce qui correspond au nombre d’instructions SQL soumises.

Pour soumettre un nombre variable d’instructions SQL dans le champ statement , réglez MULTI_STATEMENT_COUNT sur 0. Ceci est utile dans une application où le nombre d’instructions SQL soumises n’est pas connu au moment de l’exécution.

Si la valeur de MULTI_STATEMENT_COUNT ne correspond pas au nombre d’instructions SQL spécifiées dans le champ statement, l’API SQL renvoie l’erreur suivante :

Actual statement count <actual_count> did not match the desired statement count <desired_count>.
Copy

Where

  • actual_count est le nombre d’instructions spécifiées dans le champ statement.

  • desired_count est la valeur de MULTI_STATEMENT_COUNT.

Si vous spécifiez plusieurs instructions SQL dans le champ statement, mais ne spécifiez pas le champ MULTI_STATEMENT_COUNT, l’API SQL renvoie l’erreur suivante :

Actual statement count 3 did not match the desired statement count 1.
Copy

Obtenir les résultats pour chaque instruction SQL dans la requête

Pour qu’une requête contenant plusieurs instructions SQL soit traitée correctement, la réponse n’inclut pas les données renvoyées par l’exécution des instructions individuelles. À la place, la réponse contient un champ statementHandles qui contient un tableau de handles pour les instructions individuelles.

Note

Le champ statementHandles est différent du champ statementHandle :

  • Le champ statementHandle spécifie le handle pour l’ensemble des instructions SQL de la requête.

  • Le champ statementHandles est un tableau des handles des différentes instructions SQL de la requête.

Par exemple, supposons que vous envoyez une requête qui spécifie deux instructions SQL à exécuter :

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

La réponse contient un champ statementHandles qui contient un tableau de handles pour les instructions individuelles.

HTTP/1.1 200 OK
...
{
  ...
  "statementHandles" : [ "019c9fce-0502-f1fc-0000-438300e02412", "019c9fce-0502-f1fc-0000-438300e02416" ],
  ...
}
Copy

Pour vérifier le statut et récupérer les données de chaque instruction individuelle, envoyez une requête GET au point de terminaison /api/v2/statements/ et joignez l’handle de chaque instruction au chemin de l’URL. Voir Vérification du statut de l’exécution de l’instruction et récupération des données pour plus de détails.

GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02412
...
Copy
GET /api/v2/statements/019c9fce-0502-f1fc-0000-438300e02416
...
Copy

Traitement des erreurs lors de la spécification de plusieurs instructions dans une requête

Si vous avez spécifié plusieurs instructions SQL dans la requête et qu’une erreur s’est produite lors de l’exécution de l’une d’entre elles, Snowflake renvoie le code de réponse HTTP 422 avec un objet QueryFailureStatus.

Vous pouvez obtenir des détails sur l’erreur à partir de cet objet.

Par exemple, supposons que votre demande spécifie les instructions suivantes, dans lesquelles la deuxième instruction INSERT contient une erreur :

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

Snowflake renvoie une réponse avec le code de réponse HTTP 422 et un objet QueryFailureStatus qui contient les détails de l’erreur :

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

Dans l’exemple ci-dessus, l’instruction INSERT contenant l’erreur commence à la position du caractère 75 dans la valeur du champ statement.

Les instructions précédant l’instruction contenant l’erreur sont exécutées avec succès (l’instruction CREATE TABLE et la première instruction INSERT dans cet exemple). Les instructions qui suivent l’instruction contenant l’erreur ne sont pas exécutées.