snowman

snowman

Snowflake クエリには scripts/snowman.py を使用し、ユーザーが依頼した変更を手動実行用にステージングします。字句フィルターは、書き込みステートメントと、副作用があることが知られている構文を拒否します。UDF や外部関数が読み取り専用であることまでは証明できません。最小権限の接続と、信頼できる読み取り関数を使用してください。

プロジェクトのコンテキストを読み込む

現在のディレクトリから上位に向かって .snowman/context.md を探し、読み込みます。見つからない場合は、先に ブートストラップ手順 に従ってください。--connection <name> を指定したブートストラップ時の探索を除き、クエリの実行にはコンテキストが必要です。コンテキストが存在する場合は、ラッパーに接続を解決させてください。

コンテキストにはプロジェクトのアーキテクチャと接続名を記録し、認証情報は記録しません。バージョン管理に含めてください。データベースの範囲は注目先のヒントであり、アクセス制限ではありません。ユーザーの質問に必要であれば、ほかのデータベースもクエリしてください。

クエリを実行する

すべての SQL クエリは、次のラッパーを経由します。

python3 <skill-dir>/scripts/snowman.py "<SQL>"

<skill-dir> はこのスキルのディレクトリです。呼び出しごとに 1 つのステートメントを送信してください。ラッパーは同じセッションで列の型を取得するため、DESCRIBE RESULT を追加で実行します。選択したコンテキストの default_warehouse が適用されます。設定されていない場合は、指定した接続のウェアハウス設定が適用されます。

標準出力には CSV データのみが出力されます。--json を指定した場合は、コンパクトな JSON 配列が出力されます。型、切り詰めの通知、成果物のパスは標準エラー出力に出力されます。解析時には、各ストリームを分けてください。CSV のセルには改行や # で始まる行が含まれることがあります。空の CSV セルは NULL を表し、"" は空文字列を表します。ネストされた値はコンパクトな JSON 形式です。結果が空の場合も、プレビューの上限が適用される範囲内で、利用可能な列名と型が標準エラー出力に保持され、標準出力には CSV ヘッダーまたは JSON の [] が出力されます。

デフォルトでは、行数の上限は 50 行、各セルの保持文字数の上限は切り詰めマーカーを含めて 200 文字、データ出力の上限は 16,000 UTF-8 バイトです。--max-rows、--max-cell、--max-output で変更できます。0 を指定すると、該当する上限が解除されます。JSON では、切り詰められない限り、ネストされたオブジェクトと配列が保持されます。切り詰められた場合、セルは短縮された JSON テキストになります。

結果が切り詰められると、完全な行とスキーマが JSON として保存されます。標準エラー出力に示される # full result: のパスをたどり、クエリを再実行したりファイル全体をコンテキストに読み込んだりするのではなく、必要なフィールドをローカルで確認してください。結果の解析や復元については、出力の詳細 を参照してください。

エラーに対処する

BLOCKED: の後に続く理由を確認してください。これは、SQL、コンテキスト、設定の問題などにより、クエリの実行前に拒否されたことを示します。設定の問題を修正するか、許可された読み取り操作に内容を変更してください。変更をステージングするのは、ユーザーが依頼した場合に限ります。拒否を回避するために、ラッパーを経由しない方法を使ってはいけません。PATH に snow が見つからない場合は、Snowflake CLI をインストールしてから再試行してください。

クエリ処理に失敗した場合は、報告された # raw CLI stdout: のファイルをローカルで確認してください。復元に使用できる、受信した出力が保持されています。自動的に再実行しないでください。

クエリの実行にはネットワークアクセスが必要です。環境で許可されている実行モードを使用してください。診断でサンドボックスのネットワーク制限が特定された場合は、ネットワークアクセスにその承認フローを使用してください。DNS エラーだけでは原因を特定できません。

認証に失敗した場合は、ラッパーが示すヒントを伝え、認証の設定 に従ってください。ラッパーは、プロジェクトルートまたはその上位にある最も近い .env を snow に渡します。そのファイルを読み込んだり、内容を表示したり、シークレットを要求したり、接続の認証情報を編集したりしないでください。

環境を選択する

environments: マップがある場合、クエリでは default_env が使用されます。ユーザーが別の環境を要求した場合は --env <name> を渡し、更新内容でその環境を明示してください。選択はクエリごとに行われます。単一アカウントのコンテキストでは connection: を使用し、--env は拒否されます。

複数の環境があるプロジェクトで変更をステージングするには、明示的な --env が必要です。ユーザーが変更対象の環境を指定していない場合は、ステージングする前に確認してください。すでに対象環境が指定されている場合は、再確認せずにそれを使用してください。

変更を依頼された場合のステージング

ユーザーが DML または DDL を依頼した場合は、SQL を準備してステージングします。

python3 <skill-dir>/scripts/snowman.py --stage "<SQL>" --name <purpose-slug>

複数環境のプロジェクトでは、選択した --env を追加します。ステージングにはコンテキストが必要で、複数のステートメントを受け付けます。スクリプトには用途を表す kebab-case の名前を付けます。ラッパーは .snowman/staged/ の下に Git で無視されるファイルを書き込み、そのパスと、接続先および設定済みのウェアハウスを含む手動実行コマンドを出力します。その両方と、破壊的なキーワードに関する警告があれば、それも伝えます。スクリプトの実行と後片付けはユーザーが行います。Snowman はどちらも行いません。

効率的に調査する

• 既知の範囲を最も狭く絞って調査を始めます。特定のテーブルがわかっている場合は、そのテーブルを調べます。データベース名やスキーマ名が不明な場合に限り、それらを特定します。
• 調査目的の読み取りには、フィルター、LIMIT、または SAMPLE で上限を設けます。プレビューの上限は出力を減らすものであり、クエリコストを減らすものではありません。本番環境では、より小さなサンプルとより絞り込んだフィルターを使います。負荷の高いクエリの前に、設定済みのウェアハウスを伝えるか、コンテキストにウェアハウスが設定されていない場合は CURRENT_WAREHOUSE() を確認します。
• SHOW TERSE を優先し、->> SELECT "col" FROM $1 でオブジェクトのメタデータを絞り込みます。TERSE では省略される rows と bytes には、通常の SHOW を使います。TERSE でもオブジェクトの出力が小さくならない場合は、列を明示的に指定します。
• 質問への回答に必要な列を選択します。偶発的に見つかった異常は、関連する場合に限り調査します。それ以外の場合は、回答で簡潔に言及します。
• 関連するクエリは調査中にまとめて実行します。委任するのは、広範で独立した作業に限り、個々のクエリやテーブルごとには委任しません。
• 最初のクエリの目的を伝え、調査結果によって方向性が変わった場合はその都度更新し、行データをそのまま並べるのではなく、調査結果を先に示して回答します。

調査、プロファイリング、仮説検証、原因調査、またはステージングの例については、ワークフローを読み込みます。SQL が拒否された理由の説明が必要な場合は、ガードレールの詳細を読みます。