snowflake-platform

Snowflake Platform スキル

snow CLI、Cortex AI 関数、Native Apps、Snowpark を使用して、Snowflake AI Data Cloud 上でアプリケーションを構築・デプロイします。

クイックスタート

Snowflake CLI をインストールする

pip install snowflake-cli
snow --version  # Should show 3.14.0+

接続を設定する

# Interactive setup
snow connection add

# Or create ~/.snowflake/config.toml manually

[connections.default]
account = "orgname-accountname"
user = "USERNAME"
authenticator = "SNOWFLAKE_JWT"
private_key_path = "~/.snowflake/rsa_key.p8"

接続をテストする

snow connection test -c default
snow sql -q "SELECT CURRENT_USER(), CURRENT_ACCOUNT()"

このスキルを使用する場面

使用する場面：

• Snowflake プラットフォーム上でアプリケーションを構築する場合
• SQL クエリで Cortex AI 関数を使用する場合
• Marketplace 向けの Native Apps を開発する場合
• JWT キーペア認証を設定する場合
• Snowpark Python を使用する場合

使用しない場面：

• Streamlit アプリを構築する場合（streamlit-snowflake スキルを使用してください）
• データエンジニアリング／ETL のパターンが必要な場合
• BI ツール（Tableau、Looker）を使用する場合

Cortex AI 関数

Snowflake Cortex は、SQL で直接 LLM の機能を提供します。関数は SNOWFLAKE.CORTEX スキーマにあります。

主な関数

関数	用途	GA ステータス
COMPLETE / AI_COMPLETE	プロンプトからのテキスト生成	2025 年 11 月 GA
SUMMARIZE / AI_SUMMARIZE	テキストの要約	GA
TRANSLATE / AI_TRANSLATE	言語間の翻訳	2025 年 9 月 GA
SENTIMENT / AI_SENTIMENT	感情分析	2025 年 7 月 GA
AI_FILTER	自然言語によるフィルタリング	2025 年 11 月 GA
AI_CLASSIFY	テキスト／画像の分類	2025 年 11 月 GA
AI_AGG	行をまたいだインサイトの集約	2025 年 11 月 GA

COMPLETE 関数

-- Simple prompt
SELECT SNOWFLAKE.CORTEX.COMPLETE(
    'llama3.1-70b',
    'Explain quantum computing in one sentence'
) AS response;

-- With conversation history
SELECT SNOWFLAKE.CORTEX.COMPLETE(
    'llama3.1-70b',
    [
        {'role': 'system', 'content': 'You are a helpful assistant'},
        {'role': 'user', 'content': 'What is Snowflake?'}
    ]
) AS response;

-- With options
SELECT SNOWFLAKE.CORTEX.COMPLETE(
    'mistral-large2',
    'Summarize this document',
    {'temperature': 0.3, 'max_tokens': 500}
) AS response;

利用可能なモデル：

• llama3.1-70b、llama3.1-8b、llama3.2-3b
• mistral-large2、mistral-7b
• snowflake-arctic
• gemma-7b
• claude-3-5-sonnet（200K コンテキスト）

モデルのコンテキストウィンドウ（2025 年更新）：

モデル	コンテキストウィンドウ	最適な用途
Claude 3.5 Sonnet	200,000 トークン	大規模なドキュメント、長い会話
Llama3.1-70b	128,000 トークン	複雑な推論、中規模のドキュメント
Llama3.1-8b	8,000 トークン	簡単なタスク、短いテキスト
Llama3.2-3b	8,000 トークン	高速な推論、最小限のテキスト
Mistral-large2	可変	最新のドキュメントを確認してください
Snowflake Arctic	可変	最新のドキュメントを確認してください

トークンの目安：約 4 文字 = 1 トークンです。32,000 文字のドキュメントは約 8,000 トークンです。

エラー：Input exceeds context window limit → 小さいモデルを使用するか、入力を分割してください。

SUMMARIZE 関数

-- Single text
SELECT SNOWFLAKE.CORTEX.SUMMARIZE(article_text) AS summary
FROM articles
LIMIT 10;

-- Aggregate across rows (no context window limit)
SELECT AI_SUMMARIZE_AGG(review_text) AS all_reviews_summary
FROM product_reviews
WHERE product_id = 123;

