SnowSQLの使用

このトピックでは、クライアントの開始/停止、クライアント内でのコマンドと変数の使用、その他の一般的な使用情報など、SnowSQL の使用方法について説明します。

このトピックの内容:

コマンドの実行

Snowflakeセッションでは、コマンドを発行して特定のアクションを実行できます。SnowSQL のすべてのコマンドは感嘆符(!)で始まり、その後にコマンド名が続きます。

例:

user#> !help

+------------+-------------------------------------------+-------------+--------------------------------------------------------------------------------------------+
| Command    | Use                                       | Aliases     | Description                                                                                |
|------------+-------------------------------------------+-------------+--------------------------------------------------------------------------------------------|
| !abort     | !abort <query id>                         |             | Abort a query                                                                              |
| !connect   | !connect <connection_name>                |             | Create a new connection                                                                    |
| !define    | !define <variable>=<value>                |             | Define a variable as the given value                                                       |
| !edit      | !edit <query>                             |             | Opens up a text editor. Useful for writing longer queries. Defaults to last query          |
| !exit      | !exit                                     | !disconnect | Drop the current connection                                                                |
| !help      | !help                                     | !helps, !h  | Show the client help.                                                                      |
| !options   | !options                                  | !opts       | Show all options and their values                                                          |
| !pause     | !pause                                    |             | Pauses running queries.                                                                    |
| !print     | !print <message>                          |             | Print given text                                                                           |
| !queries   | !queries help, <filter>=<value>, <filter> |             | Lists queries matching the specified filters. Write <!queries> help for a list of filters. |
| !quit      | !quit                                     | !q          | Drop all connections and quit SnowSQL                                                      |
| !rehash    | !rehash                                   |             | Refresh autocompletion                                                                     |
| !result    | !result <query id>                        |             | See the result of a query                                                                  |
| !set       | !set <option>=<value>                     |             | Set an option to the given value                                                           |
| !source    | !source <filename>, <url>                 | !load       | Execute given sql file                                                                     |
| !spool     | !spool <filename>, off                    |             | Turn on or off writing results to file                                                     |
| !system    | !system <system command>                  |             | Run a system command in the shell                                                          |
| !variables | !variables                                | !vars       | Show all variables and their values                                                        |
+------------+-------------------------------------------+-------------+--------------------------------------------------------------------------------------------+
Copy

各コマンドの詳細な説明については、(このトピックの)「コマンドリファレンス」をご参照ください。

変数の使用

変数を使用して、Snowflakeセッションで値を格納し、再利用できます。変数を使用すると、クエリでユーザー定義値とデータベース値を使用できます。

次のセクションでは、変数を定義して使用する方法について説明します。

変数の定義

いくつかの方法で SnowSQL の変数を定義できます。

接続前の変数の定義(構成ファイル)

Snowflakeに接続する前に変数を定義するには、 config 構成ファイルに変数を追加します。

  1. テキストエディターで、 SnowSQL構成ファイル (名前 config)を開きます。ファイルのデフォルトの場所は次のとおりです。

    Linux/macOS:

    ~/.snowsql/

    Windows:

    %USERPROFILE%\.snowsql\

    注釈

    SnowSQL の起動時に、 --config path コマンドラインフラグを指定すると、デフォルトの場所を変更できます。

  1. [variables] セクションで、使用する予定の変数を定義します。

    [variables]
    <variable_name>=<variable_value>
    
    Copy

    条件:

    • variable_name は、変数の名前を表す英数字の文字列(大文字と小文字を区別しない)です。

    • variable_value は、変数の値を表す文字列です。必要に応じて、文字列を一重引用符または二重引用符で囲むことができます。

    例:

    [variables]
    tablename=CENUSTRACKONE
    
    Copy

接続中の変数の定義(-D または --variable コマンドラインフラグ)

Snowflakeへの接続中に変数を定義するには、ターミナルコマンドラインで -D または --variable コマンドラインフラグを指定します。このフラグの引数には、変数の名前と値を variable_name=variable_value の形式で指定します。

例:

Linux/macOS:
$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=$DB_KEY
Copy
Windows:
$ snowsql ... -D tablename=CENUSTRACKONE --variable db_key=%DB_KEY%
Copy

