使用 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 定义变量：

在连接之前定义变量（配置文件）
连接时定义变量（-D 或 --variable 命令行标志）
在会话中定义变量（!define 命令）

在连接之前定义变量（配置文件）¶

要在连接到 Snowflake 之前定义变量，请在 config 配置文件中添加变量：

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

Linux/macOS:

~/.snowsql/

Windows:

%USERPROFILE%\.snowsql\

备注

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

在 [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

在上面的例子中：

-D 将名为 tablename 的变量设置为 CENUSTRACKONE。
--variable 将名为 db_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

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

&&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 包含一组内置变量，这些变量返回有关在当前用户会话中执行的语句的元数据。

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

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

运行批处理脚本¶

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

使用连接参数（连接到 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

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 之前）。
使用 -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

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 之前）。
使用 -o 或 --options 连接参数（连接到 Snowflake 时）。
执行 !set 命令（在 Snowflake 会话的命令行上）。

备注

如果使用连接参数或直接在命令行上更改提示，则更改仅适用于当前会话。若要在将来的会话中保留更改，请在配置文件中设置相应选项。

支持的令牌¶

SnowSQL 支持以下对象类型作为令牌：

user
account
role
database
schema
warehouse

默认提示¶

SnowSQL 的默认提示使用以下令牌和结构：

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

Copy

例如：

jdoe#DATALOAD@BOOKS_DB.PUBLIC>

Copy

提示示例¶

继续使用上面的示例，在命令行中执行的以下 !set 命令会添加角色令牌，并将令牌顺序更改为 user 和 role、database 和 schema，然后是 warehouse。它还会将每个令牌的分隔符更改为句点 (.)，并将令牌设置为使用不同的颜色：

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

Copy

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

断开与 Snowflake 的连接并停止 SnowSQL¶

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

离开单个连接（即会话）而不停止 SnowSQL。
退出 SnowSQL，这也会自动终止所有连接。

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

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

离开代码¶

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

0:: 一切正常。
1:: 客户端出了点问题。
2:: 命令行实参出了点问题。
3:: SnowSQL 无法联系服务器。
4:: SnowSQL 无法与服务器正常通信。
5:: 已设置 exit_on_error 配置选项，并且 SnowSQL 因出错而离开。

默认按键绑定¶

Tab: 接受当前的自动补全建议。
CTRL + d: 退出/停止 SnowSQL。

命令参考¶

`!abort`¶

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

例如：

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

Copy

`!connect`¶

SnowSQL 通过 !connect <connection_name> 支持多个会话（即连接）：

与 connection_name 关联的连接参数/选项存储在 SnowSQL 配置文件的相应 [connections.<connection_name>] 部分中。
如果未在 [connections.<connection_name>] 部分中指定参数/选项，则未指定的参数将默认为 [connections] 下的参数。

连接时，连接将添加到连接堆栈中，而离开时将返回到以前的连接。退出将离开您的所有连接并退出，无论您有多少连接。

例如：

配置文件：

[connections.my_example_connection]
...

Copy

命令行：

user#> !connect my_example_connection

Copy

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

Copy

`!queries`¶

列出与指定筛选器匹配的所有查询。默认筛选器是 session 和 amount=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` （也可以按 `CTRL` + `d`）¶

断开所有连接并离开 SnowSQL。

`!rehash`¶

重新同步自动补全令牌。

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

`!result`¶

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

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

例如：

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

Copy

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

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`¶

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

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

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

Copy

您可以通过首先运行 !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

Copy

`!system`¶

执行 shell 命令。

!system <command>

以下示例在用户的主目录中运行 ls 命令：

user#> !system ls ~

Copy

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

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

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

使用 SnowSQL¶

执行命令¶

使用变量¶

定义变量¶

在连接之前定义变量（配置文件）¶

连接时定义变量（-D 或 --variable 命令行标志）¶

在会话中定义变量（!define 命令）¶

启用变量替换¶

替换会话中的变量¶

列出变量¶

使用内置变量¶

使用自动补全¶

查看命令行历史记录¶

历史记录文件¶

运行批处理脚本¶

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

在会话中运行（!source 或 !load 命令）¶

导出数据¶

更改 SnowSQL 提示格式¶

支持的令牌¶

默认提示¶

提示示例¶

断开与 Snowflake 的连接并停止 SnowSQL¶

离开代码¶

默认按键绑定¶

命令参考¶

!abort¶

!connect¶

!define¶

!edit¶

!exit、!disconnect¶

!help、!helps、!h¶

!options、!opts¶

!pause¶

!print¶

!queries¶

!quit、!q （也可以按 CTRL + d）¶

!rehash¶

!result¶

!set¶

!source、!load¶

!spool¶

!system¶

!variables、!vars¶

故障排除¶

错误消息：Variable is not defined¶

连接时定义变量（`-D` 或 `--variable` 命令行标志）¶

在会话中定义变量（`!define` 命令）¶

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

在会话中运行（`!source` 或 `!load` 命令）¶

`!abort`¶

`!connect`¶

`!define`¶

`!edit`¶

`!exit`、`!disconnect`¶

`!help`、`!helps`、`!h`¶

`!options`、`!opts`¶

`!pause`¶

`!print`¶

`!queries`¶

`!quit`、`!q` （也可以按 `CTRL` + `d`）¶

`!rehash`¶

`!result`¶

`!set`¶

`!source`、`!load`¶

`!spool`¶

`!system`¶

`!variables`、`!vars`¶

错误消息：`Variable is not defined`¶