Ausführen von SQL-Anweisungen

Mit Snowflake CLI können Sie SQL-Abfragen, Ad-hoc-Abfragen oder Dateien, die SQL-Abfragen enthalten, ausführen, indem Sie den Befehl snow sql verwenden.

Um eine Ad-hoc-Abfrage auszuführen, führen Sie einen Befehl ähnlich dem folgenden aus:

snow sql -q "SELECT * FROM FOO"
Copy

Um eine Datei mit einer SQL-Abfrage auszuführen, führen Sie einen Befehl ähnlich dem folgenden aus:

snow sql -f my_query.sql
Copy

Der snow sql-Befehl kann mehrere Anweisungen ausführen. In diesem Fall werden mehrere Resultsets zurückgegeben. Wenn Sie beispielsweise Folgendes ausführen:

snow sql  -q "select 'a', 'b'; select 'c', 'd';"
Copy

Dann führt dies zu folgender Ausgabe:

select 'a', 'b';
+-----------+
| 'A' | 'B' |
|-----+-----|
| a   | b   |
+-----------+

select 'c', 'd';
+-----------+
| 'C' | 'D' |
|-----+-----|
| c   | d   |
+-----------+

Sie können auch Skriptblöcke in Snowflake CLI ausführen, mit einer Einschränkung bezüglich des Begrenzungszeichens $$.

Beispiel:

EXECUTE IMMEDIATE $$
-- Snowflake Scripting code
DECLARE
  radius_of_circle FLOAT;
  area_of_circle FLOAT;
BEGIN
  radius_of_circle := 3;
  area_of_circle := pi() * radius_of_circle * radius_of_circle;
  RETURN area_of_circle;
END;
$$
;
Copy

Einige Betriebssysteme interpretieren $$, wie z. B. eine Prozess-ID (PID), anstatt es als Begrenzungszeichen für einen Skriptblock zu erkennen. Um diese Beschränkung zu umgehen, können Sie die folgenden Alternativen verwenden:

  • Wenn Sie den Skriptblock dennoch in der Befehlszeile angeben möchten, können Sie die $$-Begrenzungszeichen maskieren, wie in \$\$.

  • Sie können den Skriptblock auch mit den standardmäßigen $$-Begrenzungszeichen in eine separate Datei schreiben und mit dem Befehl snow sql -f <filename> aufrufen.

Weitere Informationen dazu finden Sie unter dem Befehl snow sql.

Verwenden von Variablen für SQL-Vorlagen

In bestimmten Situationen möchten Sie Ihre SQL-Abfragen vielleicht kontextabhängig ändern. Der snow sql-Befehl unterstützt die clientseitige Variablensubstitution, mit der Sie im Befehl Variablen verwenden können, die vor der Übermittlung der Abfrage lokal aufgelöst werde. Variablen in der SQL-Zeichenfolge haben die Form <% variable_name %>, und die Option -D (oder --variable) gibt den Wert der Variable an.

Bemerkung

Sie können derzeit die Syntax SnowSQL &variable_name und <% variable_name %> für Vorlagen verwenden. Snowflake empfiehlt jedoch die Verwendung der <% variable_name %>-Syntax.

Um beispielsweise eine Datenbank über eine clientseitige Variable anzugeben, können Sie einen Befehl ähnlich dem folgenden eingeben:

snow sql -q "select * from <% database %>.logs" -D "database=dev"
Copy

Bei der Ausführung ersetzt der Befehl den Wert dev in der Variable <% database %>, um den Dateinamen dev.logs zu erstellen und sendet dann die select * from dev.logs SQL-Abfrage zur Verarbeitung an Snowflake.

Sie können auch mehrere variable Eingaben wie folgt festlegen:

snow sql \
-q "grant usage on database <% database %> to <% role %>" \
-D "database=dev" \
-D "role=eng_rl"
Copy

Dieses Beispiel generiert die folgende SQL-Abfrage:

grant usage on database dev to eng_rl
Copy

Speichern von Variablen in der snowflake.yml-Projektdefinitionsdatei

Die Angabe von Variablen als snow sql-Befehlszeilenoptionen ist vielleicht nicht immer praktisch, oder Sie möchten vielleicht keine sensiblen Werte in der Befehlszeile angeben. In solchen Fällen können Sie Variablen und Werte in der Projektdefinitionsdatei snowflake.yml definieren. Dann können Sie die Variablennamen einfach im Format <% ctx.env.<variable_name> %> angeben, anstatt die Option -D "<variable> = <value>" zu verwenden.