上記の例では、

  • -Dtablename という名前の変数を CENUSTRACKONE に設定します。

  • --variabledb_key という名前のSnowflake変数を DB_KEY 環境変数に割り当てます。

セッション内の変数の定義(!define コマンド)

Snowflakeへの接続後に変数を定義するには、セッションで !define コマンドを実行します。

例:

user#> !define tablename=CENUSTRACKONE
Copy

変数置換の有効化

SnowSQL が変数の値を置き換えることができるようにするには、次のいずれかの方法で variable_substitution 構成オプションを true に設定する必要があります。

  • SnowSQL を開始する前にこのオプションを設定するには、テキストエディターで SnowSQL 構成ファイル を開き、 [options] セクションでこのオプションを設定します。

    [options]
    variable_substitution = True
    
    Copy
  • SnowSQL の起動時にこのオプションを設定するには、 -o コマンドラインフラグを指定します。

    $ snowsql ... -o variable_substitution=true
    
    Copy
  • SnowSQL セッションでこのオプションを設定するには、セッションで !set コマンドを実行します。

    user#> !set variable_substitution=true
    
    Copy

    注釈

    現在、 variable_substitution オプションなどのオプション値を 設定解除 するオプションはありません。変数置換を無効にする必要がある場合は、コマンド !set variable_substitution=false を実行します。

セッションでの変数の置換

変数置換 を有効にした後に、 SQL ステートメントで変数を使用できます。

ステートメントで変数を使用するには、 &variable_name 構文を使用します。変数名では大文字と小文字が区別されないことに注意してください。例:

user#> !define snowshell=bash

user#> !set variable_substitution=true

user#> select '&snowshell';

+--------+
| 'BASH' |
|--------|
| bash   |
+--------+
Copy

variable_substitution オプションが有効になっていない場合、変数の置換は行われません。例:

user#> !define snowshell=bash

user#> !set variable_substitution=false

user#> select '&snowshell';

+--------------+
| '&SNOWSHELL' |
|--------------|
| &snowshell   |
+--------------+
Copy

定義されていない変数を参照すると、 SnowSQL はエラーを表示します。例:

select '&z';

Variable z is not defined
Copy

変数とテキストを組み合わせるには、変数参照を中括弧で囲みます。例:

user#> !define snowshell=bash

user#> !set variable_substitution=true

select '&{snowshell}_shell';

+--------------+
| 'BASH_SHELL' |
|--------------|
| bash_shell   |
+--------------+
Copy

置換を使用せずにアンパサンド記号を使用するには、2番目のアンパサンド記号でアンパサンド記号をエスケープします。

&&variable

例:

user#> !set variable_substitution=true

user#> select '&notsubstitution';

Variable notsubstitution is not defined

user#> select '&&notsubstitution';

+--------------------+
| '&NOTSUBSTITUTION' |
|--------------------|
| &notsubstitution   |
+--------------------+
Copy

変数のリスト

変数を一覧表示するには、セッションで !variables または !vars コマンドを実行します。

user#> !variables

+-----------+-------+
| Name      | Value |
|-----------+-------|
| snowshell | bash  |
+-----------+-------+
Copy

組み込み変数の使用

SnowSQL には、現在のユーザーセッションで実行されたステートメントに関するメタデータを返す組み込み変数のセットが含まれています。

これらの変数名はそれぞれ、2つのアンダースコア文字(「__」)で始まります。

__rowcount

ユーザーが実行した最新の DML ステートメントによって影響を受けた行の数を返します。

user#> insert into a values(1),(2),(3);

+-------------------------+
| number of rows inserted |
|-------------------------|
|                       3 |
+-------------------------+
3 Row(s) produced. Time Elapsed: 0.950s

user#> !set variable_substitution=true

user#> select &__rowcount;

+---+
| 3 |
|---|
| 3 |
+---+
Copy
__sfqid

ユーザーが実行した最新のクエリのクエリ ID を返します。

user#> !set variable_substitution=true

user#> select * from a;

user#> select '&__sfqid';

