EXECUTE IMMEDIATE FROM

EXECUTE IMMEDIATE FROM exécute les instructions SQL spécifiées dans un fichier au cours d’une zone de préparation. Le fichier peut contenir des instructions SQL ou des blocs Snowflake Scripting. Les instructions doivent être syntaxiquement correctes en SQL.

Vous pouvez utiliser la commande EXECUTE IMMEDIATE FROM pour exécuter les instructions d’un fichier à partir de n’importe quelle session Snowflake.

Cette fonctionnalité fournit un mécanisme de contrôle du déploiement et de la gestion de vos objets et de votre code Snowflake. Par exemple, vous pouvez exécuter un script stocké pour créer un environnement Snowflake standard pour tous vos comptes. Le script de configuration peut inclure des instructions qui créent des utilisateurs, des rôles, des bases de données et des schémas pour chaque nouveau compte.

Voir aussi :

EXECUTE IMMEDIATE

Syntaxe

EXECUTE IMMEDIATE
  FROM { absoluteFilePath | relativeFilePath }
Copy

Où :

absoluteFilePath ::=
   @[ <namespace>. ]<stage_name>/<path>/<filename>
Copy
relativeFilePath ::=
  '[ { ./ | / | { ../ [ , ../, ... ] } } ]<path>/<filename>'
Copy

Chemin d’accès absolu au fichier (absoluteFilePath)

namespace

Base de données et/ou schéma dans lequel réside la zone de préparation interne ou externe, sous la forme database_name.schema_name ou schema_name. L’espace de noms est facultatif si une base de données et un schéma sont actuellement utilisés pour la session utilisateur ; sinon, il est obligatoire.

stage_name

Nom de la zone de préparation interne ou externe.

path

Chemin d’accès sensible à la casse vers le fichier dans la zone de préparation.

filename

Nom du fichier à exécuter. Il doit contenir des instructions SQL syntaxiquement correctes et valides. Chaque instruction doit être séparée par un point-virgule.

Chemin d’accès relatif au fichier (relativeFilePath)

path

Chemin d’accès sensible à la casse vers le fichier dans la zone de préparation. Les chemins d’accès relatifs s’appuient sur des conventions établies telles que l’utilisation d’un / pour indiquer la racine du système de fichiers d’une zone de préparation, d’un ./ pour faire référence au répertoire actuel (le répertoire dans lequel se trouve le fichier parent) et d’un ../ pour faire référence au répertoire parent. Pour plus d’informations, voir Notes sur l’utilisation.

filename

Nom du fichier à exécuter. Il doit contenir des instructions SQL syntaxiquement correctes et valides. Chaque instruction doit être séparée par un point-virgule.

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.

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 fichiers

Erreur

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

Cause

Les causes de cette erreur sont multiples :

  • Le fichier n’existe pas.

  • Le nom du fichier est la racine d’un répertoire. Par exemple, @stage_name/scripts/.

Solution

Vérifiez le nom du fichier et confirmez que le fichier existe. L’exécution de tous les fichiers d’un répertoire n’est pas possible.

Erreur

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

Cause

L’instruction a été exécutée en utilisant un chemin d’accès relatif en dehors de l’exécution d’un fichier.

Solution

Un chemin d’accès relatif ne peut être utilisé que dans les instructions EXECUTE IMMEDIATE FROM d’un fichier. Utilisez le chemin d’accès absolu pour le fichier. Pour plus d’informations, voir Notes sur l’utilisation.

Erreur

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

Cause

Le fichier contient des erreurs de syntaxe SQL.

Solution

Corrigez les erreurs de syntaxe dans le fichier et téléchargez à nouveau le fichier dans la zone de préparation.

Erreurs de zone de préparation

Erreur

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

Cause

La zone de préparation n’existe pas ou vous n’y avez pas accès.

Solution

  • Vérifiez le nom de la zone de préparation et confirmez son existence.

  • Exécutez l’instruction à l’aide d’un rôle disposant des privilèges requis pour accéder à la zone de préparation. Pour plus d’informations, voir Exigences en matière de contrôle d’accès.

Erreurs de contrôle d’accès

Erreur

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

Cause

Le rôle utilisé pour exécuter l’instruction ne dispose pas des privilèges requis pour exécuter certaines ou toutes les instructions du fichier.

Solution

Utilisez un rôle disposant des privilèges appropriés pour exécuter les instructions du fichier. Pour plus d’informations, voir Exigences en matière de contrôle d’accès.

Voir aussi : Erreurs de zone de préparation.

Exemples

Cet exemple exécute le fichier create-inventory.sql situé dans la zone de préparation my_stage.

  1. Créer un fichier nommé create-inventory.sql avec les instructions suivantes :

    CREATE OR REPLACE TABLE my_inventory(
      sku VARCHAR,
      price NUMBER
    );
    
    EXECUTE IMMEDIATE FROM './insert-inventory.sql';
    
    SELECT sku, price
      FROM my_inventory
      ORDER BY price DESC;
    
    Copy
  2. Créer un fichier nommé insert-inventory.sql avec les instructions suivantes :

    INSERT INTO my_inventory
      VALUES ('XYZ12345', 10.00),
             ('XYZ81974', 50.00),
             ('XYZ34985', 30.00),
             ('XYZ15324', 15.00);
    
    Copy
  3. Créer une zone de préparation interne my_stage :

    CREATE STAGE my_stage;
    
    Copy
  4. Télécharger les deux fichiers locaux sur la zone de préparation à l’aide de la commande PUT :

    PUT file://~/sql/scripts/create-inventory.sql @my_stage/scripts/
      AUTO_COMPRESS=FALSE;
    
    PUT file://~/sql/scripts/insert-inventory.sql @my_stage/scripts/
      AUTO_COMPRESS=FALSE;
    
    Copy
  5. Exécuter le script create-inventory.sql situé dans my_stage :

    EXECUTE IMMEDIATE FROM @my_stage/scripts/create-inventory.sql;
    
    Copy

    Renvoie :

    +----------+-------+
    | SKU      | PRICE |
    |----------+-------|
    | XYZ81974 |    50 |
    | XYZ34985 |    30 |
    | XYZ15324 |    15 |
    | XYZ12345 |    10 |
    +----------+-------+