TRANSLATE 関数

-- Translate to English (auto-detect source)
SELECT SNOWFLAKE.CORTEX.TRANSLATE(
    review_text,
    '',      -- Empty = auto-detect source language
    'en'     -- Target language
) AS translated
FROM international_reviews;

-- Explicit source language
SELECT AI_TRANSLATE(
    description,
    'es',    -- Source: Spanish
    'en'     -- Target: English
) AS translated
FROM spanish_products;

AI_FILTER（自然言語によるフィルタリング）

パフォーマンス：2025 年 9 月時点で、AI_FILTER には自動最適化機能が含まれており、適切なクエリでは 2～10 倍の高速化と最大 60% のトークン削減を実現します。

-- Filter with plain English
SELECT * FROM customer_feedback
WHERE AI_FILTER(
    feedback_text,
    'mentions shipping problems or delivery delays'
);

-- Combine with SQL predicates for maximum optimization
-- Query planner applies standard filters FIRST, then AI on smaller dataset
SELECT * FROM support_tickets
WHERE created_date > '2025-01-01'  -- Standard filter applied first
  AND AI_FILTER(description, 'customer is angry or frustrated');

ベストプラクティス：AI_FILTER は常に従来の SQL 述語（日付範囲、カテゴリなど）と組み合わせ、AI 処理の前にデータセットを絞り込んでください。これにより、自動最適化のメリットを最大限に活用できます。

スロットリング：利用がピークに達すると、AI 関数のリクエストが再試行可能なエラーとともにスロットリングされることがあります。本番アプリケーションでは指数バックオフを実装してください（既知の問題 #10 を参照）。

AI_CLASSIFY

-- Categorize support tickets
SELECT
    ticket_id,
    AI_CLASSIFY(
        description,
        ['billing', 'technical', 'shipping', 'other']
    ) AS category
FROM support_tickets;

課金

Cortex AI 関数の料金はトークン数に基づきます。

• 約 4 文字 = 1 トークン
• 入力トークンと出力トークンの両方が課金対象です
• 料金はモデルによって異なります（大規模なモデルほど高額です）

大規模環境でのコスト管理（コミュニティ提供情報）：

実際の本番環境の事例では、単一の AI_COMPLETE クエリで 11 億 8,000 万件のレコードを処理し、クレジットが約 5,000 ドル分消費されました。注意すべきコスト要因：

1. クロスリージョン推論：お使いのリージョンで利用できないモデルでは、追加のデータ転送コストが発生します
2. ウェアハウスのアイドル時間：未使用のコンピューティングも課金されますが、自動サスペンドを頻繁に行うと再開のオーバーヘッドが発生します
3. 大規模なテーブル結合：AI 関数を使用する複雑なクエリでは、コストが増大します

-- This seemingly simple query can be expensive at scale
SELECT
    product_id,
    AI_COMPLETE('mistral-large2', 'Summarize: ' || review_text) as summary
FROM product_reviews  -- 1 billion rows
WHERE created_date > '2024-01-01';

-- Cost = (input tokens + output tokens) × row count × model rate
-- At scale, this adds up fast

ベストプラクティス：

• AI 関数を適用する前に、データセットを絞り込んでください
• 適切なサイズのウェアハウスを使用してください（過剰にプロビジョニングしないでください）
• QUERY_HISTORY ビューを使用してクレジット消費量を監視してください
• 行ごとの AI 操作ではなく、バッチ処理を検討してください

出典：The Hidden Cost of Snowflake Cortex AI（課金の証拠を含むコミュニティブログ）

認証

JWT 鍵ペア認証

重要：Snowflake では、アカウント識別子に 2 つの形式を使用します。

形式	例	用途
組織-アカウント	irjoewf-wq46213	REST API URL、接続設定
アカウントロケーター	NZ90655	JWT クレーム（iss、sub）

これらは相互に置き換えられません！

アカウントロケーターの確認

SELECT CURRENT_ACCOUNT();  -- Returns: NZ90655

RSA 鍵ペアの生成

# Generate private key (PKCS#8 format required)
openssl genrsa 2048 | openssl pkcs8 -topk8 -inform PEM -out ~/.snowflake/rsa_key.p8 -nocrypt

# Generate public key
openssl rsa -in ~/.snowflake/rsa_key.p8 -pubout -out ~/.snowflake/rsa_key.pub

