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

Wenn Sie SQL in einem EXECUTE IMMEDIATE-Befehl oder einem OPEN-Befehl für einen Cursor ausführen, können Sie mit der USING-Klausel Variablen binden.

Dieses Beispiel bindet Variablen in einem EXECUTE IMMEDIATE-Befehl mit einer USING-Klausel:

EXECUTE IMMEDIATE :query USING (minimum_price, maximum_price);
Copy

Das vollständige Beispiel, das diesen Code enthält, finden Sie unter Ausführen einer Anweisung, die Bindungsvariablen enthält.

Dieses Beispiel bindet Variablen in einem OPEN-Befehl für einen Cursor mit der USING-Klausel:

LET c1 CURSOR FOR SELECT id FROM invoices WHERE price > ? AND price < ?;
OPEN c1 USING (minimum_price, maximum_price);
Copy

Snowflake Scripting unterstützt auch die Nummerierung von Bindungsvariablen nach Position und die Wiederverwendung einer Bindungsvariable in einer SQL-Anweisung. Bei nummerierten Bindungsvariablen wird jeder Variablendeklaration ein Index zugewiesen, und Sie können mit :n auf die n-te deklarierte Variable verweisen. Der folgende Snowflake Scripting-Block gibt zum Beispiel die Bindungsvariable :1 für die Variable i und :2 für die Variable v an und verwendet die Bindungsvariable :1 in einer SQL-Anweisung erneut:

EXECUTE IMMEDIATE $$
DECLARE
  i INTEGER DEFAULT 1;
  v VARCHAR DEFAULT 'SnowFlake';
  r RESULTSET;
BEGIN
  CREATE OR REPLACE TABLE snowflake_scripting_bind_demo (id INTEGER, value VARCHAR);
  EXECUTE IMMEDIATE 'INSERT INTO snowflake_scripting_bind_demo (id, value)
    SELECT :1, (:2 || :1)' USING (i, v);
  r := (SELECT * FROM snowflake_scripting_bind_demo);
  RETURN TABLE(r);
END;
$$
;
Copy
+----+------------+
| ID | VALUE      |
|----+------------|
|  1 | SnowFlake1 |
+----+------------+

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 im Parameter STARTS WITH verwendet werden.

  • 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.