Bindungsvariablen

Anwendungen können Daten von Benutzern annehmen und diese Daten in SQL-Anweisungen verwenden. So kann eine Anwendung den Benutzer beispielsweise auffordern, Kontaktinformationen wie Adresse und Telefonnummer einzugeben.

Um diese Benutzereingabe in einer SQL-Anweisung anzugeben, können Sie programmgesteuert eine Zeichenfolge für die SQL-Anweisung konstruieren, indem Sie die Benutzereingabe mit den anderen Teilen der Anweisung verketten. Alternativ können Sie auch Bindungsvariablen verwenden. Wenn Sie Bindungsvariablen verwenden, fügen Sie einen oder mehrere Platzhalter in den Text der SQL-Anweisung ein, und dann geben Sie für jeden Platzhalter die Variable (den zu verwendenden Wert) an.

Überblick über die Bindungsvariablen

Mit Bindungsvariablen ersetzen Sie in SQL-Anweisungen Literale durch Platzhalter. Die folgende SQL-Anweisung verwendet beispielsweise Literale für die eingefügten Werte:

INSERT INTO t (c1, c2) VALUES (1, 'Test string');
Copy

Die folgende SQL-Anweisung verwendet Platzhalter für die eingefügten Werte:

INSERT INTO t (c1, c2) VALUES (?, ?);
Copy

Ihr Anwendungscode bindet mit jedem Platzhalter Daten in der SQL-Anweisung. Die jeweilige Technik zum Binden von Daten mit Platzhaltern hängt von der Programmiersprache ab. Auch die Syntax des Platzhalters variiert je nach Programmiersprache. Es ist entweder ?, :varname oder %varname.

Bindungsvariablen in gespeicherten Prozeduren in JavaScript verwenden

Sie können JavaScript verwenden, um gespeicherte Prozeduren zu erstellen, die SQL ausführen.

Um Bindungsvariablen in JavaScript anzugeben, verwenden Sie ? Platzhalter. Die folgende INSERT-Anweisung gibt zum Beispiel Bindungsvariablen für die in eine Tabellenzeile eingefügten Werte an:

INSERT INTO t (col1, col2) VALUES (?, ?)
Copy

In JavaScript können Sie Bindungsvariablen für die Werte in den meisten SQL-Anweisungen verwenden. Informationen über Einschränkungen finden Sie unter Einschränkungen für Bindungsvariablen.

Weitere Informationen zur Verwendung von Bindungsvariablen in JavaScript finden Sie unter Binden von Variablen.

Verwenden von Bindungsvariablen mit Snowflake Scripting

Sie können Snowflake Scripting verwenden, um prozeduralen Code zu erstellen, der SQL ausführt, wie Codeblöcke und gespeicherte Prozeduren. Um Bindungsvariablen in Snowflake Scripting-Code anzugeben, stellen Sie dem Variablennamen einen Doppelpunkt voran. Die folgende INSERT-Anweisung gibt zum Beispiel eine Bindungsvariable mit dem Namen variable1 an:

INSERT INTO t (c1) VALUES (:variable1)
Copy

In Snowflake Scripting Code können Sie Bindungsvariablen für die Werte in den meisten SQL-Anweisungen verwenden. Informationen über Einschränkungen finden Sie unter Einschränkungen für Bindungsvariablen.

Weitere Informationen zur Verwendung von Bindungsvariablen in Snowflake Scripting finden Sie unter Verwenden einer Variablen in einer SQL-Anweisung (Bindung) und Verwenden eines Arguments in einer SQL-Anweisung (Bindung).

Verwenden von Bindungsvariablen mit der SQL-API

Sie können die Snowflake-SQL-API verwenden, um auf Daten in einer Snowflake-Datenbank zuzugreifen und diese Daten zu aktualisieren. Sie können Anwendungen erstellen, die die SQL-API verwenden, um SQL-Anweisungen zu übermitteln und Bereitstellungen zu verwalten.

Wenn Sie eine Anforderung übermitteln, die eine SQL-Anweisung ausführt, können Sie für Werte in der Anweisung Bindungsvariablen verwenden. Weitere Informationen dazu finden Sie unter Verwenden von Bindungsvariablen in einer Anweisung.

Verwenden von Bindungsvariablen mit Treibern