Anhand des Beispiels aus dem vorigen Abschnitt könnten Sie die Datenbank- und Rollenvariablen in der Datei snowflake.yml speichern und die Abfrage wie folgt ändern:

snow sql -q "grant usage on database <% ctx.env.database %> to <% ctx.env.role %>"
Copy

In diesem Beispiel sucht der snow sql-Befehl nach den Variablendefinitionen in der Projektdefinitionsdatei und extrahiert die Werte, ohne sie in der Befehlszeile sichtbar zu machen. Die snowflake.yml-Datei sollte sich entweder im aktuellen Verzeichnis oder an dem mit der -p-Option angegebenen Speicherort befinden.

Weitere Informationen zum Speichern dieser Werte in der Projektdefinitionsdatei finden Sie unter Variablen in SQL verwenden.

Asynchrone Ausführung von SQL-Abfragen

Snowflake CLI lässt Sie eine oder mehrere SQL-Abfragen asynchron ausführen. Anstatt auf ein Ergebnis zu warten, plant der Befehl snow sql die Abfragen bei Snowflake und liefert eine Abfrage-ID. Nachdem eine Abfrage beendet ist, können Sie das Ergebnis mit dem Abfragebefehl !result oder dem SQL-Befehl RESULT_SCAN abrufen.

Um eine SQL-Abfrage asynchron auszuführen, beenden Sie die Abfrage mit ;> anstelle von ;, wie gezeigt:

snow sql -q 'select "My async query" ;>'
Copy

Das folgende Beispiel führt eine einzelne Abfrage asynchron aus:

snow sql -q "select 'This is async query';>"
Copy
select 'This is async query'
+--------------------------------------+
| scheduled query ID                   |
|--------------------------------------|
| 01bc3011-080f-f2d7-0001-c1be14bae7c2 |
+--------------------------------------+

Sie können dann die zurückgegebene Abfrage-ID in dem Abfragebefehl !result verwenden, um das Abfrageergebnis anzuzeigen:

snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'
Copy
path-to-private-key-file
+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query   |
+-----------------------+

Sie können auch mehrere Abfragen in der Abfragezeichenfolge ausführen, sowohl asynchron als auch synchron, wie gezeigt:

snow sql -q "select 'This is async query';> select 'Not an async query'; select 'Another async query';>"
Copy
select 'This is async query'
+--------------------------------------+
| scheduled query ID                   |
|--------------------------------------|
| 01bc3b8c-0109-2e81-0000-0f2d0e5a4a32 |
+--------------------------------------+

select 'Not an async query';
+----------------------+
| 'NOT AN ASYNC QUERY' |
|----------------------|
| Not an async query   |
+----------------------+

select 'Another async query'
+--------------------------------------+
| scheduled query ID                   |
|--------------------------------------|
| 01bc3b8c-0109-2e81-0000-0f2d0e5a4a36 |
+--------------------------------------+

Arbeiten mit SQL-Abfragebefehlen

Snowflake CLI stellt die folgenden Befehle zur Verfügung, die Sie innerhalb Ihrer SQL-Abfragen verwenden können:

  • !source, der SQL in lokalen Dateien oder URLs ausführt.

  • !queries, der alle SQL-Abfragen auflistet.

  • !result, der das Ergebnis einer SQL-Abfrage anzeigt.

  • !abort, der eine aktive SQL-Abfrage abbricht.

Tipp

Wenn Sie Ihre SQL-Abfrage in doppelte Anführungszeichen ("") statt in einfache Anführungszeichen ('') einschließen, müssen Sie das Ausrufezeichen möglicherweise maskieren (!), je nachdem, welche Shell Sie verwenden.

Führen Sie SQL in lokalen Dateien oder URLs aus

Sie können den Abfragebefehl !source in Ihrer SQL-Abfrage verwenden, um SQL in lokalen Dateien oder einer URL-basierten Datei auszuführen. Der folgende Befehl führt zum Beispiel alle SQL-Befehle in einer lokalen Datei namens my_sql_code.sql aus:

snow sql -q '!source my_sql_code.sql'
Copy

Sie können auch !source-Befehle in den SQL-Dateien verschachteln, wie z. B.:

select emp_id FROM employees;
!source code_file_2.sql
Copy