+----------------------------------------+
| 'A5F35B56-49A2-4437-BA0E-998496CE793E' |
|----------------------------------------|
| a5f35b56-49a2-4437-ba0e-998496ce793e   |
+----------------------------------------+
Copy

オートコンプリートの使用

さまざまな SQL 関数、テーブル名、および変数は SnowSQL に格納され、インタラクティブモードでオートコンプリートされます。オートコンプリートの候補を選択するには、 Tab キーを押します。別の候補を選択するには、 キーを使って希望のオプションをハイライトし、 Tab キーを押します。

インタラクティブにオートコンプリートを無効にするには、 構成ファイルauto_completion 構成オプションを False に設定します。

コマンドライン履歴の表示

キーを使用して、最近のコマンドライン履歴を呼び出すことができます。キーを繰り返し押して、バッファをスクロールします。

履歴ファイル

インタラクティブコマンドライン履歴ファイルの名前は history で、 ~/.snowsql/history にあります。

バッチスクリプトの実行

次の2つの方法でバッチスクリプトを実行できます。

  • 接続パラメーターの使用(Snowflakeへの接続中)

  • コマンドの実行(Snowflakeセッションのコマンドライン上)

接続中の実行(-f 接続パラメーター)

Snowflakeへの接続中に SQL スクリプトを実行するには、 -f <入力ファイル名> 接続パラメーターを使用します。

スクリプトの出力ファイルは、 -o output_file=<出力ファイル名> を使用して指定できます。加えて、 -o quiet=true を使用して標準出力をオフにし、 -o friendly=false を使用して起動メッセージと終了メッセージをオフにすることができます。

例:

snowsql -a myorganization-myaccount -u jsmith -f /tmp/input_script.sql -o output_file=/tmp/output.csv -o quiet=true -o friendly=false -o header=false -o output_format=csv
Copy

すべての接続パラメーターの詳細については、 接続パラメーターリファレンス をご参照ください。

セッションでの実行(!source または !load コマンド)

Snowflakeへの接続後に SQL スクリプトを実行するには、セッションで !source (または !load)コマンドを実行します。

例:

user#> !source example.sql
Copy

データのエクスポート

次の 構成オプション を使用して、定義された形式でクエリ結果をファイルに出力します。

  • output_format=output_format

  • output_file=output_filename

出力からスプラッシュテキスト、ヘッダーテキスト、タイミング、および別れのメッセージを削除するには、次のオプションも設定します。

  • friendly=false

  • header=false

  • timing=false

すべての構成オプションと同様に、次のいずれかの方法を使用して設定できます。

  • 構成ファイル内(Snowflakeに接続する前)。

  • (Snowflakeへの接続中に) -o または --options 接続パラメーターを使用します。

  • !set コマンドの実行(Snowflakeセッションのコマンドラインで)。

連続したクエリが出力ファイルに追加されることに注意してください。または、クエリ出力をファイルにリダイレクトし、それぞれの新しいステートメントでファイルを上書きするには、スクリプトで大なり記号(>)を使用します。

次の例では、SnowSQL は名前付き接続を使用してアカウントに接続し、テーブルをクエリします。出力は、現在のローカルディレクトリの output_file.csv という名前の CSV ファイルに書き込まれます。

Linux/macOS:

snowsql -c my_example_connection -d sales_db -s public -q 'select * from mytable limit 10' -o output_format=csv -o header=false -o timing=false -o friendly=false  > output_file.csv
Copy
Windows:

snowsql -c my_example_connection -d sales_db -s public -q "select * from mytable limit 10" -o output_format=csv -o header=false -o timing=false -o friendly=false  > output_file.csv
Copy

SnowSQL プロンプト形式の変更

SnowSQL プロンプトは、現在のセッションに関するコンテキスト情報を動的に表示します。

  • Snowflakeにログインすると、プロンプトにユーザー名とデフォルトのウェアハウス、データベース、スキーマ(デフォルトが設定されている場合)が表示されます。

  • セッションで USE コマンドを使用してウェアハウス、データベース、またはスキーマを設定または変更すると、プロンプトが変更され、コンテキストが反映されます。

prompt_format 構成オプションと各オブジェクトタイプの括弧内のPygmentsトークンを [token] (例: [user] または [warehouse])の形式で使用して、プロンプトの外観と構造を制御できます。

