Snowflake CLI の基本操作を試してみる

モダンデータスタック(MDS)

#Snowflake

安原朋紀

2025.03.22

はじめに

Snowflake CLI は主に Snowflake によるアプリケーション（Streamlit, Snowpark Container Services など）開発で使用できる CLI ツールです。Snowflake CLI でもクエリの実行や基本的なオブジェクトの作成ができるので、関連する基礎的な使い方としてをまとめておきたく記事としました。

注意点として Snowpark 周りは本記事では扱いません。

前提条件

以下の環境で検証しています。

Ubuntu 24.04LTS（WSL2上で動作）
Snowflake CLI version: 3.4.1

インストール

本記事の環境へのインストール手順は以下にまとまっているので、こちらに沿って進めました。

インストール確認

$ snow --version
Snowflake CLI version: 3.4.1

接続の管理

はじめに Snowflake アカウントへの接続情報を定義します。接続の管理には snow connection add コマンドを使用できます。

コマンドを実行するとアカウントやユーザー名など接続に必要な情報の入力を求められます。

$ snow connection add
Enter connection name: my_connection
省略
Wrote new connection my_default_connection to /home/<ユーザー名>/.config/snowflake/config.toml

入力内容をもとに構成ファイルが更新されます。接続に関する情報はconfig.tomlファイルに記載されます。特に何も設定していない場合、Linux では~/.config/snowflake/config.toml に配置されています。

接続設定のテスト

接続設定後は snow connection test でテスト可能です。

$ snow connection test -c my_connection
+----------------------------------------------------------+
| key             | value                                  |
|-----------------+----------------------------------------|
| Connection name | my_connection                          |
| Status          | OK                                     |
| Host            | <組織>-<アカウント>.snowflakecomputing.com |
| Account         | <組織>-<アカウント>                     |
| User            | <ユーザー名>                            |
| Role            | <ロール>　                              |
| Database        | not set                                |
| Warehouse       | COMPUTE_WH                             |
+----------------------------------------------------------+

ドキュメントからの引用ですが、任意の構成ファイルを指定する場合は、以下のコマンドで指定できます。

snow --config-file="my_config.toml" connection test

デフォルトの接続設定を指定

接続は複数作成できるので、以下のコマンドでデフォルトとして使用する構成を指定できます。

snow connection set-default my_connection

環境変数による構成値のオーバーライド

環境変数を使用し、以下のように構成ファイルの設定値をオーバーライドすることも可能です。

SNOWFLAKE_<config-section>_<variable>=<value>

先の手順で構成ファイルには以下のような構成が追加されていたとします。

config.toml

[connections.my_connection]
account = "<組織>-<アカウント>"
user = "<ユーザー>"
password = "XXXXX"
role = "ACCOUNTADMIN"

この接続の変数として「ロール」をオーバーライドする場合は以下の環境変数を定義します。

export SNOWFLAKE_CONNECTIONS_MY_CONNECTION_ROLE="SYSADMIN"

この上でクエリを実行すると変数が上書きされていることを確認できます。

# 構成に基づくロール
$ snow sql --query "select current_role()"
select current_role()
+----------------+
| CURRENT_ROLE() |
|----------------|
| ACCOUNTADMIN   |
+----------------+

# 環境変数を設定
$ export SNOWFLAKE_CONNECTIONS_MY_CONNECTION_ROLE="SYSADMIN"

# 構成のロールが上書きされている
$ snow sql --query "select current_role()"
select current_role()
+----------------+
| CURRENT_ROLE() |
|----------------|
| SYSADMIN       |
+----------------+

基本的なクエリ

snow sql

Snowflake CLI でアドホックなクエリの実行には snow sql を使用できます。

以下のようにクエリを実行できます。

$ snow sql --query "select current_date()"
select current_date()
+----------------+
| CURRENT_DATE() |
|----------------|
| 2025-03-20     |
+----------------+

-fでファイルを指定できます。

# sqlファイルを作成
$ echo "select current_timestamp();" > timestamp.sql

# -fでファイルのパスを指定
$ snow sql -f timestamp.sql
select current_timestamp();
+----------------------------------+
| CURRENT_TIMESTAMP()              |
|----------------------------------|
| 2025-03-20 22:05:34.313000-07:00 |
+----------------------------------+

Snowflake オブジェクトの管理

サポートされるオブジェクトについてはsnow object コマンドで管理（作成・一覧・表示・削除）できます。

サポートされるオブジェクトと注意点

Snowflake CLI によるオブジェクトの作成には snow object create を使用します。サポートされるオブジェクトはこちらに記載があります。