In diesem Beispiel führt der Befehl die SELECT-Abfrage aus und führt dann die SQL-Befehle in der Datei code_file_2.sql aus. Bevor Sie die !source-Abfragen ausführen, führt Snowflake CLI Folgendes aus:

  • Evaluiert Variablenersetzungen und Vorlagen.

  • Liest den Inhalt aller verschachtelten Dateien, um sicherzustellen, dass keine Rekursion stattfindet.

Wenn die Variablen und Vorlagen aufgelöst werden und keine Rekursion festgestellt wird, sendet der Befehl den Code zur Ausführung an Snowflake.

Bemerkung

Wenn Sie doppelte Anführungszeichen ("") anstelle von einfachen Anführungszeichen ('') um eine !source-Abfrage verwenden, müssen Sie je nachdem, welche Shell Sie verwenden, möglicherweise das ! maskieren (\!).

Die folgenden Beispiele veranschaulichen verschiedene Möglichkeiten, wie Sie Quelldateien ausführen können.

  • Ausführen von Code in einer lokalen Datei.

    Dieses Beispiel geht davon aus, dass Sie eine einfache Abfrage in einer lokalen SQL-Datei haben.

    cat code_to_execute.sql
    
    Copy
    select 73;
    

    Um den Code in der Datei auszuführen, geben Sie den folgenden Befehl ein:

    snow sql -q '!source code_to_execute.sql'
    
    Copy
    select 73;
    +----+
    | 73 |
    |----|
    | 73 |
    +----+
    
  • Ausführen von Code in einer URL-basierten Datei.

    In diesem Beispiel wird davon ausgegangen, dass Sie die gleiche einfache Abfrage in einer SQL-Datei unter einer URL haben.

    Um den Code in der Datei auszuführen, geben Sie den folgenden Befehl ein:

    snow sql -q '!source https://trusted-host/trusted-content.sql'
    
    Copy
    select 73;
    +----+
    | 73 |
    |----|
    | 73 |
    +----+
    
  • Ausführen von Code, der Variablensubstitution und Templating verwendet.

    Dieses Beispiel geht davon aus, dass Sie eine Abfrage in einer lokalen SQL-Datei haben, die eine Vorlagenvariable verwendet.

    cat code_with_variable.sql
    
    Copy
    select '<% ctx.env.Message %>';
    

    Um den Code in der Datei auszuführen, geben Sie den folgenden Befehl ein, der den Variablenwert definiert:

    snow sql -q '!source code_&value.sql;' -D value=with_variable --env Message='Welcome !'
    
    Copy
    select 'Welcome !';
    +-------------+
    | 'WELCOME !' |
    |-------------|
    | Welcome !   |
    +-------------+
    

Bemerkung

Der Befehl !source unterstützt den alten Alias !load.

Alle SQL-Abfragen auflisten

Der !queries-Abfragebefehl listet alle Abfragen für ein Konto auf. Standardmäßig listet der Befehl die 25 letzten Abfragen auf, die in der aktuellen Sitzung ausgeführt wurden.

Der folgende !queries-Abfragebefehl gibt zum Beispiel die drei letzten Abfragen für einen bestimmten Benutzer zurück:

snow sql -q '!queries user=user1 amount=3'
Copy
+-------------------------------------------------------------------------------------------------------------------------------------+
| QUERY ID                             | SQL TEXT                                                           | STATUS    | DURATION_MS |
|--------------------------------------+--------------------------------------------------------------------+-----------+-------------|
| 01bc3040-080f-f4f9-0001-c1be14bb603a | select current_version();                                          | SUCCEEDED | 3858        |
| 01bc303d-080f-f4e9-0001-c1be14bb1812 | SELECT SYSTEM$CANCEL_QUERY('01bc3011-080f-f2d7-0001-c1be14bae7c2') | SUCCEEDED | 564         |
| 01bc3011-080f-f2d7-0001-c1be14bae7c2 | select 'This is async query'                                       | SUCCEEDED | 931         |
+-------------------------------------------------------------------------------------------------------------------------------------+

Sie können die folgenden Filter verwenden, um die Liste der zurückgegebenen Abfragen einzuschränken:

Filter

Standard

Beschreibung

amount (integer)

25

Anzahl der letzten Abfragen, die zurückgegeben werden sollen (Standard: 25).

session (boolean)

N/A

Falls angegeben, werden nur Abfragen zurückgegeben, die in der aktuellen Sitzung ausgeführt wurden.

warehouse (string)

Keine

Gibt Abfragen zurück, die nur für das angegebene Warehouse ausgeführt wurden.

user (string)

Keine

Gibt Abfragen zurück, die nur von dem angegebenen Benutzer ausgeführt wurden.

