使用 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 配置文件中添加变量：

  1. 在文本编辑器中，打开 SnowSQL 配置文件 （名为 config）。该文件的默认位置是：

    Linux/macOS:

    ~/.snowsql/

    Windows:

    %USERPROFILE%\.snowsql\

    备注

    启动 SnowSQL 时，可以指定 --config path 命令行标志来更改默认位置。

  1. 在 [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   |
+--------------+

要在不使用替换的情况下使用 & 号，请使用第二个 & 号将 & 号进行转义：

&&variable

例如：

user#> !set variable_substitution=true

user#> select '&notsubstitution';

Variable notsubstitution is not defined

user#> select '&&notsubstitution';

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

列出变量

要列出变量，请在会话中执行 !variables 或 !vars 命令：

user#> !variables

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

使用内置变量

SnowSQL 包含一组内置变量，这些变量返回有关在当前用户会话中执行的语句的元数据。

这些变量名称中的每一个都以两个下划线字符（“__”）开头。

__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。

Viewing your command-line history

Your recent command-line history can be recalled by using the ↑ key. Press the key repeatedly to scroll through the buffer.

历史记录文件

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

运行批处理脚本

您可以通过两种方式运行批处理脚本：

  • 使用连接参数（连接到 Snowflake 时）

  • 执行命令（在 Snowflake 会话的命令行上）

连接时运行（-f 连接参数）

若要在连接到 Snowflake 时执行 SQL 脚本，请使用 -f <input_filename> 连接参数。

可以使用 -o output_file=<output_filename> 指定脚本的输出文件。此外，还可以使用 -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 之前）。

  • 使用 -o 或 --options 连接参数（连接到 Snowflake 时）。

  • 执行 !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 之前）。

  • 使用 -o 或 --options 连接参数（连接到 Snowflake 时）。

  • 执行 !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]>

此示例将导致会话中出现以下提示：

SnowSQL 提示格式

断开与 Snowflake 的连接并停止 SnowSQL

SnowSQL 为以下操作提供单独的命令：

  • 离开单个连接（即会话）而不停止 SnowSQL。

  • 退出 SnowSQL，这也会自动终止所有连接。

要离开连接/会话，请使用 !exit 命令或其别名 !disconnect。然后，如果在 SnowSQL config 文件中定义了多个连接，则可以使用 !connect <connection_name> 重新连接。请注意，如果只打开了一个连接，则 !exit 命令也会退出/停止 SnowSQL。

要离开所有连接，然后退出/停止 SnowSQL，请使用 !quit 命令或其别名 !q。您也可以在键盘上键入 CTRL + d。

离开代码

SnowSQL 退出/离开时会返回几种可能的离开代码：

0:

一切正常。

1:

客户端出了点问题。

2:

Something went wrong with the command-line arguments.

3:

SnowSQL 无法联系服务器。

4:

SnowSQL 无法与服务器正常通信。

5:

已设置 exit_on_error 配置选项，并且 SnowSQL 因出错而离开。

默认按键绑定

Tab

接受当前的自动补全建议。

CTRL + d

退出/停止 SnowSQL。

命令参考

!abort

中止查询（通过查询 ID 来指定）。可以从 Web 界面中的 History History 选项卡 页面获取查询 ID。

例如：

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

暂停正在运行的查询。按回车键继续。

!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 （也可以按 CTRL + d）

断开所有连接并离开 SnowSQL。

!rehash

重新同步自动补全令牌。

正常使用并不需要重新同步自动补全令牌。但是，在某些情况下（例如，如果在另一个会话中创建了新的用户定义函数），强制更新服务器端令牌可能很有用。

!result

返回已完成的查询（由查询 ID 指定）的结果。可以从 Web 界面中的 History History 选项卡 页面或使用 !queries 命令获取查询 IDs。

如果查询仍在运行，此命令将等待查询完成。

例如：

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

可以通过两种方式执行此命令：

  • 启用假脱机，并将所有后续语句/查询的结果写入指定文件：

    !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> 命令来更改输出格式。选项支持以下值：

  • 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

执行 shell 命令。

!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

原因:

如果在 SnowSQL 中运行命令时看到此错误消息，这可能是由 CREATE FUNCTION 命令中的 & 号造成的。（& 号是 SnowSQL 变量替换字符。）例如，在 SnowSQL 中执行以下命令会导致此错误：

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

此错误发生在创建函数时，而不是调用函数时。

解决方案:

如果不打算在 SnowSQL 中使用变量替换，可以通过执行以下命令来显式禁用变量替换：

!set variable_substitution=false;

有关变量替换的更多信息，请参阅 使用变量。