EXECUTE IMMEDIATE FROM¶

Modélisation Jinja2¶

EXECUTE IMMEDIATE FROM peut également exécuter un fichier de modèle à l’aide du langage de modélisation Jinja2. Un modèle peut contenir des variables et des expressions, ce qui permet d’utiliser des boucles, des logiques conditionnelles, des substitutions de variable, des macros, etc.

Pour plus d’informations sur le langage de modélisation, voir la documentation Jinja2.

Le fichier de modèle à exécuter doit être :

• Un modèle Jinja2 valide d’un point de vue syntaxique.

• Situé dans une zone de préparation ou un référentiel Git.

• Capable d’effectuer un rendu d’instructions SQL valides d’un point de vue syntaxique.

La modélisation permet des structures de contrôle plus souples et une paramétrisation à l’aide de variables d’environnement. Par exemple, vous pouvez utiliser un modèle pour sélectionner dynamiquement la cible de déploiement des objets définis dans le script. Pour utiliser un modèle afin d’effectuer le rendu d’un script SQL, utilisez la directive de modélisation ou ajoutez une clause USING avec au moins une variable de modèle.

--!jinja

#!jinja

Syntaxe¶

EXECUTE IMMEDIATE
  FROM { absoluteFilePath | relativeFilePath }
  [ USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )  ]

Où :

absoluteFilePath ::=
   @[ <namespace>. ]<stage_name>/<path>/<filename>

Copy

relativeFilePath ::=
  '[ / | ./ | ../ ]<path>/<filename>'

Copy

Paramètres requis¶

Paramètres facultatifs¶

USING ( <key> => <value> [ , <key> => <value> [ , ... ] ]  )

Fonctionnalité en avant-première — Ouvrir

Disponible pour tous les comptes.

Vous permet de transmettre une ou plusieurs paires clé-valeur qui peuvent être utilisées pour paramétrer l’expansion de modèle. Les paires clé-valeur doivent former une liste séparée par des virgules.

Lorsque la clause USING est présente, le fichier est d’abord rendu sous forme de modèle Jinja2 avant d’être exécuté sous forme de script SQL.

Où :