トークンは、今後のプロンプトに影響します。各トークンの順序、色、およびトークン間の区切り文字を変更できます。

すべての構成オプションと同様に、次のいずれかの方法を使用してプロンプトを設定できます。

  • 構成ファイル内(Snowflakeに接続する前)。

  • (Snowflakeへの接続中に) -o または --options 接続パラメーターを使用します。

  • !set コマンドの実行(Snowflakeセッションのコマンドラインで)。

注釈

接続パラメーターを使用して、またはコマンドラインで直接プロンプトを変更した場合、変更は現在のセッションにのみ適用されます。将来のセッションで変更を保持するには、構成ファイルでオプションを設定します。

サポートされているトークン

SnowSQL では、次のオブジェクトタイプをトークンとしてサポートします。

  • user

  • account

  • role

  • database

  • schema

  • warehouse

デフォルトのプロンプト

SnowSQL のデフォルトプロンプトは、次のトークンと構造を使用します。

[user]#[warehouse]@[database].[schema]>
Copy

例:

jdoe#DATALOAD@BOOKS_DB.PUBLIC>
Copy

プロンプトの例

上記の例に続けて、コマンドラインで実行された次の !set コマンドは、ロールトークンを追加し、トークンの順序を userroledatabaseschema、そして warehouse に変更します。また、各トークンの区切り文字をピリオド(.)に変更し、異なる色を使用するようにトークンを設定します。

jdoe#DATALOAD@BOOKS_DB.PUBLIC> !set prompt_format=[#FF0000][user].[role].[#00FF00][database].[schema].[#0000FF][warehouse]>
Copy

この例では、セッションに対して次のプロンプトが表示されます。

SnowSQL プロンプト形式

Snowflake からの接続解除と SnowSQL の停止

SnowSQL は次の個別のコマンドを提供します。

  • SnowSQL を停止せずに個々の接続(セッション)を終了します。

  • SnowSQL を終了すると、すべての接続も自動的に終了します。

接続/セッションを終了するには、 !exit コマンド(またはそのエイリアス !disconnect)を使用します。SnowSQL config ファイルで複数の接続を定義できる場合は、 !connect <接続名> を使用して再度接続できます。開いている接続が1つしかない場合、 !exit コマンドによっても SnowSQL が終了/停止することに注意してください。

すべての接続を終了して SnowSQL を終了/停止するには、 !quit コマンド(またはそのエイリアスの !q)を使用します。キーボードで CTRL + d と入力することもできます。

終了コード

SnowSQL の終了/終了時に返される可能性のあるいくつかの終了コードがあります。

0:

すべてが正常に実行されました。

1:

クライアントで問題が発生しました。

2:

コマンドライン引数に問題が発生しました。

3:

SnowSQL でサーバーに接続できませんでした。

4:

SnowSQL でサーバーと適切に通信できませんでした。

5:

exit_on_error 構成オプションが設定され、エラーによって SnowSQL が終了しました。

デフォルトのキーバインディング

kbd:Tab キー

現在のオートコンプリートの提案を受け入れます。

kbd:CTRL + d

SnowSQL を終了または停止します。

コマンドリファレンス

!abort

クエリを中止します(クエリ ID で指定)。クエリ ID は、ウェブインターフェイスの History 履歴タブ ページから取得できます。

例:

user#> !abort 77589bd1-bcbf-4ec8-9ebc-6c949b00614d;
Copy

!connect

SnowSQL は !connect <接続名> との複数のセッション(接続)をサポートします。

  • connection_name に関連付けられた接続パラメーター/オプションは、SnowSQL 構成ファイルの対応する [connections.<接続名>] セクションに格納されます。

  • パラメーター/オプションが [connections.<接続名>] セクションで指定されていない場合、指定されていないパラメーターはデフォルトで [connections] 下のパラメーターになります。

接続すると、接続が接続スタックに追加され、終了すると以前の接続に戻ります。終了すると、接続の数に関係なく、すべての接続が終了します。

例:

構成ファイル:

[connections.my_example_connection]
...
Copy

コマンドライン:

user#> !connect my_example_connection
Copy

