EXECUTE IMMEDIATE FROM¶

Erstellen von Jinja2-Vorlagen¶

EXECUTE IMMEDIATE FROM kann auch eine Vorlagendatei mit der Jinja2-Vorlagensprache ausführen. Eine Vorlage kann Variablen und Ausdrücke enthalten, die die Verwendung von Schleifen, Bedingungen, Variablenersetzungen, Makros und mehr ermöglichen.

Weitere Informationen zur Vorlagensprache finden Sie in der Jinja2-Dokumentation.

Die auszuführende Vorlagendatei muss folgende Voraussetzungen erfüllen:

• Ist eine syntaktisch gültige Jinja2-Vorlage.

• Befindet sich in einem Stagingbereich oder Git-Repository.

• Ist in der Lage, syntaktisch gültige SQL-Anweisungen zu rendern.

Die Verwendung von Vorlagen ermöglicht flexiblere Kontrollstrukturen und ermöglicht die Parametrisierung mithilfe von Umgebungsvariablen. Sie können zum Beispiel eine Vorlage verwenden, um das Bereitstellungsziel der im Skript definierten Objekte dynamisch auszuwählen. Um eine Vorlage zum Rendern eines SQL-Skripts zu verwenden, verwenden Sie die Vorlagenrichtlinie oder fügen Sie eine USING-Klausel mit mindestens einer Vorlagenvariablen hinzu.

--!jinja

#!jinja

Syntax¶

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

Wobei:

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

Copy

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

Copy

Erforderliche Parameter¶

Optionale Parameter¶

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

Vorschau-Feature – Offen

Verfügbar bei allen Konten.

Ermöglicht Ihnen die Übergabe eines oder mehrerer Schlüssel-Wert-Paare, die zur Parametrisierung der Vorlagenerweiterung verwendet werden können. Die Schlüssel-Wert-Paare müssen eine durch Komma getrennte Liste bilden.

Wenn die USING-Klausel vorhanden ist, wird die Datei zunächst als Jinja2-Vorlage gerendert, bevor sie als SQL-Skript ausgeführt wird.

Wobei:

• key ist der Name der Vorlagenvariable. Der Name der Vorlagenvariable kann optional in doppelte Anführungszeichen (") eingeschlossen werden.

• value ist der Wert, der der Variablen in der Vorlage zugewiesen werden soll. Zeichenfolgenwert müssen in ' oder $$ eingeschlossen sein. Ein Beispiel finden Sie unter Nutzungshinweise zu Vorlagen.

Rückgabewerte¶

EXECUTE IMMEDIATE FROM Rückgabewerte:

• Das Ergebnis der letzten Anweisung in der Datei, wenn alle Anweisungen erfolgreich ausgeführt wurden.

• Die Fehlermeldung, wenn eine Anweisung in der Datei fehlgeschlagen ist.

  Wenn in einer Anweisung in der Datei ein Fehler auftritt, schlägt der Befehl EXECUTE IMMEDIATE FROM fehl und gibt die Fehlermeldung der fehlgeschlagenen Anweisung zurück.

  Bemerkung

  Wenn der Befehl EXECUTE IMMEDIATE FROM fehlschlägt und eine Fehlermeldung zurückgibt, sind alle Anweisungen in der Datei vor der fehlgeschlagenen Anweisung erfolgreich abgeschlossen worden.

Anforderungen an die Zugriffssteuerung¶

• Die Rolle, die zur Ausführung des Befehls EXECUTE IMMEDIATE FROM verwendet wird, muss über die Berechtigung USAGE (externer Stagingbereich) oder READ (interner Stagingbereich) für den Stagingbereich verfügen, in dem sich die Datei befindet.

• Die Rolle, mit der die Datei ausgeführt wird, kann nur die Anweisungen in der Datei ausführen, für die sie Berechtigungen hat. Wenn beispielsweise eine CREATE TABLE-Anweisung in der Datei enthalten ist, muss die Rolle über die notwendigen Berechtigungen verfügen, um eine Tabelle im Konto zu erstellen, sonst schlägt die Anweisung fehl.

Beachten Sie, dass für die Bearbeitung eines Objekts in einem Schema auch die Berechtigung USAGE für die übergeordnete Datenbank und das Schema erforderlich ist.

Eine Anleitung zum Erstellen einer kundenspezifischen Rolle mit einer bestimmten Gruppe von Berechtigungen finden Sie unter Erstellen von kundenspezifischen Rollen.

Allgemeine Informationen zu Rollen und Berechtigungen zur Durchführung von SQL-Aktionen auf sicherungsfähigen Objekten finden Sie unter Übersicht zur Zugriffssteuerung.

Nutzungshinweise¶

• Die SQL-Anweisungen in einer auszuführenden Datei können EXECUTE IMMEDIATE FROM-Anweisungen enthalten:

  • Verschachtelte EXECUTE IMMEDIATE FROM-Anweisungen können relative Dateipfade verwenden.

    Relative Pfade werden in Bezug auf den Stagingbereich und den Dateipfad der übergeordneten Datei ausgewertet. Wenn der relative Dateipfad mit / beginnt, beginnt der Pfad im Stammverzeichnis des Stagingbereichs, der die übergeordnete Datei enthält.

    Ein Beispiel dazu finden Sie unter Beispiele.

  • Relative Dateipfade müssen in einfache Anführungszeichen (') oder $$ gesetzt wird.

  • Die maximale Ausführungstiefe für verschachtelte Dateien ist 5.

• Absolute Dateipfade können optional in einfache Anführungszeichen (') oder $$ gesetzt werden.

• Die auszuführende Datei darf nicht größer als 10MB sein.

• Die auszuführende Datei muss in UTF-8 kodiert sein.

• Die auszuführende Datei muss unkomprimiert sein. Wenn Sie den Befehl PUT verwenden, um eine Datei in einen internen Stagingbereich hochzuladen, müssen Sie den Parameter AUTO_COMPRESS explizit auf FALSE setzen.

  Laden Sie zum Beispiel my_file.sql nach my_stage hoch:

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

  Copy

• Das Ausführen aller Dateien in einem Verzeichnis wird nicht unterstützt. Zum Beispiel führt EXECUTE IMMEDIATE FROM @stage_name/scripts/ zu einem Fehler.

Nutzungshinweise zu Vorlagen¶

• Bei Variablennamen in Vorlagen wird zwischen Groß- und Kleinschreibung unterschieden.

• Der Name der Vorlagenvariable kann optional in doppelte Anführungszeichen gesetzt werden. Das Einschließen des Variablennamens kann nützlich sein, wenn irgendwelche reservierten Schlüsselwörter als Variablennamen verwendet werden.

• Die folgenden Parametertypen werden in der USING-Klausel unterstützt:

  • Zeichenfolge. Muss von ' oder $$ umschlossen sein. Beispiel: USING (a => 'a', b => $$b$$).

  • Zahl (dezimal und ganzzahlig). Beispiel: USING (a => 1, b => -1.23).

  • Boolescher Wert. Beispiel: USING (a => TRUE, b => FALSE).

  • NULL. Beispiel: USING (a => NULL).

    Bemerkung

    Die Jinja2-Vorlagen-Engine interpretiert einen NULL-Wert als Python-Typ NoneType.

  • Sitzungsvariablen. Beispiel: USING (a => $var). Es sind nur Sitzungsvariablen erlaubt, die Werte von unterstützten Datentypen enthalten.

  • Bindungsvariablen. Beispiel: USING (a => :var). Nur Bindungsvariablen, die Werte von unterstützten Datentypen enthalten, sind erlaubt. Sie können Bindungsvariablen verwenden, um Argumente für gespeicherte Prozeduren an eine Vorlage zu übergeben.

• Die maximale Ergebnisgröße für die Wiedergabe von Vorlagen beträgt 100.000 Bytes.

• Vorlagen werden mit der Jinja2 Version 3.1.2-Vorlagen-Engine gerendert.

Problembehandlung bei EXECUTE IMMEDIATE FROM-Fehlern¶

Dieser Abschnitt enthält einige häufige Fehler, die sich aus einer EXECUTE IMMEDIATE FROM-Anweisung ergeben, und wie Sie diese beheben können.

• Dateifehler

• Stagingbereichsfehler

• Zugriffssteuerungsfehler

• Fehler bei der Verwendung von Vorlagen

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.

Beispiele¶