duration (Millisekunden)

0

Gibt nur Abfragen zurück, die mindestens die angegebene Anzahl von Millisekunden benötigt haben.

start_date (string)

Keine

Gibt nur Abfragen zurück, die nach dem angegebenen Datum ausgeführt wurden. Es wird erwartet, dass das Datum im ISO-Format angegeben wird (zum Beispiel 2025-01-01T09:00:00)

end_date (string)

Keine

Gibt nur Abfragen zurück, die vor dem angegebenen Datum ausgeführt wurden. Es wird erwartet, dass das Datum im ISO-Format angegeben wird (zum Beispiel 2025-01-01T09:00:00)

start (integer)

Keine

Gibt nur Abfragen zurück, die nach dem angegebenen Unix-Zeitstempel (in Millisekunden) ausgeführt wurden.

end (integer)

Keine

Gibt nur Abfragen zurück, die vor dem angegebenen Unix-Zeitstempel (in Millisekunden) ausgeführt wurden.

status (enum)

Keine

Gibt nur Abfragen mit einem der folgenden Status zurück:

  • RUNNING

  • SUCCEEDED

  • FAILED

  • BLOCKED

  • QUEUED

  • ABORTED

type

Keine

Gibt nur Abfragen von einem der folgenden Typen zurück:

  • SELECT

  • INSERT

  • UPDATE

  • DELETE

  • MERGE

  • MULTI_TABLE_INSERT

  • COPY

  • COMMIT

  • ROLLBACK

  • BEGIN_TRANSACTION

  • SHOW

  • GRANT

  • CREATE

  • ALTER

Die folgenden Beispiele liefern Abfragen mit verschiedenen Filtern:

  • Gibt die 25 letzten Abfragen zurück, die in der aktuellen Sitzung ausgeführt wurden:

    snow sql -q 'select 42; select 15; !queries session'
    
    Copy
  • Gibt die 20 letzten Abfragen zurück, die auf dem Konto ausgeführt wurden:

    snow sql -q '!queries amount=20'
    
    Copy
  • Liefert die 20 zuletzt auf dem Konto ausgeführten Abfragen, deren Ausführung länger als 200 Millisekunden dauerte:

    snow sql -q '!queries amount=20 duration=200'
    
    Copy
  • Gibt die 25 letzten Abfragen zurück, die im angegebenen Warehouse ausgeführt wurden:

    snow sql -q '!queries warehouse=mywh'
    
    Copy

Gibt ein vollständiges SQL-Abfrageergebnis zurück

Der Abfragebefehl !result gibt das Ergebnis einer abgeschlossenen Abfrage zurück, wenn die Abfrage-ID angegeben wird. Sie können die Abfrage-ID auf folgende Weise erhalten:

  • Sehen Sie sich die Seite Abfrageverlauf in Snowsight an.

  • Führen Sie den SQL-Abfragebefehl !queries aus.

  • Verwenden Sie die ID, die von einer asynchronen Abfrage zurückgegeben wird.

snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'
Copy
+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query   |
+-----------------------+

Abbrechen einer aktiven SQL-Abfrage

Der Abfragebefehl !abort bricht eine aktive Abfrage ab, wenn die Abfrage-ID angegeben wird. Sie können die Abfrage-ID auf folgende Weise erhalten:

  • Sehen Sie sich die Seite Abfrageverlauf in Snowsight an.

  • Führen Sie den SQL-Abfragebefehl !queries aus.

  • Verwenden Sie die ID, die von einer asynchronen Abfrage zurückgegeben wird.

snow sql -q '!abort 01bc3011-080f-f2d7-0001-c1be14bae7c2'
Copy
+-------------------------------------------------------------+
| SYSTEM$CANCEL_QUERY('01BC3011-080F-F2D7-0001-C1BE14BAE7C2') |
|-------------------------------------------------------------|
| Identified SQL statement is not currently executing.        |
+-------------------------------------------------------------+

Eingeben mehrerer Befehle in einer einzigen Transaktion

Mit der Option --single-transaction können Sie mehrere SQL-Befehle eingeben, die als Alles-oder-Nichts-Satz von Befehlen ausgeführt werden. Indem Sie Befehle in einer einzigen Transaktion ausführen, können Sie sicherstellen, dass alle Befehle erfolgreich abgeschlossen werden, bevor Sie die Änderungen festschreiben. Wenn einer der Befehle fehlschlägt, bleibt keine der Änderungen aus den erfolgreichen Befehlen erhalten.

