Soumission d’une requête d’exécution d’instructions SQL¶

Création de la requête¶

Dans l’URL de la requête, vous pouvez définir les paramètres de la requête pour :

• Spécifier un ID de requête qui distingue cette requête des autres requêtes.

• Exécuter l’instruction de manière asynchrone.

Pour le corps de la requête, définissez les champs suivants :

• Définissez le champ statement sur l’instruction SQL que vous voulez exécuter. Par exemple :

  {
    "statement": "select * from my_table",
    ...
  }
  

  Copy

  Si vous souhaitez soumettre plusieurs instructions dans une seule requête, utilisez un point-virgule (;) entre les instructions. Voir Soumission de plusieurs instructions SQL dans une seule requête pour plus de détails.

• Si vous incluez des variables de liaison (caractères de remplacement ?) dans l’instruction, définissez le champ bindings sur un objet qui spécifie les types de données Snowflake correspondants et les valeurs pour chaque variable.

  Pour plus de détails, voir Utilisation de variables de liaison dans une instruction.

• Pour spécifier l’entrepôt, la base de données, le schéma et le rôle à utiliser, définissez les champs warehouse, database, schema et role.

  Les valeurs de ces champs sont sensibles à la casse.

  Si vous omettez ces champs, l’API SQL utilise les valeurs des propriétés correspondantes pour l’utilisateur (c’est-à-dire le DEFAULT_WAREHOUSE, le DEFAULT_NAMESPACE, et DEFAULT_ROLE les propriétés de l’utilisateur).

• Pour définir un délai d’expiration pour l’exécution de l’instruction, définissez le champ timeout sur le nombre maximal de secondes à attendre. Si le champ timeout n’est pas défini, le délai d’expiration spécifié par le paramètre STATEMENT_TIMEOUT_IN_SECONDS est utilisé.

Exemple de requête¶

Par exemple, la commande curl suivante envoie une instruction SQL pour exécution. L’exemple utilise le fichier request-body.json pour spécifier le corps de la requête.

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"

où :

• jwt est le JWT que vous avez généré pour l’authentification.

• myApplicationName est un exemple d’identificateur pour votre application.

• account_identifier est votre identificateur de compte.

Dans cet exemple, request-body.json contient le corps de la requête :

{
  "statement": "select * from T where c1=?",
  "timeout": 60,
  "database": "TESTDB",
  "schema": "TESTSCHEMA",
  "warehouse": "TESTWH",
  "role": "TESTROLE",
  "bindings": {
    "1": {
      "type": "FIXED",
      "value": "123"
    }
  }
}

Dans le corps de la requête de l’exemple ci-dessus :

• Le champ statement spécifie l’instruction SQL à exécuter.

  L’instruction comprend une variable de liaison (le point d’interrogation dans "cl=?"), qui est évaluée à la première liaison ("1") spécifiée dans le champ bindings.

• Le champ timeout indique que le serveur accorde 60 secondes pour l’exécution de l’instruction.

• Les champs database, schema, warehouse et role indiquent que la base de données TESTDB, le schéma TESTSCHEMA, l’entrepôt TESTWH et le rôle TESTROLE doivent être utilisés lors de l’exécution de l’instruction.

Utilisation de variables de liaison dans une instruction¶

Si vous souhaitez utiliser des variables de liaison (caractères de remplacement ?) dans l’instruction, utilisez le champ bindings pour spécifier les valeurs à insérer.

Définissez ce champ comme un objet JSON qui spécifie le type de données Snowflake et la valeur de chaque variable de liaison.

...
"statement": "select * from T where c1=?",
...
"bindings": {
  "1": {
    "type": "FIXED",
    "value": "123"
  }
},
...

Sélectionnez le type de liaison qui correspond au type de la valeur que vous liez. Par exemple, si la valeur est une chaîne représentant une date (par exemple 2021-04-15) et que vous souhaitez insérer cette valeur dans une colonne DATE, utilisez le type de liaison TEXT.

Le tableau suivant spécifie les valeurs du champ type que vous pouvez utiliser pour lier différents types de données Snowflake pour cette version préliminaire.

• La première colonne de gauche indique les types de liaisons que vous pouvez utiliser.