2025年3月時点の注意点として、すべてのオブジェクトがこのコマンドで管理可能ではありません。また、ストリームなどサポート一覧に記載がある一部のオブジェクトでは、具体的なコマンドのリファレンスがなく、詳細なパラメータの設定方法がドキュメントからは把握できません。
この点はサポートに問い合わせてみたところ、一部オブジェクトはドキュメント作成中のステータスのため、現時点では snow sql の使用を推奨するとのことでした。
他にもサポートされるオブジェクトであっても、比較的新しいパラメータはサポートしていないようで、この点もドキュメントからは確認し辛いです。

上記より、snow object create を使用する際は、まずは代表的なオブジェクト管理にこのコマンドを試してみるのがよいと思います。

ここでは以下のオブジェクトを作成してみます。

データベース
スキーマ
テーブル

代表的なオブジェクトの作成：データベース

データベース作成時に指定可能な属性は以下に記載があります。

以下のように作成できます。

$ snow object create database name=my_example_db comment="Snowflake CLI から作成"
Database MY_EXAMPLE_DB successfully created.

オプションを指定することでオブジェクトの置き換え（replace）やウェアハウスを指定することも可能です。

$ snow object create database name=my_example_db_admin comment="Snowflake CLI から作成" --role accountadmin
Database MY_EXAMPLE_DB successfully created.

属性値は Json 形式での指定も可能です。

# データベースの設定ファイルを作成
echo '{"name":"my_db", "comment":"Created with Snowflake CLI"}' > db_config.json

# 設定ファイルを指定し作成
$ snow object create database --json "$(cat db_config.json)"
Database MY_DB successfully created.

代表的なオブジェクトの作成：スキーマ

スキーマを作成する際には、どのデータベースにスキーマを作成するかを指定する必要があります。これは、接続設定ファイル（config.toml）でデータベースを定義しておくか、コマンド実行時に--databaseオプションを使用することで行います。

ここでは設定ファイルにデータベースの指定はないので、上記の手順で作成したデータベース内にスキーマを作成します。

# データベースを指定し作成
$ snow object create schema name=my_example_schema --database my_example_db comment="Snowflake CLI から作成"
Schema MY_EXAMPLE_SCHEMA successfully created.

# コマンドとconfig.toml両方にデータベースの指定が無い場合エラー
$  snow object create schema name=my_example_schema comment="Snowflake CLI から作成"
╭─ Error ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Database not defined in connection. Please try again with `--database` flag.                                                                                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

代表的なオブジェクトの作成：テーブル

テーブルを作成する際は、どのデータベース/スキーマに作成するかを指定する必要があります。テーブル定義についても、属性ペアのリスト形式か Json 形式で指定できます。

table.json というファイルに以下のようなテーブル定義を記述します。

touch example_table.json

example_table.json

{
    "name": "example_table",
    "columns": [
        {
            "name": "product_id",
            "datatype": "NUMBER",
            "nullable": false
        },
        {
            "name": "product_name",
            "datatype": "VARCHAR"
        }
    ],
    "comment": "example table"
}

この状態で以下のコマンドを実行するとオブジェクトを定義できます。

$ snow object create table --json "$(cat example_table.json)" --database my_example_db --schema my_example_schema
Table EXAMPLE_TABLE successfully created.

注意点として Json で構成をまとめる場合、対象のオブジェクト属性はすべて Jsonにまとめる必要があります。一部の属性（ここではcomment）をパラメータで指定すると以下のようなエラーとなります。

$ snow object create table --json "$(cat example_table.json)"  comment="example table"
Usage: snow object create [OPTIONS] OBJECT_TYPE [OBJECT_ATTRIBUTES]...
Try 'snow object create --help' for help.
╭─ Error ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Parameters 'object_attributes' and '--json' are incompatible and cannot be used simultaneously.                                                                        │
╰────────────────────────────────────────────────────────────────────────────────────────────────────

テーブル作成時に完全修飾名を使用するとどうなるか試してみたのですが、エラーとなりました。そのため snow object create を使用し、明示的にデータベーススキーマを指定したい場合は—database,—schema の指定が必要なようです。

touch another_example_table.json

another_example_table.json

{
    "name": "my_example_db.my_example_schema.another_example_table",
    "columns": [
        {
            "name": "product_id",
            "datatype": "NUMBER",
            "nullable": false
        },
        {
            "name": "product_name",
            "datatype": "VARCHAR"
        }
    ],
    "comment": "Another example table"
}