!define

次の形式を使用して、変数を指定された値に設定します。

!define <変数名>=<変数値>

名前と値は、スペースを含まない単一の = で区切る必要があります。変数で使用できる有効な文字は次のとおりです。

0-9a-zA-Z_

変数の定義と使用の詳細については、 変数の使用 をご参照ください。

!edit

editor 接続パラメーターを使用して設定されたエディターを開きます(エディターが設定されていない場合、デフォルトは vim です)。このコマンドは、クエリを引数として受け入れます。引数が渡されない場合、最後に実行されたクエリを開きます。

注釈

エディターの終了前または終了中に保存する必要があります。そうしないと、エディターで入力/変更されたテキストは保存されません。

!exit!disconnect

現在の接続をドロップし、最後の接続である場合は SnowSQL を終了します。

!help!helps!h

SnowSQL コマンドのヘルプを表示します。

!options!opts

すべての SnowSQL 構成オプション と現在設定されている値のリストを返します。これらのオプションは、現在の SnowSQL セッションで !set コマンドを使用して設定できます。

注釈

これらのオプションは、SnowSQL の 構成ファイル で、または SnowSQL を呼び出すときにコマンドラインで コネクターパラメーター として設定することもできます。

!pause

実行中のクエリを一時停止します。改行キーを押して続行します。

!print

指定したテキストを画面および現在スプールしているファイルに出力します。

例:

user#> !print Include This Text
Copy

!queries

指定したフィルターに一致するすべてのクエリをリストします。デフォルトのフィルターは sessionamount=25 で、現在のセッションの最新のクエリ25を返します。

例:

  • この現在のセッションで実行された最新の25のクエリを返します。

    !queries session
    
    Copy
  • アカウントで実行された最新のクエリ20を返します。

    !queries amount=20
    
    Copy
  • アカウントで実行された200ミリ秒以上かかった最新のクエリ20を返します。

    !queries amount=20 duration=200
    
    Copy
  • 指定されたウェアハウスで実行された最新の25クエリを返します。

    !queries warehouse=mywh
    
    Copy

このコマンドは、返されたクエリ ID ごとに変数を作成します。これらの変数を使用するには、変数置換を有効化する必要があることに注意してください。例:

user#> !queries session

+-----+--------------------------------------+----------+-----------+----------+
| VAR | QUERY ID                             | SQL TEXT | STATUS    | DURATION |
|-----+--------------------------------------+----------+-----------+----------|
| &0  | acbd6778-c68c-4e79-a977-510b2d8c08f1 | select 1 | SUCCEEDED |       19 |
+-----+--------------------------------------+----------+-----------+----------+

user#> !result &0

+---+
| 1 |
|---|
| 1 |
+---+

user#> !result acbd6778-c68c-4e79-a977-510b2d8c08f1

+---+
| 1 |
|---|
| 1 |
+---+
Copy

!quit!q (kbd:CTRL + d も可)。

すべての接続をドロップし、SnowSQL を終了します。

!rehash

オートコンプリートトークンを再同期します。

通常の使用では、オートコンプリートトークンを再同期する必要はありません。ただし、特定のシナリオ(例えば、別のセッションで新しいユーザー定義関数が作成される場合)では、サーバー側のトークンを強制的に更新することが役に立つ場合があります。

!result

完了したクエリの結果を返します(クエリ ID で指定)。クエリ IDs は、ウェブインターフェイスの History 履歴タブ ページまたは !queries コマンドを使用して取得できます。

クエリがまだ実行中の場合、コマンドはクエリが完了するまで待機します。

例:

user#> !result 77589bd1-bcbf-4ec8-9ebc-6c949b00614d;
Copy

!set

<オプション>=<値> 形式を使用して、指定された SnowSQL 構成オプション を特定の値に設定します。

現在、オプション値を 設定解除 するオプションはありません。オプションの値を変更するには、目的の値を指定して !set コマンドを再度実行します。

例:

user#> !options

+-----------------------+-------------------+
| Name                  | Value             |
|-----------------------+-------------------|
 ...
| rowset_size           | 1000              |
 ...
+-----------------------+-------------------+

user#> !set rowset_size=500