# Get fingerprint for JWT claims
openssl rsa -in ~/.snowflake/rsa_key.p8 -pubout -outform DER | \
  openssl dgst -sha256 -binary | openssl enc -base64

ユーザーへの公開鍵の登録

-- In Snowflake worksheet (requires ACCOUNTADMIN or SECURITYADMIN)
ALTER USER my_user SET RSA_PUBLIC_KEY='MIIBIjANBgkq...';

JWT クレームの形式

iss: ACCOUNT_LOCATOR.USERNAME.SHA256:fingerprint
sub: ACCOUNT_LOCATOR.USERNAME

例：

iss: NZ90655.JEZWEB.SHA256:jpZO6LvU2SpKd8tE61OGfas5ZXpfHloiJd7XHLPDEEA=
sub: NZ90655.JEZWEB

SPCS コンテナ認証（v4.2.0+）

2026 年 1 月の新機能：Snowpark Container Services 内で実行している場合、コネクターは SPCS サービス識別子トークンを自動的に検出して使用します。

# No special configuration needed inside SPCS containers
import snowflake.connector

# Auto-detects SPCS_TOKEN environment variable
conn = snowflake.connector.connect()

これにより、明示的な認証情報を設定することなく、コンテナ化された Snowpark サービスからシームレスに認証できます。

出典：リリース v4.2.0

Snow CLI コマンド

プロジェクト管理

# Initialize project
snow init

# Execute SQL
snow sql -q "SELECT 1"
snow sql -f query.sql

# View logs
snow logs

Native App コマンド

# Development
snow app run              # Deploy and run locally
snow app deploy           # Upload to stage only
snow app teardown         # Remove app

# Versioning
snow app version create V1_0
snow app version list
snow app version drop V1_0

# Publishing
snow app publish --version V1_0 --patch 0

# Release Channels
snow app release-channel list
snow app release-channel add-version --channel ALPHA --version V1_0
snow app release-directive set default --version V1_0 --patch 0 --channel DEFAULT

Streamlit コマンド

snow streamlit deploy --replace
snow streamlit deploy --replace --open

ステージコマンド

snow stage list
snow stage copy @my_stage/file.txt ./local/

Native App の開発

プロジェクト構成

my_native_app/
├── snowflake.yml           # Project config
├── manifest.yml            # App manifest
├── setup_script.sql        # Installation script
├── app/
│   └── streamlit/
│       ├── environment.yml
│       └── streamlit_app.py
└── scripts/
    └── setup.sql

snowflake.yml

definition_version: 2

native_app:
  name: my_app
  package:
    name: my_app_pkg
    distribution: external    # For marketplace
  application:
    name: my_app
  source_stage: stage/dev
  artifacts:
    - src: manifest.yml
      dest: manifest.yml
    - src: setup_script.sql
      dest: setup_script.sql
    - src: app/streamlit/environment.yml
      dest: streamlit/environment.yml
    - src: app/streamlit/streamlit_app.py
      dest: streamlit/streamlit_app.py
  enable_release_channels: true  # For ALPHA/BETA channels

manifest.yml

manifest_version: 1

artifacts:
  setup_script: setup_script.sql
  default_streamlit: streamlit/streamlit_app.py

# Note: Do NOT include privileges section - Native Apps can't declare privileges

外部アクセス統合

外部 API を呼び出す Native App には、次の設定が必要です。

-- 1. Create network rule (in a real database, NOT app package)
CREATE DATABASE IF NOT EXISTS MY_APP_UTILS;

CREATE OR REPLACE NETWORK RULE MY_APP_UTILS.PUBLIC.api_rule
  MODE = EGRESS
  TYPE = HOST_PORT
  VALUE_LIST = ('api.example.com:443');

-- 2. Create integration
CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_integration
  ALLOWED_NETWORK_RULES = (MY_APP_UTILS.PUBLIC.api_rule)
  ENABLED = TRUE;

-- 3. Grant to app
GRANT USAGE ON INTEGRATION my_app_integration
  TO APPLICATION MY_APP;

-- 4. CRITICAL: Attach to Streamlit (must repeat after EVERY deploy!)
ALTER STREAMLIT MY_APP.config_schema.my_streamlit
  SET EXTERNAL_ACCESS_INTEGRATIONS = (my_app_integration);