• Le reste des colonnes spécifie le type de données Snowflake de la colonne dans laquelle vous prévoyez d’insérer les données.

• Chaque cellule spécifie le type de valeur que vous pouvez utiliser avec un type de liaison pour insérer des données dans une colonne d’un type de données Snowflake particulier.

  Si la cellule d’un type de liaison et d’un type de données Snowflake est vide, vous ne pouvez pas utiliser le type de liaison spécifié pour insérer des données dans une colonne de ce type de données Snowflake.

Remarques :

• Les valeurs des variables de liaison doivent être des chaînes de caractères (par exemple, "1.0" pour la valeur 1.0).

• Lorsque vous utilisez le type de liaison DATE, indiquez le nombre de millisecondes depuis l’epoch.

• Lorsque vous utilisez le type de liaison TIME ou TIMESTAMP*, indiquez le nombre de nanosecondes depuis l’epoch.

• Lorsque vous utilisez le type de liaison TIMESTAMP_TZ, indiquez le nombre de nanosecondes depuis l’epoch, suivi d’un espace et du décalage du fuseau horaire en minutes (par exemple, 1616173619000000000 960).

• Lorsque vous utilisez le type de liaison TEXT :

  • Pour insérer des données dans une colonne DATE, vous pouvez utiliser tout format de date pris en charge par la détection AUTO.

  • Pour insérer des données dans une colonne TIME, vous pouvez utiliser n’importe quel format d’heure qui est pris en charge par la détection AUTO.

  • Pour insérer des données dans une colonne TIMEZONE*, vous pouvez utiliser n’importe quel format de date-heure pris en charge par la détection AUTO.

Si la valeur est dans un format non pris en charge par Snowflake, l’API renvoie une erreur :

{
  code: "100037",
  message: "<bind type> value '<value>' is not recognized",
  sqlState: "22018",
  statementHandle: "<ID>"
}

Soumission de requêtes simultanées¶

L’API SQL de Snowflake prend en charge l’envoi de requêtes simultanées au serveur. Les limites d’accès concurrentiel sur l’API sont déterminées par les limites d’accès concurrentiel appliquées par Snowflake.

Selon la charge actuelle du serveur, vous pouvez recevoir une erreur HTTP 429 qui pourrait indiquer que le serveur reçoit actuellement trop de requêtes.

Pour que votre application traite correctement les erreurs 429, intégrez les requêtes simultanées dans une logique de nouvelles tentatives.

Nouvelle soumission d’une requête d’exécution d’instructions SQL¶

Dans certains cas, il peut être difficile de savoir si Snowflake a exécuté l’instruction SQL dans une requête API (par exemple, en raison d’une erreur de réseau ou d’un dépassement de délai). Vous pouvez choisir de soumettre à nouveau la même requête à Snowflake, au cas où Snowflake n’aurait pas exécuté l’instruction.

Cependant, si Snowflake a déjà exécuté l’instruction dans la requête initiale et que vous soumettez à nouveau la requête, l’instruction est exécutée deux fois. Pour certains types de requêtes, l’exécution répétée de la même instruction peut avoir des conséquences inattendues (par exemple, l’insertion de données en double dans une table).

Pour éviter que Snowflake n’exécute deux fois la même instruction lorsque vous soumettez à nouveau une requête, vous pouvez utiliser un ID de requête pour distinguer votre requête des autres requêtes. Si vous spécifiez le même ID de requête dans la requête initiale avec le paramètre retry=true dans la requête resoumise, Snowflake n’exécute pas à nouveau l’instruction si celle-ci a déjà été exécutée avec succès.

Pour spécifier un ID de demande, générez un identificateur unique universel (UUID). Vous pouvez ensuite inclure cet identificateur dans le paramètre de requête requestId. Vous devez également spécifier le paramètre retry=true dans le cadre de la requête, comme le montre l’exemple suivant.

POST /api/v2/statements?requestId=ea7b46ed-bdc1-8c32-d593-764fcad64e83&retry=true HTTP/1.1

Si Snowflake ne parvient pas à traiter une requête, vous pouvez soumettre à nouveau la même requête avec le même ID de requête. L’utilisation du même ID de requête indique au serveur que vous soumettez à nouveau la même requête.