Die folgenden Beispiele zeigen erfolgreiche und erfolglose Transaktionen:

  • Erfolgreiche Befehlsausführung

    snow sql -q "insert into my_tbl values (123); insert into my_tbl values (124);" --single-transaction
    
    Copy
    BEGIN;
    +----------------------------------+
    | status                           |
    |----------------------------------|
    | Statement executed successfully. |
    +----------------------------------+
    
    insert into my_tbl values (123);
    +-------------------------+
    | number of rows inserted |
    |-------------------------|
    | 1                       |
    +-------------------------+
    
    insert into my_tbl values (124);
    +-------------------------+
    | number of rows inserted |
    |-------------------------|
    | 1                       |
    +-------------------------+
    
    COMMIT
    +----------------------------------+
    | status                           |
    |----------------------------------|
    | Statement executed successfully. |
    +----------------------------------+
    

    Sie können dann überprüfen, ob die Befehle in die Datenbank übertragen wurden:

    snow sql -q "select count(*) from my_tbl"
    
    Copy
    select count(*) from my_tbl
    +----------+
    | COUNT(*) |
    |----------|
    | 2        |
    +----------+
    
  • Erfolglose Einzeltransaktion

    snow sql -c patcli -q "insert into my_tbl values (123); insert into my_tbl values (124); select BAD;" --single-transaction
    
    Copy
    BEGIN;
    +----------------------------------+
    | status                           |
    |----------------------------------|
    | Statement executed successfully. |
    +----------------------------------+
    
    insert into my_tbl values (123);
    +-------------------------+
    | number of rows inserted |
    |-------------------------|
    | 1                       |
    +-------------------------+
    
    insert into my_tbl values (124);
    +-------------------------+
    | number of rows inserted |
    |-------------------------|
    | 1                       |
    +-------------------------+
    
    select BAD;
    ╭─ Error ───────────────────────────────────────────────────────────────────────────────╮
    │ 000904 (42000): 01bc3b84-0810-0247-0001-c1be14ee11ce: SQL compilation error: error    │
    │ line 1 at position 7                                                                  │
    │ invalid identifier 'BAD'                                                              │
    ╰───────────────────────────────────────────────────────────────────────────────────────╯
    

Sie können dann überprüfen, dass die Befehle nicht in die Datenbank übertragen wurden:

snow sql -q "select count(*) from my_tbl"
Copy
select count(*) from my_tbl
+----------+
| COUNT(*) |
|----------|
| 0        |
+----------+

Eingabe von SQL-Befehlen im interaktiven Modus

Der Befehl snow sql unterstützt einen interaktiven Modus, in dem Sie SQL-Befehle einzeln eingeben können. Der interaktive Modus bietet die folgenden Features:

  • Syntax-Hervorhebung

    Syntax-Hervorhebung im interaktiven Modus
  • Code-Vervollständigung beim Tippen

    Code-Vervollständigung im interaktiven Modus
  • Durchsuchbarer Verlauf

    Durch Drücken von CTRL-R: können Sie Ihren Befehlsverlauf durchsuchen:

    Interaktiver Modus, durchsuchbarer Verlauf
  • Mehrzeilige Eingabe

    Wenn Sie ENTER in einer Zeile drücken, die nicht mit einem Semikolon endet (;), springt der Cursor für weitere Befehle in die nächste Zeile, bis eine Anweisung mit einem Semikolon endet.

    Interaktiver Modus, mehrzeilige Eingabe

Um den interaktiven Modus zu verwenden, geben Sie den Befehl snow sql ein, gefolgt von ENTER, wie gezeigt:

snow sql
Copy

Der Befehl öffnet eine Sub-Shell mit einer >-Eingabeaufforderung, an der Sie interaktiv SQL-Befehle eingeben können:

$ snow sql
  ╭───────────────────────────────────────────────────────────────────────────────────╮
  │ Welcome to Snowflake-CLI REPL                                                     │
  │ Type 'exit' or 'quit' to leave                                                    │
  ╰───────────────────────────────────────────────────────────────────────────────────╯
  >

Sie können dann SQL-Befehle eingeben, wie gezeigt:

> create table my_table (c1 int);
Copy
+-------------------------------------+
| status                              |
|-------------------------------------|
| Table MY_TABLE successfully created.|
+-------------------------------------+

Bemerkung

Sie müssen jede SQL-Anweisung mit einem Semikolon beenden (;).

Um den interaktiven Modus zu verlassen, geben Sie exit, quit, oder CTRL-D ein.