警告：ステップ 4 は、snow app run を実行するたびにリセットされます。デプロイのたびに再実行する必要があります！

共有データパターン

Native App が外部データベースのデータを必要とする場合：

-- 1. Create shared_data schema in app package
CREATE SCHEMA IF NOT EXISTS MY_APP_PKG.SHARED_DATA;

-- 2. Create views referencing external database
CREATE OR REPLACE VIEW MY_APP_PKG.SHARED_DATA.MY_VIEW AS
SELECT * FROM EXTERNAL_DB.SCHEMA.TABLE;

-- 3. Grant REFERENCE_USAGE (CRITICAL!)
GRANT REFERENCE_USAGE ON DATABASE EXTERNAL_DB
  TO SHARE IN APPLICATION PACKAGE MY_APP_PKG;

-- 4. Grant access to share
GRANT USAGE ON SCHEMA MY_APP_PKG.SHARED_DATA
  TO SHARE IN APPLICATION PACKAGE MY_APP_PKG;
GRANT SELECT ON ALL VIEWS IN SCHEMA MY_APP_PKG.SHARED_DATA
  TO SHARE IN APPLICATION PACKAGE MY_APP_PKG;

setup_script.sql では、元のデータベースではなく shared_data.view_name を参照してください。

マーケットプレイスへの公開

セキュリティレビューのワークフロー

# 1. Deploy app
snow app run

# 2. Create version
snow app version create V1_0

# 3. Check security review status
snow app version list
# Wait for review_status = APPROVED

# 4. Set release directive
snow app release-directive set default --version V1_0 --patch 0 --channel DEFAULT

# 5. Create listing in Snowsight Provider Studio (UI only)

セキュリティレビューのステータス

ステータス	意味	対応
NOT_REVIEWED	スキャンが実行されていません	DISTRIBUTION が EXTERNAL になっているか確認します
IN_PROGRESS	スキャン中です	完了を待ちます
APPROVED	合格しました	公開できます
REJECTED	不合格です	問題を修正するか、異議を申し立てます
MANUAL_REVIEW	人によるレビュー中です	完了を待ちます（数日かかる場合があります）

手動レビューの対象となるもの：外部アクセス統合、Streamlit コンポーネント、ネットワーク呼び出し。

Provider Studio の項目

項目	最大文字数	備考
タイトル	72 文字	アプリ名
サブタイトル	128 文字	一行の説明
説明	10,000 文字	HTML エディター
ビジネスニーズ	最大 6 件	ドロップダウンから選択
クイックスタートの例	最大 10 件	タイトル + 説明 + SQL
データ辞書	必須	データリスティングでは必須（2025 年）

有料リスティングの前提条件

#	要件
1	Snowflake のフルアカウント（トライアルではないこと）
2	ACCOUNTADMIN ロール
3	Provider Profile の承認
4	Stripe アカウントの設定
5	Provider & Consumer Terms への同意
6	Marketplace Ops への問い合わせ

注：無料リスティングを有料に変更することはできません。新しいリスティングを作成する必要があります。

Snowpark Python

セッションの設定

from snowflake.snowpark import Session

connection_params = {
    "account": "orgname-accountname",
    "user": "USERNAME",
    "password": "PASSWORD",  # Or use private_key_path
    "warehouse": "COMPUTE_WH",
    "database": "MY_DB",
    "schema": "PUBLIC"
}

session = Session.builder.configs(connection_params).create()

DataFrame の操作

# Read table
df = session.table("MY_TABLE")

# Filter and select
result = df.filter(df["STATUS"] == "ACTIVE") \
           .select("ID", "NAME", "CREATED_AT") \
           .sort("CREATED_AT", ascending=False)

# Execute
result.show()

# Collect to Python
rows = result.collect()

行へのアクセス（よくある落とし穴）

# WRONG - dict() doesn't work on Snowpark Row
config = dict(result[0])

# CORRECT - Access columns explicitly
row = result[0]
config = {
    'COLUMN_A': row['COLUMN_A'],
    'COLUMN_B': row['COLUMN_B'],
}

DML 統計情報（v4.2.0+）