Mit Snowflake-Treibern können Sie Anwendungen schreiben, die Operationen in Snowflake ausführen. Die Treiber unterstützen Programmiersprachen wie Go, Java und Python. Weitere Informationen zur Verwendung von Bindungsvariablen in einer Anwendung für einen bestimmten Treiber finden Sie unter dem Link des jeweiligen Treibers:

Bemerkung

Der PHP-Treiber bietet keine Unterstützung von Bindungsvariablen.

Verwenden von Bindungsvariablen mit Arrays von Werten

Sie können ein Array von Werten an Variablen in SQL-Anweisungen binden. Mit dieser Technik können Sie die Performance verbessern, indem Sie mehrere Zeilen in einen einzigen Batch einfügen, wodurch Netzwerk-Roundtrips und Kompilierungen vermieden werden. Die Verwendung einer Array-Bindung wird auch als „Masseneinfügen“ (Bulk Insert) oder „Batcheinfügung“ (Batch Insert) bezeichnet.

Bemerkung

Snowflake unterstützt noch weitere Methoden zum Laden von Daten, die anstelle der Verwendung von Array-Bindungen empfohlen werden. Weitere Informationen dazu finden Sie unter Daten in Snowflake laden und Befehle zum Laden und Entladen von Daten.

Im Folgenden finden Sie ein Beispiel für eine Array-Bindung in Python-Code:

conn = snowflake.connector.connect( ... )
rows_to_insert = [('milk', 2), ('apple', 3), ('egg', 2)]
conn.cursor().executemany(
            "insert into grocery (item, quantity) values (?, ?)",
            rows_to_insert)
Copy

Im diesem Beispiel wird die folgende Bindungsliste angegeben: [('milk', 2), ('apple', 3), ('egg', 2)]. Die Art und Weise, wie eine Anwendung eine Bindungsliste angibt, hängt von der Programmiersprache ab.

Dieser Code fügt drei Zeilen in die Tabelle ein:

+-------+----+
| C1    | C2 |
|-------+----|
| milk  |  2 |
| apple |  3 |
| egg   |  2 |
+-------+----+

Weitere Informationen zur Verwendung von Array-Bindungen in einer Anwendung für einen bestimmten Treiber finden Sie unter dem Link des jeweiligen Treibers:

Bemerkung

Der PHP-Treiber bietet keine Unterstützung von Array-Bindungen.

Einschränkungen bei der Verwendung von Array-Bindungen

Die folgenden Einschränkungen gelten für Array-Bindungen:

  • Array-Bindungsvariablen können nur in INSERT INTO … VALUES-Anweisungen enthalten sein.

  • Die VALUES-Klausel muss eine einzeilige Liste von Bindungsvariablen sein. Die folgende VALUES-Klausel wird beispielsweise nicht unterstützt:

    VALUES (?,?), (?,?)
    
    Copy

Einfügen mehrerer Zeilen ohne Verwendung von Array-Bindungen

Eine INSERT-Anweisung kann Bindungsvariablen verwenden, um mehrere Zeilen einzufügen, ohne eine Array-Bindung zu verwenden. Im folgenden Beispiel werden Werte in zwei Zeilen eingegeben, wobei aber keine Array-Bindung verwendet wird.

INSERT INTO t VALUES (?,?), (?,?);
Copy

Ihre Anwendung kann zum Beispiel eine Bindungsliste angeben, die in der Reihenfolge der Platzhalter den folgenden Werten entspricht: [1,'String1',2,'String2']. Da die VALUES-Klausel mehr als eine Zeile angibt, fügt die Anweisung nur die genaue Anzahl der Werte ein (im Beispiel vier) und nicht eine dynamische Anzahl von Zeilen.

Verwenden von Bindungsvariablen mit semistrukturierten Daten

Um Variablen mit semistrukturierten Daten zu binden, binden Sie die Variable als Zeichenfolgetyp (String) und verwenden Funktionen wie PARSE_JSON oder ARRAY_CONSTRUCT.

Im folgenden Beispiel wird eine Tabelle mit einer VARIANT-Spalte erstellt und dann die Funktion PARSE_JSON aufgerufen, um semistrukturierte Daten mit einer Bindungsvariablen in die Tabelle einzufügen:

