querying-data-lake

データレイクへのクエリ

ワークグループの選択、ステートメントの分類、エラー回復機能を備え、デフォルトカタログおよびフェデレーテッドカタログ（Glue、S3 Tables、Redshift）にまたがって Amazon Athena で SQL クエリを実行します。

概要

デフォルトカタログおよびフェデレーテッドカタログにまたがる Athena SQL クエリを実行・管理します。ワークグループを選択し、対象アセットを特定し（あいまいな参照の解決は finding-data-lake-assets に委任します）、ステートメントの安全性を分類して、コストとスキャンされたデータ量を報告します。サンドボックス環境での実行と監査ログ記録には AWS MCP サーバーを使用します。MCP サーバーが利用できない場合も、同じ AWS CLI コマンドを直接実行できます。

パラメーター取得の制約：

• SQL テキスト、名前付きクエリ名、ワークグループ名、カタログ名、または profile TABLE_NAME のいずれかの単一の省略可能な引数を必ず受け入れること
• 引数を直接のテキスト、または SQL を含むファイルへのポインターとして必ず受け入れること
• AWS リージョンが未設定の場合、必ずユーザーに対象の AWS リージョンを確認すること
• 重要なクエリを実行する前に、必ず出力先の S3 の場所を確認すること
• どの段階でも、ユーザーが中止を選択した場合は必ずその判断に従うこと

よくあるタスク

1. 依存関係を確認する

クエリを実行する前に、必要なツールと AWS へのアクセスを確認します。

制約：

• AWS MCP サーバーのツール（aws___call_aws）が利用可能か必ず確認し、利用可能な場合はそれを使ってクエリを実行すること。MCP サーバーが利用できない場合に限り、AWS CLI にフォールバックすること
• クエリの実行にシェルや Bash を使ってフォールバックしてはならない。出力先とコストを追跡できるよう、結果は MCP ツールまたは aws athena CLI を通じて取得すること
• aws sts get-caller-identity で必ず認証情報を確認し、不足しているツールがあればユーザーに伝えること

2. ワークグループを特定する

呼び出し元の ID を確認し、ワークグループを一覧表示して、最適なものを自動選択します（workgroup-selection.md を参照）。

制約：

• 出力先のエラーを防ぐため、クエリを送信する前に必ずワークグループを選択すること
• 選択したワークグループとその出力先を必ずユーザーに提示すること
• 失敗時に、ユーザーの確認なしで別のワークグループへ自動的に切り替えてはならない

3. 対象アセットを特定する

ユーザーがテーブル名、業務上の概念（「四半期レポート」「売上データ」など）、S3 パス、またはテーブルを指定しないカタログ名を指定した場合は、finding-data-lake-assets に委任し、具体的な database.table（デフォルト以外の場合はカタログも）を取得します。

制約：

• あいまいなアセット参照を athena list-data-catalogs や get-tables の反復実行で解決しようとしてはならない。これらの方法ではフェデレーテッドカタログを見落とし、トークンを無駄にするため
• ユーザーが完全修飾参照（正確な database.table）またはそのまま実行する SQL を提示した場合に限り、この手順を省略することが望ましい
• クエリを組み立てる前に、必ず解決したアセットを明示すること：「[テーブル]が[カタログ]で見つかりました。これをクエリに使用します。」
• ユーザーが「federated」、「Redshift」、「S3 Tables」に言及した場合、または finding-data-lake-assets が別のカタログを返した場合を除き、デフォルトの Glue カタログを使用することが望ましい

4. スキーマを確認する

分析クエリでは、最終的なクエリを組み立てる前に対象テーブルのプロファイルを作成することが望ましい。プロファイルの一部として、サンプル行（SELECT ... LIMIT 5）を必ず提示すること。

5. クエリを組み立てる

テーブルの指定方法はカタログの種類によって異なります。