• key est le nom de la variable de modèle. Le nom de variable de modèle peut éventuellement être placé entre guillemets doubles (").

• value est la valeur à attribuer à la variable du modèle. Les valeurs de chaîne doivent être encadrées par ' ou par $$. Pour un exemple, voir Notes sur l’utilisation de la modélisation.

Renvoie¶

EXECUTE IMMEDIATE FROM renvoie :

• Le résultat de la dernière instruction du fichier si toutes les instructions ont été exécutées avec succès.

• Le message d’erreur, si une instruction du fichier a échoué.

  En cas d’erreur dans une instruction dans le fichier, la commande EXECUTE IMMEDIATE FROM échoue et renvoie le message d’erreur de l’instruction défaillante.

  Note

  Si la commande EXECUTE IMMEDIATE FROM échoue et renvoie un message d’erreur, toutes les instructions du fichier précédant l’instruction ayant échoué se sont achevées avec succès.

Exigences en matière de contrôle d’accès¶

• Le rôle utilisé pour exécuter la commande EXECUTE IMMEDIATE FROM doit avoir le privilège USAGE (zone de préparation externe) ou READ (zone de préparation interne) sur la zone de préparation où se trouve le fichier.

• Le rôle utilisé pour exécuter le fichier ne peut exécuter que les instructions du fichier pour lesquelles il dispose de privilèges. Par exemple, si le fichier contient une instruction CREATE TABLE, le rôle doit disposer des privilèges nécessaires pour créer une table dans le compte, faute de quoi l’instruction échoue.

Notez que l’exploitation d’un objet dans un schéma requiert également le privilège USAGE sur la base de données et le schéma parents.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation¶

• Les instructions SQL d’un fichier à exécuter peuvent inclure des instructions EXECUTE IMMEDIATE FROM :

  • Les instructions EXECUTE IMMEDIATE FROM imbriquées peuvent utiliser des chemins de fichiers relatifs.

    Les chemins relatifs sont évalués par rapport à la zone de préparation et au chemin d’accès du fichier parent. Si le chemin d’accès relatif au fichier commence par /, le chemin d’accès commence au répertoire racine de la zone de préparation contenant le fichier parent.

    Pour un exemple, voir Exemples.

  • Les chemins d’accès relatifs aux fichiers doivent être placés entre guillemets simples (') ou ($$).

  • La profondeur d’exécution maximale pour les fichiers imbriqués est de 5.

• Les chemins d’accès absolus aux fichiers peuvent éventuellement être placés entre guillemets simples (') ou ($$).

• Le fichier à exécuter ne peut pas avoir une taille supérieure à 10MB.

• Le fichier à exécuter doit être codé en UTF-8.

• Le fichier à exécuter doit être décompressé. Si vous utilisez la commande PUT pour télécharger un fichier vers une zone de préparation interne, vous devez explicitement définir le paramètre AUTO_COMPRESS sur FALSE.

  Par exemple, télécharger my_file.sql vers my_stage :

  PUT file://~/sql/scripts/my_file.sql @my_stage/scripts/
    AUTO_COMPRESS=FALSE;
  

  Copy

• L’exécution de tous les fichiers d’un répertoire n’est pas possible. Par exemple, EXECUTE IMMEDIATE FROM @stage_name/scripts/ entraîne une erreur.

Notes sur l’utilisation de la modélisation¶

• Les noms de variable des modèles sont sensibles à la casse.

• Le nom de variable de modèle peut éventuellement être placé entre guillemets doubles. L’encadrement du nom de variable peut s’avérer utile si des mots-clés réservés sont utilisés comme noms de variable.

• Les types de paramètre suivants sont pris en charge dans la clause USING :

  • Chaîne. Doit être encadré de ' ou de $$. Par exemple, USING (a => 'a', b => $$b$$).

  • Nombre (décimal et entier). Par exemple, USING (a => 1, b => -1.23).

  • Booléen. Par exemple, USING (a => TRUE, b => FALSE).

  • NULL. Par exemple, USING (a => NULL).

    Note

    Le moteur de modélisation Jinja2 interprète une valeur NULL comme le type NoneType Python.

  • Variables de session. Par exemple, USING (a => $var). Seules les variables de session contenant des valeurs de types de données pris en charge sont autorisées.

  • Variables de liaison. Par exemple, USING (a => :var). Seules les variables de liaison contenant des valeurs de types de données pris en charge sont autorisées. Vous pouvez utiliser des variables de liaison pour transmettre des arguments de procédure stockée à un modèle.

• La taille de résultat maximale du rendu de modèle est de 100 000 octets.

• Les modèles sont rendus à l’aide du moteur de modélisation Jinja2 version 3.1.2.

Dépannage d’erreurs EXECUTE IMMEDIATE FROM¶

Cette section présente quelques erreurs courantes résultant d’une instruction EXECUTE IMMEDIATE FROM et explique comment les résoudre.

• Erreurs de fichier

• Erreurs de zone de préparation

• Erreurs de contrôle d’accès

• Erreurs de modélisation

001501 (02000): File '<directory_name>' not found in stage '<stage_name>'.

001503 (42601): Relative file references like '<filename.sql>' cannot be used in top-level EXECUTE IMMEDIATE calls.

001003 (42000): SQL compilation error: syntax error line <n> at position <m> unexpected '<string>'.

002003 (02000): SQL compilation error: Stage '<stage_name>' does not exist or not authorized.

003001 (42501): Uncaught exception of type 'STATEMENT_ERROR' in file <file_name> on line <n> at position <m>:
SQL access control error: Insufficient privileges to operate on schema '<schema_name>'

001003 (42000): SQL compilation error:
syntax error line [n] at position [m] unexpected '{'.

000005 (XX000): Python Interpreter Error:
jinja2.exceptions.UndefinedError: '<key>' is undefined
in template processing

001510 (42601): Unable to use value of template variable '<key>'

001518 (42601): Size of expanded template exceeds limit of 100,000 bytes.

Exemples¶