CREATE TABLE t (a VARIANT);
-- Code that supplies a bind value for ? of '{'a': 'abc', 'x': 'xyz'}'
INSERT INTO t SELECT PARSE_JSON(a) FROM VALUES (?);
Copy

Im folgenden Beispiel wird die Tabelle abgefragt:

SELECT * FROM t;
Copy

Die Abfrage gibt die folgende Ausgabe zurück:

+---------------+
| A             |
|---------------|
| {             |
|   "a": "abc", |
|   "x": "xyz"  |
| }             |
+---------------+

Die folgende Anweisung ruft die Funktion ARRAY_CONSTRUCT auf, um ein Array von semistrukturierten Daten mittels einer Bindungsvariablen in eine VARIANT-Spalte einzufügen:

INSERT INTO t SELECT ARRAY_CONSTRUCT(column1) FROM VALUES (?);
Copy

In beiden Beispiele kann eine einzelne Zeile eingefügt werden, oder es kann eine Array-Bindung verwendet werden, um mehrere Zeilen im Batch einzufügen. Sie können diese Technik verwenden, um jede Art von semistrukturierten Daten einzufügen, die in einer VARIANT-Spalte gültig ist.

Einschränkungen für Bindungsvariablen

Die folgenden Einschränkungen gelten für Bindungsvariablen:

  • Einschränkungen für SELECT-Anweisungen:

    • Bindungsvariablen können keine Zahlen ersetzen, die Teil einer Datentypdefinition (z. B. NUMBER(?)) oder Sortierungsspezifikation (z. B. COLLATE ?) sind.

    • Bindungsvariablen können nicht für die Quelle in einer SELECT-Anweisung verwendet werden, die Dateien in einem Stagingbereich abfragt.

  • Einschränkungen für DDL-Befehle:

    • Bindungsvariablen können in den folgenden DDL-Befehlen nicht verwendet werden:

      • CREATE/ALTER INTEGRATION

      • CREATE/ALTER REPLICATION GROUP

      • CREATE/ALTER PIPE

      • CREATE TABLE … USING TEMPLATE

    • Bindungsvariablen können in den folgenden Klauseln nicht verwendet werden:

      • ALTER COLUMN

      • COMMENT ON CONSTRAINT

    • In CREATE/ALTER-Befehlen können Bindungsvariablen nicht für die Werte der folgenden Parameter verwendet werden:

      • CREDENTIALS

      • DIRECTORY

      • ENCRYPTION

      • IMPORTS

      • PACKAGES

      • REFRESH

      • TAG

      • Parameter, die spezifisch für externe Tabellen sind

    • Bindungsvariablen können nicht für Eigenschaften verwendet werden, die Teil eines FILE FORMAT-Wertes sind.

  • In COPY INTO-Befehlen können Bindungsvariablen nicht für die Werte der folgenden Parameter verwendet werden:

    • CREDENTIALS

    • ENCRYPTION

    • FILE_FORMAT

  • In SHOW-Befehlen können Bindungsvariablen nicht in den folgenden Parametern verwendet werden:

    • LIKE

    • LIMIT

    • STARTS WITH

  • Bindungsvariablen können nicht in einem EXECUTE IMMEDIATE FROM-Befehl verwendet werden.

  • Die Werte von Bindungsvariablen können nicht automatisch von einem Datentyp in einen anderen konvertiert werden, wenn Bindungsvariablen verwendet werden in:

    • Snowflake Scripting-Code, der den Datentyp explizit angibt

    • DDL-Anweisungen

    • Namen von Stagingbereichen

Sicherheitserwägungen für Bindungsvariablen

Bindungsvariablen maskieren nicht in allen Fällen sensible Daten. Die Werte von Bindungsvariablen können zum Beispiel in Fehlermeldungen und anderen Artefakten erscheinen.

Bindungsvariablen können helfen, Angriffe durch Einschleusen von SQL-Befehlen zu verhindern, wenn Sie SQL-Anweisungen anhand von Benutzereingaben konstruieren. Bindungsvariablen können jedoch potenzielle Sicherheitsrisiken darstellen. Wenn Eingaben für SQL-Anweisungen aus externen Quellen stammen, stellen Sie sicher, dass diese validiert sind. Weitere Informationen dazu finden Sie unter Einschleusung von SQL-Befehlen.