2026 年 1 月の新機能：SnowflakeCursor.stats プロパティを使用すると、rowcount だけでは不十分な操作（CTAS クエリなど）の詳細な DML 統計情報を取得できます。

# Before v4.2.0 - rowcount returns -1 for CTAS
cursor.execute("CREATE TABLE new_table AS SELECT * FROM source WHERE active = true")
print(cursor.rowcount)  # Returns -1 (not helpful!)

# After v4.2.0 - stats property shows actual row counts
cursor.execute("CREATE TABLE new_table AS SELECT * FROM source WHERE active = true")
print(cursor.stats)  # Returns {'rows_inserted': 1234, 'duplicates': 0, ...}

出典：リリース v4.2.0

UDF とストアドプロシージャ

from snowflake.snowpark.functions import udf, sproc

# Register UDF
@udf(name="my_udf", replace=True)
def my_udf(x: int) -> int:
    return x * 2

# Register Stored Procedure
@sproc(name="my_sproc", replace=True)
def my_sproc(session: Session, table_name: str) -> str:
    df = session.table(table_name)
    count = df.count()
    return f"Row count: {count}"

REST API（SQL API v2）

REST API は、Cloudflare Workers からプログラムで Snowflake にアクセスするための基盤です。

エンドポイント

https://{org-account}.snowflakecomputing.com/api/v2/statements

必須ヘッダー（重要）

すべてのリクエストにこれらのヘッダーを含める必要があります。Accept がないと、エラーが通知されないまま失敗します。

const headers = {
  'Authorization': `Bearer ${jwt}`,
  'Content-Type': 'application/json',
  'Accept': 'application/json',  // REQUIRED - "null" error if missing
  'User-Agent': 'MyApp/1.0',
};

非同期クエリの処理

単純なクエリでも非同期で返されます（HTTP 202）。必ずポーリングを実装してください。

// Submit returns statementHandle, not results
const submit = await fetch(url, { method: 'POST', headers, body });
const { statementHandle } = await submit.json();

// Poll until complete
while (true) {
  const status = await fetch(`${url}/${statementHandle}`, { headers });
  if (status.status === 200) break;  // Complete
  if (status.status === 202) {
    await sleep(2000);  // Still running
    continue;
  }
}

Workers のサブリクエスト制限

プラン	上限	安全なポーリング
無料	50	2 秒間隔で 45 回 = 最大 90 秒
有料	1,000	500 ミリ秒間隔で 100 回 = 最大 50 秒

フェッチのタイムアウト

Workers の fetch() にはデフォルトのタイムアウトがありません。必ず AbortController を使用してください。

const response = await fetch(url, {
  signal: AbortSignal.timeout(30000),  // 30 seconds
  headers,
});

タイムアウト時のキャンセル

ウェアハウスのコストを抑えるため、タイムアウトが発生したらクエリをキャンセルしてください。

POST /api/v2/statements/{statementHandle}/cancel

完全な実装については、templates/snowflake-rest-client.ts を参照してください。

既知の問題

1. アカウント識別子の混同

症状：JWT 認証がサイレントに失敗し、クエリが Query History に表示されません。

原因：JWT クレームでアカウントロケーターではなく、組織アカウント形式を使用しています。

解決策：SELECT CURRENT_ACCOUNT() を使用して、実際のアカウントロケーターを取得してください。

2. 外部アクセス設定のリセット

症状：snow app run の実行後に API 呼び出しが失敗します。

原因：デプロイのたびに、外部アクセス統合のアタッチメントがリセットされます。

解決策：デプロイのたびに ALTER STREAMLIT ... SET EXTERNAL_ACCESS_INTEGRATIONS を再実行してください。

3. リリースチャネルの構文

症状：ALTER APPLICATION PACKAGE ... SET DEFAULT RELEASE DIRECTIVE が失敗します。

原因：リリースチャネルが有効な場合、従来の SQL 構文は機能しません。

解決策：snow CLI を使用してください：snow app release-directive set default --version V1_0 --patch 0 --channel DEFAULT

4. アーティファクトの入れ子

症状：ファイルが streamlit/ ではなく streamlit/streamlit/ に表示されます。

原因：snowflake.yml のディレクトリマッピングによって、フォルダー名が入れ子になります。

解決策：artifacts ではディレクトリではなく、個々のファイルを明示的に指定してください。