user#> !options

+-----------------------+-------------------+
| Name                  | Value             |
|-----------------------+-------------------|
 ...
| rowset_size           | 500               |
 ...
+-----------------------+-------------------+

user#> !set rowset_size=1000

user#> !options

+-----------------------+-------------------+
| Name                  | Value             |
|-----------------------+-------------------|
 ...
| rowset_size           | 1000              |
 ...
+-----------------------+-------------------+
Copy

重要

オプションとその値の間にスペースを入れることは 許可されません。一部のオプションは、定義済みの値セットをサポートしています。指定された値がサポートされていない場合、SnowSQL はエラーを返します。新しいオプションを作成することはできません。

設定可能なすべての構成オプションのリストについては、 !options コマンドを使用してください。

!source!load

ファイルから SQL を実行します。ローカルファイルまたは URL から SQL を実行できます。

例:

user#> !source example.sql

user#> !load /tmp/scripts/example.sql

user#> !load http://www.example.com/sql_text.sql
Copy

!spool

このコマンドは、次の2つの方法で実行できます。

  • スプールを有効化し、後続のすべてのステートメント/クエリの結果を指定されたファイルに書き込みます。

    !spool <ファイル名>

  • 結果のスプールをオフにします(有効化されている場合)。

    !spool off

例:

user#> select 1 num;

+-----+
| NUM |
|-----|
|   1 |
+-----+

user#> !spool /tmp/spool_example

user#> select 2 num;

+---+
| 2 |
|---|
| 2 |
+---+

user#> !spool off

user#> select 3 num;

+---+
| 3 |
|---|
| 3 |
+---+

user#> !exit

Goodbye!

$ cat /tmp/spool_example

+---+
| 2 |
|---|
| 2 |
+---+
Copy

最初に !set output_format=<フォーマット> コマンドを実行して、出力形式を変更できます。このオプションは次の値をサポートしています。

  • expanded

  • fancy_grid

  • grid

  • html

  • latex

  • latex_booktabs

  • mediawiki

  • orgtbl

  • pipe

  • plain

  • psql

  • rst

  • simple

  • tsv

推奨値: psqlfancy_grid、または grid

例えば、CSV 形式で出力するには、

user#> !set output_format=csv

user#> !spool /tmp/spool_example
Copy

!system

シェルコマンドを実行します。

!system <コマンド>

次の例では、ユーザーのホームディレクトリで ls コマンドを実行します。

user#> !system ls ~
Copy

!variables!vars

現在の変数をすべてリストします。現在定義されている各 <変数名>=<変数値> ペアを返します。

変数が割り当てられると、削除することはできませんが、値なしで変数名を指定することにより、その値を削除できます。例:

user#> !set variable_substitution=true

user#> !define SnowAlpha=_ALPHA_

user#> !variables

+------------------+---------+
| Name             | Value   |
|------------------+---------|
| snowalpha        | _ALPHA_ |
+------------------+---------+

user#> !define SnowAlpha

user#> !variables

+------------------+-------+
| Name             | Value |
|------------------+-------|
| snowalpha        |       |
+------------------+-------+

user#> !define snowalpha=456

user#> select &snowalpha;

+-----+
| 456 |
|-----|
| 456 |
+-----+
Copy

変数の設定の詳細については、(このトピックの)「変数の使用」をご参照ください。

トラブルシューティング

エラーメッセージ: Variable is not defined

原因:

SnowSQL でコマンドを実行しているときにこのエラーメッセージが表示される場合は、 CREATE FUNCTION コマンド内のアンパサンド(&)が原因である可能性があります。(アンパサンドは SnowSQL 変数置換文字です。)たとえば、 SnowSQL で次のコマンドを実行すると、このエラーが発生します。

create function mask_bits(...)
    ...
    as
    $$
    var masked = (x & y);
    ...
    $$;
Copy

エラーは、関数が呼び出されたときではなく、関数が作成されたときに発生します。

解決策:

SnowSQL で変数置換を使用する予定がない場合は、次のコマンドを実行して変数置換を明示的に無効にできます。

!set variable_substitution=false;
Copy

変数置換の詳細については、 変数の使用 をご参照ください。