SQL ステートメントの実行¶

SQL テンプレートの変数の使用¶

状況によっては、コンテキストに応じて SQL クエリを変更する必要がある場合があります。snow sql コマンドはクライアント側の変数置換をサポートしており、クエリを送信する前にローカルで解決されるコマンド内の変数を使用できます。 SQL 文字列内の変数は <% 変数名 %> の形式をとり、 -D （または --variable）オプションで変数の値を指定します。

注釈

現在、テンプレートには SnowSQL &variable_name と <% variable_name %> 構文を使用できます。ただし、Snowflakeでは <% variable_name %> 構文の使用を推奨しています。

たとえば、クライアント側の変数を使用してデータベースを指定するには、次のようなコマンドを入力します。

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

実行されると、コマンドは <% データベース %> 変数の値を dev に置き換えて dev.logs ファイル名を作成し、 select * from dev.logs SQL クエリをSnowflakeに送信して処理します。

次に示すように、複数の変数入力を指定することもできます。

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

この例では、次の SQL クエリが生成されます。

grant usage on database dev to eng_rl

--enable-templating オプションを使用すると、どのテンプレート化構文で SQL クエリを解決するかを指定できます。Snowflake CLI は、次の構文をサポートしています。

• STANDARD:標準の Snowflake CLI 変数構文（<% variable_name %>）をサポートします。デフォルトで有効。

• LEGACY:SnowSQL 変数構文（&{ variable_name } または:codenowrap:&variable_name）をサポートします。デフォルトで有効。

• JINJA:jinja変数構文（{{ variable_name}}）をサポートします。デフォルトで無効。

• ALL:サポートされているすべての構文を許可します。デフォルトで無効。

• NONE:テンプレート化はサポートされていません。デフォルトで無効。

次の例では、テンプレート化をサポートするさまざまな方法を説明します。

• テンプレート化を無効にし、いずれのクエリ変数も解決されないようにします。

  snow sql --enable-templating NONE -q "select '<% not_resolved %> &not_resolved'"
  

  Copy

• LEGACY テンプレート化を許可せずに、JINJA および STANDARD テンプレート化を許可します。

  snow sql --enable-templating JINJA --enable-templating STANDARD -q "select '<% resolved %> {{ resolved }} &not_resolved'"
  

  Copy

• すべての構文を有効にすると、SQL クエリは3つの構文すべてを解決します。

  snow sql --enable-templating ALL -q "select '<% resolved %> {{ resolved }}'"
  snow sql --enable-templating ALL -q "select '&resolved {{ resolved }}'"
  

  Copy

snowflake.yml プロジェクト定義ファイルに変数を保存する¶

snow sql コマンドラインオプションとして変数を指定することが必ずしも実用的ではなく、またコマンドラインで機密性の高い値を指定したくない場合もあります。このような場合は、 snowflake.yml プロジェクト定義ファイルで変数と値を定義できます。その場合、 -D "<変数> = <値>" オプションを使用する代わりに、 <% ctx.env.<変数名> %> の形式で変数名を指定します。

前のセクションの例を使用して、データベースとロールの変数を snowflake.yml ファイルに保存し、クエリを次のように変更できます。

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

この例では、 snow sql コマンドはプロジェクト定義ファイル内の変数定義を検索し、コマンドラインに表示させずに値を抽出します。snowflake.yml ファイルは、現在の作業ディレクトリか、 :codenowrap: -p オプションで指定された場所のいずれかにある必要があります。

これらの値をプロジェクト定義ファイルに保存する方法の詳細については、 SQL での変数を使用する をご参照ください。

Executing SQL queries asynchronously¶

Snowflake CLI lets you execute one or more SQL queries asynchronously. Instead of waiting for a result, the snow sql command schedules the queries at Snowflake and returns a query ID. After a query finishes, you can get the result using the !result query command or the SQL RESULT_SCAN command.

To execute a SQL query asynchronously, end the query with ;> instead of ;, as shown:

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

