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

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

変数の使用

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

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

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

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

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

加えて、セッション内の変数を置換でき、Snowflakeは組み込み変数も提供します。

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

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

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

    Linux/macOS

    ~/.snowsql/

    Windows

    %USERPROFILE%\.snowsql\

    注釈

    SnowSQL の起動時に --config <path> 接続パラメーターを含めることにより、別の場所を指定できます。

  2. [variables] セクションに変数を追加します。

    [variables]
    <variable_name>=<variable_value>
    

    条件:

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

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

    例:

    [variables]
    tablename=CENUSTRACKONE
    

接続中の定義(-D または --variable 接続パラメーター)

Snowflakeへの接続中に変数を定義するには、ターミナルコマンドラインで、 <variable_name>=<variable_value> の形式で、変数名と値が後に続く -D または --variable 接続パラメーターを指定します。

例:

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

上記の例では、

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

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

セッションでの定義(!define コマンド)

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

例:

user#> !define tablename=CENUSTRACKONE

セッションでの置換

variable_substitution 構成オプションが有効化されている場合、 &<variable> 構文を使用して、定義された変数を SnowSQL で参照し、クエリに値を置換できます。変数参照は大文字と小文字を区別しません。

例:

user#> !define snowshell=bash

user#> !set variable_substitution=true

user#> select '&snowshell';

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

variable_substitution が無効化されていると、変数の置換は行われません。

例:

user#> !define snowshell=bash

user#> !set variable_substitution=false

user#> select '&snowshell';

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

加えて、 variable_substitution オプションが有効化されており、変数が定義されていない場合、SnowSQL はエラーを表示します。

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

例:

user#> !define snowshell=bash

user#> !set variable_substitution=true

select '&{snowshell}_shell';

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

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

&&<variable>

例:

user#> !set variable_substitution=true

user#> select '&notsubstitution';

Variable notsubstitution is not defined

user#> select '&&notsubstitution';

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

注釈

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

組み込み変数

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

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

user#> !set variable_substitution=true

user#> select * from a;

user#> select '&__sfqid';

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

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

さまざまな SQL 関数、テーブル名、および変数は SnowSQL に格納され、インタラクティブモードでオートコンプリートされます。オートコンプリートの候補を選択するには、 [タブ] キーを押します。別の提案を選択するには、 [上矢印] および [下矢印] キーを使用して目的のオプションを強調表示し、 [タブ] を押します。

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

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

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

履歴ファイル

The interactive command line history file is named history and is located in ~/.snowsql/history.

バッチスクリプトの実行

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

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

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

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

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

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

例:

snowsql -a xy12345 -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

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

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

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

例:

user#> !source example.sql

データのエクスポート

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

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

SnowSQL プロンプト形式の変更

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

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

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

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

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

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

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

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

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

注釈

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

サポートされたトークン

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

  • user

  • account

  • role

  • database

  • schema

  • warehouse

デフォルトプロンプト

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

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

例:

marie#DATALOAD@DEMO_DB.PUBLIC>

プロンプトの例

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

marie#DATALOAD@DEMO_DB.PUBLIC> !set prompt_format=[#FF0000][user].[#00FF00][database].[schema].[#0000FF][warehouse]>

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

SnowSQL prompt format

Snowflake からの SnowSQL 切断と停止

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

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

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

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

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

終了コード

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

0

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

1

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

2

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

3

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

4

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

5

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

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

[タブ]

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

[CTRL]-d

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

コマンドリファレンス

!abort

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

例:

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

!connect

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

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

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

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

例:

構成ファイル:

[connections.my_example_connection]
...

コマンドライン:

user#> !connect my_example_connection

!define

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

!define <variable_name>=<variable_value>

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

0-9a-zA-Z\_

!edit

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

注釈

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

!exit , !disconnect

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

!help , !helps , !h

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

!options , !opts

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

注釈

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

!pause

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

!print

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

例:

user#> !print Include This Text

!queries

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

例:

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

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

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

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

    !queries warehouse=mywh
    

このコマンドは、返されたクエリ 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 |
+---+

!quit!q[CTRL]-d も)

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

!rehash

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

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

!result

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

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

例:

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

!set

<option>=<value> 形式を使用して、指定された 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              |
 ...
+-----------------------+-------------------+

重要

オプションとその値の間にスペースを入れることは 許可されません。一部のオプションは、定義済みの値セットをサポートしています。指定された値がサポートされていない場合、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

!spool

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

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

    !spool <file_name>

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

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

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

  • custom

  • 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

!system

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

!system <command>

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

user#> !system ls ~

!variables , !vars

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

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

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

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

トラブルシューティング

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

原因

場合によっては、 CREATE FUNCTION コマンド内でアンパサンド文字(変数置換文字)を使用することでこれが発生する可能性があります。

create function mask_bits(...)
    ...
    as
    $$
    var masked = (x & y);
    ...
    $$;
解決策

この問題については、あらゆる状況で機能する解決策はありません。ただし、変数置換を使用しない場合は、無効にして問題を回避できます。変数置換をオフにするには、次のコマンドを実行します。

!set variable_substitution=false;

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