SQL ステートメントの実行¶
Snowflake CLI では、 snow sql コマンドを使用して、 SQL クエリ、アドホッククエリ、または SQL クエリを含むファイルを実行できます。
アドホッククエリを実行するには、次のようなコマンドを実行します。
snow sql -q "SELECT * FROM FOO"
SQL クエリを含むファイルを実行するには、次のようなコマンドを実行します。
snow sql -f my_query.sql
snow sql
コマンドは複数のステートメントを実行でき、その場合は複数の結果セットが返されます。たとえば、次のように実行します。
snow sql -q "select 'a', 'b'; select 'c', 'd';"
出力は次のようになります。
select 'a', 'b';
+-----------+
| 'A' | 'B' |
|-----+-----|
| a | b |
+-----------+
select 'c', 'd';
+-----------+
| 'C' | 'D' |
|-----+-----|
| c | d |
+-----------+
また、 スクリプトブロック を、 Snowflake CLI の中で実行することもできます。この場合、 $$
区切り文字に関する注意事項があります。
例:
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;
$$
;
オペレーティングシステムによっては、スクリプトブロックの区切り文字として認識せず、プロセス ID (PID)のように $$
を解釈するものもあります。この制限に対処するために、次のような選択肢を使うことができます。
それでもコマンドラインでスクリプトブロックを指定する場合は、
$$
区切り文字をエスケープして、\$\$
のようにすることができます。デフォルトの
$$
区切り文字のスクリプトブロックを別のファイルに置き、snow sql -f <filename>
コマンドで呼び出すこともできます。
詳細については、 snow 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
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 での変数を使用する をご参照ください。
SQL クエリの非同期実行¶
Snowflake CLI を使用すると、1つ以上の SQL クエリを非同期に実行できます。結果を待つ代わりに、 snow sql
コマンドはSnowflakeでクエリをスケジュールし、クエリ ID を返します。クエリ終了後、 !result クエリコマンドまたは SQL RESULT_SCAN コマンドで結果を取得できます。
SQL クエリを非同期的に実行するには、次に示すように、 ;
ではなく ;>
でクエリを終了します。
snow sql -q 'select "My async query" ;>'
以下の例は、単一のクエリを非同期に実行します。
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 クエリを中止します。
Tip
SQL クエリを一重引用符(''
)ではなく二重引用符(""
)で囲んだ場合、使用するシェルによっては感嘆符(!
)をエスケープする必要があるかもしれません。
ローカルファイルまたは URLs で SQL を実行する¶
SQL クエリで !source
クエリコマンドを使用すると、ローカルファイルまたは URL ベースのファイルで SQL を実行できます。例えば、以下のコマンドは、 my_sql_code.sql
という名前のローカルファイル内のすべての SQL コマンドを実行します。
snow sql -q '!source my_sql_code.sql'
次のように、 !source
コマンドを SQL ファイルにネストすることもできます。
select emp_id FROM employees;
!source code_file_2.sql
この例では、コマンドは SELECT クエリを実行し、 code_file_2.sql
ファイル内の SQL コマンドを実行します。!source
クエリを実行する前に、 Snowflake CLI は次のことを行います。
変数の置換とテンプレートを評価します。
再帰が発生しないように、ネストされたすべてのファイルの内容を読み込みます。
変数とテンプレートが解決され、再帰が検出されない場合、コマンドは実行のためにコードをSnowflakeに送信します。
注釈
!source
クエリの周囲に一重引用符(''
)ではなく二重引用符(""
)を使用すると、使用するシェルによっては !
(\!
)をエスケープする必要があるかもしれません。
以下の例は、ソースファイルを実行するさまざまな方法を示しています。
ローカルファイルのコードを実行します。
この例では、ローカルの SQL ファイルに簡単なクエリがあることを想定しています。
cat code_to_execute.sql
select 73;
ファイル内のコードを実行するには、以下のコマンドを入力します。
snow sql -q '!source code_to_execute.sql'
select 73; +----+ | 73 | |----| | 73 | +----+
URL ベースのファイル内のコードを実行します。
この例では、 URL の SQL ファイルに同じ簡単なクエリがあると仮定しています。
ファイル内のコードを実行するには、以下のコマンドを入力します。
snow sql -q '!source https://trusted-host/trusted-content.sql'
select 73; +----+ | 73 | |----| | 73 | +----+
変数置換とテンプレートを使用するコードを実行します。
この例では、ローカルの SQL ファイルにテンプレート変数を使用するクエリがあると仮定しています。
cat code_with_variable.sql
select '<% ctx.env.Message %>';
ファイル内のコードを実行するには、変数値を定義する以下のコマンドを入力します。
snow sql -q '!source code_&value.sql;' -D value=with_variable --env Message='Welcome !'
select 'Welcome !'; +-------------+ | 'WELCOME !' | |-------------| | Welcome ! | +-------------+
注釈
!source
コマンドは、従来の !load
エイリアスをサポートしています。
すべての SQL クエリをリスト¶
!queries
クエリコマンドは、アカウントのすべてのクエリをリストします。デフォルトでは、コマンドは現在のセッションで実行された最新の25のクエリをリストします。
例えば、次の !queries
クエリコマンドは、特定のユーザーに対する最新の3つのクエリを返します。
snow sql -q '!queries user=user1 amount=3'+-------------------------------------------------------------------------------------------------------------------------------------+ | 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 | +-------------------------------------------------------------------------------------------------------------------------------------+
以下のフィルターを使用して、返されるクエリのリストを絞り込むことができます。
フィルター |
デフォルト |
説明 |
---|---|---|
amount(整数) |
25 |
最近返されたクエリの数(デフォルト: 25)。 |
session (boolean) |
N/A |
指定されている場合は、現在のセッションで実行されたクエリのみを返します。 |
warehouse (string) |
なし |
指定したウェアハウスのみで実行されたクエリを返します。 |
user (string) |
なし |
指定したユーザーのみが実行したクエリを返します。 |
duration(ミリ秒) |
0 |
指定したミリ秒以上のクエリのみを返します。 |
start_date (string) |
なし |
指定した日付以降に実行されたクエリのみを返します。日付は ISO 形式で指定されることが期待されます(例: |
end_date (string) |
なし |
指定した日付より前に実行されたクエリのみを返します。日付は ISO 形式で指定されることが期待されます(例: |
start(整数) |
なし |
指定したUnixタイムスタンプ(ミリ秒単位)以降に実行されたクエリのみを返します。 |
end(整数) |
なし |
指定したUnixタイムスタンプ(ミリ秒単位)より前に実行されたクエリのみを返します。 |
status(列挙型) |
なし |
以下のステータスのクエリのみを返します。
|
type |
なし |
以下のタイプのクエリのみを返します。
|
以下の例では、異なるフィルターを使用したクエリを返します。
現在のセッションで実行された最新のクエリ25件を返します。
snow sql -q 'select 42; select 15; !queries session'
アカウントで実行された最新のクエリ20件を返します。
snow sql -q '!queries amount=20'
アカウントで実行されたクエリのうち、実行に200ミリ秒以上かかった最新のクエリ20件を返します。
snow sql -q '!queries amount=20 duration=200'
指定したウェアハウスで実行された最新のクエリ25件を返します。
snow sql -q '!queries warehouse=mywh'
完了した SQL クエリ結果を返す¶
!result
クエリコマンドは、クエリ ID を指定すると、完了したクエリの結果を返します。クエリ ID は以下の方法で取得できます。
snow sql -q '!result 01bc3011-080f-f2d7-0001-c1be14bae7c2'
+-----------------------+
| 'THIS IS ASYNC QUERY' |
|-----------------------|
| This is async query |
+-----------------------+
SQL クエリを中止する¶
!abort
クエリコマンドは、そのクエリ ID が指定されると、アクティブなクエリを中止します。クエリ ID は以下の方法で取得できます。
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
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"
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
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"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.|
+-------------------------------------+
注釈
各 SQL ステートメントをセミコロン(;
)で終わらせる必要があります。
インタラクティブモードを終了するには、 exit
、 quit
、または CTRL-D と入力します。