The following example executes a single query asynchronously:

snow sql -q "select 'This is async query';>"

select 'This is async query'
+--------------------------------------+
| scheduled query ID                   |
|--------------------------------------|
| 01bc3011-080f-f2d7-0001-c1be14bae7c2 |
+--------------------------------------+

返されたクエリ ID を !result クエリコマンドで使用すると、クエリ結果を表示できます。

snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'

path-to-private-key-file
+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query   |
+-----------------------+

また、次に示すように、非同期でも同期でも、クエリ文字列で複数のクエリを実行することもできます。

snow sql -q "select 'This is async query';> select 'Not an async query'; select 'Another async query';>"

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

SQL クエリコマンドの使用法¶

Snowflake CLI は、 SQL クエリ内で使用できる次のコマンドを提供します。

• !source は、ローカルファイルまたは URLs で SQL を実行します。

• !queries は、すべての SQL クエリをリストします。

• !result は、 SQL クエリの結果を表示します。

• !abort は、アクティブな SQL クエリを中止します。

• !edit, which opens an external editor to modify and execute SQL commands.

snow sql -q '!source my_sql_code.sql'

select emp_id FROM employees;
!source code_file_2.sql

snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'

+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query   |
+-----------------------+

snow sql -q '!abort 01bc3011-080f-f2d7-0001-c1be14bae7c2'

+-------------------------------------------------------------+
| SYSTEM$CANCEL_QUERY('01BC3011-080F-F2D7-0001-C1BE14BAE7C2') |
|-------------------------------------------------------------|
| Identified SQL statement is not currently executing.        |
+-------------------------------------------------------------+

1つのトランザクションで複数のコマンドを入力する場合¶

--single-transaction オプションを使用すると、複数の SQL コマンドを入力し、オールオアナッシングのコマンドセットとして実行することができます。単一のトランザクションでコマンドを実行することで、変更をコミットする前に、すべてのコマンドが正常に完了したことを確認できます。コマンドのどれかが失敗した場合、成功したコマンドからの変更はどれも持続しません。

以下の例は、成功したトランザクションと失敗したトランザクションを示しています。

• コマンド実行成功

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

  その後、コマンドがデータベースにコミットされたことを確認できます。

  snow sql -q "select count(*) from my_tbl"
  

  Copy

  select count(*) from my_tbl
  +----------+
  | COUNT(*) |
  |----------|
  | 2        |
  +----------+
  

• 単一トランザクションの失敗

  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'                                                              │
  ╰───────────────────────────────────────────────────────────────────────────────────────╯
  

その後、コマンドがデータベースにコミットされていないことを確認できます。

snow sql -q "select count(*) from my_tbl"

Copy

select count(*) from my_tbl
+----------+
| COUNT(*) |
|----------|
| 0        |
+----------+

インタラクティブモードでの SQL コマンドの入力¶

snow sql コマンドは、 SQL コマンドを一度に入力できるインタラクティブモードをサポートしています。インタラクティブモードには以下の機能があります。

• 構文の強調表示

  

• タイプ中のコード補完

  

• 検索可能な履歴

  CTRL-R:を押すと、コマンド履歴を検索できます。

  

• マルチライン入力

  セミコロンで終わっていない行（;）で ENTER を押すと、ステートメントがセミコロンで終わるまで、カーソルは次の行に移動してコマンドを続けます。

  

インタラクティブモードを使用するには、以下のように、 snow sql コマンドに続いて、 ENTER を入力します。

snow sql

このコマンドは、 > プロンプトのあるサブシェルを開き、 SQL コマンドを対話的に入力できます。

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

以下のように、 SQL コマンドを入力します。

> create table my_table (c1 int);

+-------------------------------------+
| status                              |
|-------------------------------------|
| Table MY_TABLE successfully created.|
+-------------------------------------+

インタラクティブモードを終了するには、 exit、 quit、または CTRL-D と入力します。