# データベース・スキーマの指定が必要
$ snow object create table --json "$(cat another_example_table.json)" 
╭─ Error ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Database not defined in connection. Please try again with `--database` flag.                                                                                                                                           │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

# Json ファイルで完全修飾名は指定できない
$  snow object create table --json "$(cat another_example_table.json)" --database my_example_db --schema my_example_schema
000400: 400: HTTP 400: Bad Request
Traceback (most recent call last):
  File "snowflake/connector/network.py", line 914, in _request_exec_wrapper
  File "snowflake/connector/network.py", line 1191, in _request_exec
  File "snowflake/connector/network.py", line 1128, in _request_exec
snowflake.connector.network.RetryRequest: 000400: 400: HTTP 400: Bad Request
╭─ Error ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ 400 bad request: Incorrect object definition (arguments misspelled or malformatted).                                                                                                                                   │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

上記でオブジェクト名を完全修飾名としない場合、実行できました。

snow sql での変数利用

Snowflake CLI でも変数を使用できます。

この場合 snow sql で変数を使用でき、以下に記載があるようにクエリ内に<% 変数名 %>とすることで変数を使用できます。

以下のファイルを作成します。

variable_test.sql

USE ROLE SYSADMIN;
CREATE OR ALTER DATABASE <% environment %>_my_db;
CREATE OR ALTER SCHEMA  <% environment %>_my_sch;

-Dで変数の値を指定し、コマンドを実行できます。

$ snow sql -f variable_test.sql -D "environment=dev"
USE ROLE SYSADMIN;
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+

CREATE OR ALTER DATABASE dev_my_db;
+------------------------------------------+
| status                                   |
|------------------------------------------|
| Database DEV_MY_DB successfully created. |
+------------------------------------------+

CREATE OR ALTER SCHEMA  dev_my_sch;
+-----------------------------------------+
| status                                  |
|-----------------------------------------|
| Schema DEV_MY_SCH successfully created. |
+-----------------------------------------+

プロジェクトファイルでの変数定義

特に Streamlit や Snowpark アプリケーションを開発する際に使用されるプロジェクト定義ファイル（snowflake.yml）を使用してsnow sql などのコマンドが使用できる変数を定義することもできます。

例として現在の操作ディレクトリで以下のプロジェクトファイルを作成します。

snowflake.yml

definition_version: '2'

env:
  name: "my_project"

envはプロジェクトのデフォルト環境仕様の一覧として定義されるプロパティです。ドット表記を使用して、定義されたオブジェクトの属性にアクセスできます。my_projectには<% ctx.env.name %>としてアクセスできます。

この表記は snow sql でも使用できます。以下のような SQL ファイルを作成します。

def_file_variable_test.sql

USE ROLE SYSADMIN;
CREATE OR ALTER DATABASE <% ctx.env.name %>_db;
CREATE OR ALTER SCHEMA  <% ctx.env.name %>_sch;

snow sql でファイルを実行すると構成ファイルのプロパティを呼び出すことができます。

$ snow sql -f def_file_variable_test.sql
USE ROLE SYSADMIN;
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+

CREATE OR ALTER DATABASE my_project_db;
+----------------------------------------------+
| status                                       |
|----------------------------------------------|
| Database MY_PROJECT_DB successfully created. |
+----------------------------------------------+

CREATE OR ALTER SCHEMA  my_project_sch;
+---------------------------------------------+
| status                                      |
|---------------------------------------------|
| Schema MY_PROJECT_SCH successfully created. |
+---------------------------------------------+

snowflake.ymlのenvセクションで定義された変数は環境変数でオーバーライドできます。注意点として変数は大文字小文字が区別されます。

# name: "my_project"をオーバーライド
export name="other"

# 上書きされた変数でSQLファイルが実行される
$ snow sql -f def_file_variable_test.sql
USE ROLE SYSADMIN;
+----------------------------------+
| status                           |
|----------------------------------|
| Statement executed successfully. |
+----------------------------------+

CREATE OR ALTER DATABASE other_db;
+-----------------------------------------+
| status                                  |
|-----------------------------------------|
| Database OTHER_DB successfully created. |
+-----------------------------------------+

CREATE OR ALTER SCHEMA  other_sch;
+----------------------------------------+
| status                                 |
|----------------------------------------|
| Schema OTHER_SCH successfully created. |
+----------------------------------------+

さいごに

Snowflake CLI でのクエリ実行、オブジェクト定義について基本的な操作手順をまとめてみました。Git 連携も可能なのでこちらも試してみたいと思います。
本記事の内容が何かの参考になれば幸いです。