• デフォルトの Glue カタログ：database.table（単一カタログのクエリではカタログのプレフィックスを省略します）。カタログをまたぐクエリでは、デフォルトカタログのテーブルを"awsdatacatalog".database.tableと指定します。
• 登録済みデータソース：datasource.database.table
• 未登録の Glue カタログ："catalog/subcatalog".database.table

6. 分類して実行する

実行前に SQL 文を分類します。

文	動作
SELECT、SHOW、DESCRIBE、EXPLAIN	安全 — 実行する
INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、TRUNCATE、MERGE	破壊的 — ユーザーに警告し、明示的な確認を求める
不明	破壊的として扱い、確認する

ツール呼び出しの例（AWS MCP サーバー経由）：

aws___call_aws(command="aws athena start-query-execution --work-group <WORKGROUP_NAME> --query-string '<sql>' --query-execution-context Database=<db>")

フェデレーテッドカタログまたは S3 Tables カタログの場合は、実行コンテキストに Catalog=<CATALOG_PATH> も設定します（例：Catalog=s3tablescatalog/<BUCKET_NAME>）。

制約：

• ターゲットが Redshift フェデレーテッドの場合、実行前に必ずユーザーに警告してください（「パーティションプルーニングがないため、すべてのクエリでテーブル全体がスキャンされます」）
• クロスカタログ結合の場合、実行前に必ずユーザーに警告してください（「クロスカタログ結合ではネットワークのオーバーヘッドが発生し、処理が遅くなる可能性があります」）
• 実行前に必ず出力先の S3 ロケーションを確認してください
• 実行前に、呼び出すツールを必ず説明してください
• 中止するというユーザーの判断を必ず尊重してください

7. 結果を提示して復旧する

コスト、スキャンしたデータ量、所要時間、実行可能な分析情報とともに結果を提示します。失敗した場合は、利用可能なワークグループを一覧表示し、どのワークグループで再試行するかユーザーに選んでもらいます。

引数の振り分け

次の順に解決し、最初に一致した時点で処理を終了します。

1. SQL キーワード（SELECT、SHOW、DESCRIBE、INSERT など）を含む — SQL テキストとして直接実行
2. profile TABLE_NAME — テーブルの包括的なプロファイリングを実行（query-patterns.md を参照）
3. 既知の名前付きクエリに一致する — 検索して実行
4. 既知のワークグループに一致する — ワークグループのステータスと最近のクエリを表示
5. 既知のカタログに一致する — exploring-data-catalog に委任して、データベースとテーブルを列挙
6. 引数なし — 最近のクエリアクティビティと利用可能なテーブルを表示

原則

• 実行前に必ずワークグループを選択してください（出力先のエラーを防ぎます）
• 不慣れなテーブルでは、分析クエリを実行する前にプロファイリングしてください
• ユーザーがコストを把握できるよう、結果とともにコストを提示してください
• 大規模なテーブルに対する探索的なクエリでは LIMIT を提案してください
• 答えが明らかなドメインに関する質問は決してしないでください。ただし、セキュリティに関わる操作（ワークグループの切り替え、出力先の変更、SELECT 以外の文）については、必ず確認してください

トラブルシューティング

エラー	原因	修正方法
大文字と小文字が混在する名前による Redshift の識別子エラー	Redshift フェデレーテッド名では小文字のみが使用されます	識別子を小文字にします
CatalogId の検証失敗	カタログ名ではなく ARN が渡された	ARN ではなくカタログ名を渡します
クロスカタログの information_schema が何も返さない	カタログ修飾子がない	カタログ修飾パスを使用します："catalog".information_schema.tables
出力先エラーによりクエリが失敗する	ワークグループに出力先が設定されていない	出力先のある別のワークグループを選択するか、出力先を設定します
破壊的な文が確認なしで実行された	文の分類が省略された	INSERT／UPDATE／DELETE／DROP／ALTER／CREATE／TRUNCATE／MERGE を必ず分類し、ユーザーに確認します

追加リソース

• ワークグループの選択ロジック
• 一般的なクエリパターン
• Athena のベストプラクティス
• Athena のフェデレーテッドクエリ