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に接続する前に変数を定義するには、 config
構成ファイルに変数を追加します。
テキストエディターで、 SnowSQL構成ファイル (名前
config
)を開きます。ファイルのデフォルトの場所は次のとおりです。- Linux/macOS:
~/.snowsql/
- Windows:
%USERPROFILE%\.snowsql\
注釈
SnowSQL の起動時に、
--config path
コマンドラインフラグを指定すると、デフォルトの場所を変更できます。
[variables]
セクションで、使用する予定の変数を定義します。[variables] <variable_name>=<variable_value>
条件:
variable_name
は、変数の名前を表す英数字の文字列(大文字と小文字を区別しない)です。variable_value
は、変数の値を表す文字列です。必要に応じて、文字列を一重引用符または二重引用符で囲むことができます。
例:
[variables] tablename=CENUSTRACKONE
接続中の変数の定義(-D
または --variable
コマンドラインフラグ)¶
Snowflakeへの接続中に変数を定義するには、ターミナルコマンドラインで -D
または --variable
コマンドラインフラグを指定します。このフラグの引数には、変数の名前と値を variable_name=variable_value
の形式で指定します。
例:
- 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
変数置換の有効化¶
SnowSQL が変数の値を置き換えることができるようにするには、次のいずれかの方法で variable_substitution
構成オプションを true
に設定する必要があります。
SnowSQL を開始する前にこのオプションを設定するには、テキストエディターで SnowSQL 構成ファイル を開き、
[options]
セクションでこのオプションを設定します。[options] variable_substitution = True
SnowSQL の起動時にこのオプションを設定するには、
-o
コマンドラインフラグを指定します。$ snowsql ... -o variable_substitution=true
SnowSQL セッションでこのオプションを設定するには、セッションで
!set
コマンドを実行します。user#> !set variable_substitution=true
注釈
現在、
variable_substitution
オプションなどのオプション値を 設定解除 するオプションはありません。変数置換を無効にする必要がある場合は、コマンド!set variable_substitution=false
を実行します。
セッションでの変数の置換¶
変数置換 を有効にした後に、 SQL ステートメントで変数を使用できます。
ステートメントで変数を使用するには、 &variable_name
構文を使用します。変数名では大文字と小文字が区別されないことに注意してください。例:
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 | +--------------+
定義されていない変数を参照すると、 SnowSQL はエラーを表示します。例:
select '&z'; Variable z is not defined
変数とテキストを組み合わせるには、変数参照を中括弧で囲みます。例:
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 '¬substitution'; Variable notsubstitution is not defined user#> select '&¬substitution'; +--------------------+ | '&NOTSUBSTITUTION' | |--------------------| | ¬substitution | +--------------------+
変数のリスト¶
変数を一覧表示するには、セッションで !variables
または !vars
コマンドを実行します。
user#> !variables +-----------+-------+ | Name | Value | |-----------+-------| | snowshell | bash | +-----------+-------+
組み込み変数の使用¶
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 に格納され、インタラクティブモードでオートコンプリートされます。オートコンプリートの候補を選択するには、 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
すべての接続パラメーターの詳細については、 接続パラメーターリファレンス をご参照ください。
セッションでの実行(!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トークンを [token]
(例: [user]
または [warehouse]
)の形式で使用して、プロンプトの外観と構造を制御できます。
トークンは、今後のプロンプトに影響します。各トークンの順序、色、およびトークン間の区切り文字を変更できます。
すべての構成オプションと同様に、次のいずれかの方法を使用してプロンプトを設定できます。
構成ファイル内(Snowflakeに接続する前)。
(Snowflakeへの接続中に)
-o
または--options
接続パラメーターを使用します。!set
コマンドの実行(Snowflakeセッションのコマンドラインで)。
注釈
接続パラメーターを使用して、またはコマンドラインで直接プロンプトを変更した場合、変更は現在のセッションにのみ適用されます。将来のセッションで変更を保持するには、構成ファイルでオプションを設定します。
サポートされているトークン¶
SnowSQL では、次のオブジェクトタイプをトークンとしてサポートします。
user
account
role
database
schema
warehouse
デフォルトのプロンプト¶
SnowSQL のデフォルトプロンプトは、次のトークンと構造を使用します。
[user]#[warehouse]@[database].[schema]>
例:
jdoe#DATALOAD@BOOKS_DB.PUBLIC>
プロンプトの例¶
上記の例に続けて、コマンドラインで実行された次の !set
コマンドは、ロールトークンを追加し、トークンの順序を user
と role
、 database
と schema
、そして warehouse
に変更します。また、各トークンの区切り文字をピリオド(.
)に変更し、異なる色を使用するようにトークンを設定します。
jdoe#DATALOAD@BOOKS_DB.PUBLIC> !set prompt_format=[#FF0000][user].[role].[#00FF00][database].[schema].[#0000FF][warehouse]>
この例では、セッションに対して次のプロンプトが表示されます。
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;
!connect
¶
SnowSQL は !connect <接続名>
との複数のセッション(接続)をサポートします。
connection_name
に関連付けられた接続パラメーター/オプションは、SnowSQL 構成ファイルの対応する[connections.<接続名>]
セクションに格納されます。パラメーター/オプションが
[connections.<接続名>]
セクションで指定されていない場合、指定されていないパラメーターはデフォルトで[connections]
下のパラメーターになります。
接続すると、接続が接続スタックに追加され、終了すると以前の接続に戻ります。終了すると、接続の数に関係なく、すべての接続が終了します。
例:
構成ファイル:
[connections.my_example_connection] ...
コマンドライン:
user#> !connect my_example_connection
!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
!queries
¶
指定したフィルターに一致するすべてのクエリをリストします。デフォルトのフィルターは session
と amount=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
(kbd:CTRL + d も可)。¶
すべての接続をドロップし、SnowSQL を終了します。
!rehash
¶
オートコンプリートトークンを再同期します。
通常の使用では、オートコンプリートトークンを再同期する必要はありません。ただし、特定のシナリオ(例えば、別のセッションで新しいユーザー定義関数が作成される場合)では、サーバー側のトークンを強制的に更新することが役に立つ場合があります。
!result
¶
完了したクエリの結果を返します(クエリ ID で指定)。クエリ IDs は、ウェブインターフェイスの History ページまたは !queries
コマンドを使用して取得できます。
クエリがまだ実行中の場合、コマンドはクエリが完了するまで待機します。
例:
user#> !result 77589bd1-bcbf-4ec8-9ebc-6c949b00614d;
!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 | ... +-----------------------+-------------------+
重要
オプションとその値の間にスペースを入れることは 許可されません。一部のオプションは、定義済みの値セットをサポートしています。指定された値がサポートされていない場合、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 <ファイル名>
結果のスプールをオフにします(有効化されている場合)。
!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=<フォーマット>
コマンドを実行して、出力形式を変更できます。このオプションは次の値をサポートしています。
expanded
fancy_grid
grid
html
latex
latex_booktabs
mediawiki
orgtbl
pipe
plain
psql
rst
simple
tsv
推奨値: psql
、 fancy_grid
、または grid
例えば、CSV 形式で出力するには、
user#> !set output_format=csv user#> !spool /tmp/spool_example
!system
¶
シェルコマンドを実行します。
!system <コマンド>
次の例では、ユーザーのホームディレクトリで ls
コマンドを実行します。
user#> !system ls ~
!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 | +-----+
変数の設定の詳細については、(このトピックの)「変数の使用」をご参照ください。
トラブルシューティング¶
エラーメッセージ: Variable is not defined
¶
- 原因:
SnowSQL でコマンドを実行しているときにこのエラーメッセージが表示される場合は、 CREATE FUNCTION コマンド内のアンパサンド(
&
)が原因である可能性があります。(アンパサンドは SnowSQL 変数置換文字です。)たとえば、 SnowSQL で次のコマンドを実行すると、このエラーが発生します。create function mask_bits(...) ... as $$ var masked = (x & y); ... $$;
エラーは、関数が呼び出されたときではなく、関数が作成されたときに発生します。
- 解決策:
SnowSQL で変数置換を使用する予定がない場合は、次のコマンドを実行して変数置換を明示的に無効にできます。
!set variable_substitution=false;
変数置換の詳細については、 変数の使用 をご参照ください。