5. REFERENCE_USAGE の不足

症状：「共有コンテンツに追加されたビューは、他のデータベースのオブジェクトを参照できません」

原因：共有データに対する GRANT REFERENCE_USAGE ON DATABASE が不足しています。

解決策：外部データベースを使用する場合は、snow app run の前に必ず REFERENCE_USAGE を付与してください。

6. REST API の Accept ヘッダー不足

症状：ポーリングリクエストで「Unsupported Accept header null is specified」と表示されます。

原因：初回リクエストには Accept: application/json が含まれていましたが、ポーリングリクエストには含まれていませんでした。

解決策：送信、ポーリング、キャンセルのすべてのリクエストで、一貫したヘルパー関数を使用してください。

7. Workers の Fetch が停止しない

症状：Snowflake からの応答を待っている間、Worker がいつまでも停止します。

原因：Cloudflare Workers の fetch() にはデフォルトのタイムアウトがありません。

解決策：すべての Snowflake リクエストで、必ず AbortSignal.timeout(30000) を使用してください。

8. サブリクエストが多すぎる

症状：ポーリング中に「Too many subrequests」エラーが発生します。

原因：1 秒ごとのポーリングを 600 回試行すると、600 件のサブリクエストとなり、制限を超えます。

解決策：2～5 秒ごとにポーリングし、試行回数を 45 回（無料プラン）または 100 回（有料プラン）に制限してください。

9. ウェアハウスが自動再開しない（ように見える）

症状：クエリが statementHandle を返しますが、完了せず（コード 090001 のまま）止まります。

原因：090001 はエラーではなく「実行中」を意味します。ウェアハウスは再開中で、時間がかかっているだけです。

解決策：自動再開は機能します。しばらく待つか、先に明示的に再開してください：POST /api/v2/warehouses/{wh}:resume

10. Connector 4.x のメモリリーク（対応中の問題）

エラー：長時間実行する Python アプリケーションで、時間の経過とともにメモリ使用量が増加します。 発生元：GitHub Issue #2727、#2725 影響範囲：snowflake-connector-python 4.0.0 ～ 4.2.0

発生する理由：

• SessionManager が defaultdict を使用しているため、ガベージコレクションが妨げられます。
• SnowflakeRestful.fetch() がクエリ実行中にリークする参照を保持します。

防止策： 接続を繰り返し新規作成するのではなく、再利用してください。PR #2741 および PR #2726 による修正が進行中です。

# AVOID - creates new connection each iteration
for i in range(1000):
    conn = snowflake.connector.connect(...)
    cursor = conn.cursor()
    cursor.execute("SELECT 1")
    cursor.close()
    conn.close()

# BETTER - reuse connection
conn = snowflake.connector.connect(...)
cursor = conn.cursor()
for i in range(1000):
    cursor.execute("SELECT 1")
cursor.close()
conn.close()

ステータス：Connector v4.3.0 以降で修正される見込みです

11. ピーク時の AI 関数のスロットリング

エラー：「使用量が多いためリクエストがスロットリングされました。再試行してください。」 ソース：Snowflake Cortex のドキュメント 影響範囲：すべての Cortex AI 関数（COMPLETE、FILTER、CLASSIFY など）

発生する理由： プラットフォームの処理能力を管理するため、使用量が多い時間帯には AI／LLM リクエストがスロットリングされることがあります。スロットリングされたリクエストはエラーを返し、手動で再試行する必要があります。

予防策： 指数バックオフを使用した再試行ロジックを実装します。

import time
import snowflake.connector

def execute_with_retry(cursor, query, max_retries=3):
    for attempt in range(max_retries):
        try:
            return cursor.execute(query).fetchall()
        except snowflake.connector.errors.DatabaseError as e:
            if "throttled" in str(e).lower() and attempt < max_retries - 1:
                wait_time = 2 ** attempt  # Exponential backoff
                time.sleep(wait_time)
            else:
                raise

ステータス：仕様として文書化済み。修正の予定はありません。

参考資料

• Snowflake CLI のドキュメント
• SQL REST API リファレンス
• SQL API 認証
• Cortex AI 関数
• Native Apps フレームワーク
• Snowpark Python
• マーケットプレイスへの公開

関連スキル

• streamlit-snowflake - Snowflake の Streamlit アプリ