データレイク資産の検索

概要

データレイク資産参照を具体的なカタログエントリに解決します。他のスキルおよび直接ユーザーリクエストのリゾルバーとして機能します。Glue、S3、S3 Tables、Redshift をカバーします。トークン使用量を最小化することに最適化されており、素早く回答を返して終了します。

パラメータ取得の制約:

• 単一の引数（テーブル名、キーワード、列名、または S3 パス）を受け入れる必須
• 引数を直接入力、またはスペックを含むファイルへのポインタとして受け入れる必須
• ターゲット AWS リージョンが設定されていない場合は確認する必須
• あいまいな入力の場合は検索前に確認する必須（例：「テーブル X またはバケット Y のどちらを意味していますか？」）
• 任意のステップでユーザーの中止決定を尊重する必須

一般的なタスク

AWS MCP サーバーツールが接続されている場合は、必ずそれを使用してコマンドを実行します。これらはバリデーション、サンドボックス実行、監査ログを提供します。MCP が利用できない場合のみ AWS CLI にフォールバックします。各ステップ前に説明する必須。

1. 依存関係の確認

検索前に必要なツールと AWS アクセスを確認します。

制約:

• AWS MCP サーバーツール（aws___call_aws）が利用可能なことを確認する必須。利用できない場合は AWS CLI にフォールバック
• aws sts get-caller-identity で認証情報を確認する必須
• ユーザーに欠落ツールについて通知し、続行するか確認を求める必須

2. リクエストを分類する

モードを判定します：

• 解決（最も一般的）: ユーザー/スキルが何か特定のものを参照しています。 シグナル：所有格/定冠詞（「私たちの X テーブル」、「Y データセット」）は資産が存在することを示唆します。目標：それを見つけ、参照を返し、完了。
• 検索: ユーザーが探索しています。シグナル：「〜を含むテーブルを検索」、「customer_id を持つもの」。目標：候補をランク付けし、上位一致を提示。

あいまいな場合は解決モードをデフォルトとする推奨。

3. 検索用語を抽出する

リクエストを検索ディメンションに解析します：

• 名前用語: テーブルまたはデータベース名
• ドメイン用語: ビジネスコンセプト（請求、注文、チャーン）
• 列用語: 特定の列名（customer_id、event_type）
• 場所用語: S3 パス、バケット名、プレフィックス

4. レイヤー化検索（早期停止）

ソースを順に検索します。高信頼度マッチを返す最初のレイヤーで停止します。毎回すべてのレイヤーを検索しないでください。

検索したレイヤーとスキップしたレイヤーを追跡する必須。出力でこれを報告します（ステップ 6 を参照）。

レイヤー 1: Glue Data Catalog（常にここから開始）

主要 API として SearchTables を使用する推奨。カタログ全体をわたって単一の呼び出しでテーブル名、列名、列コメントを検索します。データベース名が既に分かっていない場合は、get-tables でデータベースをループしない必須。パターンについてはsearch-strategy.md を参照してください。

aws glue search-tables --search-text "orders"
aws glue get-tables --database-name sales --expression "order.*"

レイヤー 2: S3 逆引き検索（S3 パス提供時）

ユーザーが S3 パスを提供する場合、デフォルトで逆引き検索を優先する推奨。ファイル内容ではなく Glue テーブルを通常求めています。

aws glue search-tables --search-text "<path-keyword>"
aws s3api list-objects-v2 --bucket <bucket-name> --prefix <prefix>

レイヤー 3: Redshift カタログ（ユーザーが Redshift、warehouse、lakehouse を言及した場合）

SELECT schema_name, table_name, table_type
FROM svv_all_tables
WHERE table_name ILIKE '%orders%';

Redshift Spectrum 外部テーブルは Glue にも表示されます。レイヤー 1 が Spectrum SerDe を持つテーブルを見つけた場合、レイヤー 3 をスキップします。

4b. 広範スキャン フォールバック（単一ターン）

search-tables が何も返さず、S3 Tables 列挙も見落とした場合、データベース間でスキャンが必要になる可能性があります。データベースごとに別の CLI 呼び出しを発行しないでください。ターン数とトークンを消費します。代わりに、boto3 ページネーターを使用して単一の実行で完全スキャンを実行する短い Python スクリプトを作成します。スクリプトをファイルに書き込み、python3 で実行します。

スクリプトは以下の必須：

• get_databases() をページネーション化してすべてのデータベース名を収集
• 各データベースについて、検索用語に一致する Expression フィルタを使用して get_tables() をページネーション化
• マッチする結果のみを構造化出力（JSON またはテーブル）として出力
• 引数または変数としてリージョンと検索用語を受け入れる

import boto3, sys, json

region = sys.argv[1]
term = sys.argv[2]

glue = boto3.client("glue", region_name=region)
matches = []

db_paginator = glue.get_paginator("get_databases")
for db_page in db_paginator.paginate():
    for db in db_page["DatabaseList"]:
        db_name = db["Name"]
        tbl_paginator = glue.get_paginator("get_tables")
        for tbl_page in tbl_paginator.paginate(
            DatabaseName=db_name, Expression=f".*{term}.*"
        ):
            for tbl in tbl_page["TableList"]:
                matches.append({
                    "database": db_name,
                    "table": tbl["Name"],
                    "format": tbl.get("Parameters", {}).get("classification", "unknown"),
                    "location": tbl.get("StorageDescriptor", {}).get("Location", ""),
                })

print(json.dumps(matches, indent=2) if matches else "No matches found.")

このフォールバックは search-tables と S3 Tables 列挙が既に何も返さなかった後のみ使用する必須。これは最後の手段であり、最初の選択ではありません。

5. 信頼度ゲートを適用する

• 高信頼度（正確な名前マッチ、単一結果）: 解決された参照を直ちに返します。概要もオプションもなし。
• 中程度の信頼度（あいまいマッチ、2～3 結果）: 上位一致を 1 行で提示：名前、マッチ理由、形式。ユーザーに選択させます。
• 低信頼度（多数の弱いマッチまたはなし）: 検索内容とスキップ内容を報告し、クエリの絞り込みまたは exploring-data-catalog 実行を提案します。

6. 参照を返す

高信頼度解決の場合、構造化された参照を返します。常に「Sources searched / skipped」行を含めてユーザーが確認したデータストアとそうでないデータストアを知ることができるようにします。

Table: database_name.table_name
Catalog: default | catalog_name
Format: Parquet | CSV | JSON | ORC | Iceberg
Location: s3://bucket/prefix/
Partition keys: [key1, key2] or none
Sources searched: Glue Data Catalog
Sources skipped: S3, Redshift (stopped early — high-confidence match in Glue)

S3 Tables は 4 レベルの階層（catalog / table-bucket / namespace / table）を使用し、search-tables は s3tablescatalog/* にインデックスを付けません。ユーザーが S3 Tables を明示的に言及するか、レイヤー 1 が予想される S3 Tables 資産について何も返さない場合、aws s3tables list-table-buckets と list-namespaces で列挙します。以下のように返します：

Table: s3tablescatalog/<table-bucket>/<namespace>/<table>
Format: Iceberg
Location: arn:aws:s3tables:<region>:<account>:bucket/<table-bucket>/table/<table-uuid>
Sources searched: Glue Data Catalog, S3 Tables
Sources skipped: Redshift (not relevant to S3 Tables lookup)

SQL 参照: "s3tablescatalog/<table-bucket>"."<namespace>"."<table>"。

出力には常に「Sources searched」と「Sources skipped」の両方を含める必須。スキップ理由を括弧内にリストします。有効な理由：「stopped early」、「not relevant to this request」、「access denied」、「no results in prior layer」。

トラブルシューティング

エラー	原因	修正
get-tables がデータベース欠落で失敗	--database-name が必須	クロスデータベース検索の場合は search-tables を使用
search-tables が S3 Tables について何も返さない	フェデレーション カタログを S3 Tables がカバーしていない	S3 Tables が関連する場合は aws s3tables list-table-buckets を使用
search-tables で AccessDeniedException	呼び出し元が glue:SearchTables 権限を持っていない	権限をリクエストするか、既知のデータベースで Glue get-tables にフォールバック
API 呼び出しがタイムアウトまたはスロットル（ThrottlingException）	サービスレベルレート制限によるスロットル	指数バックオフで再試行。並列呼び出しを削減
リソースが予想されるリージョンにない	クロスリージョン検索	AWS リージョンを確認。Glue カタログはリージョンスコープ
委任呼び出し元が詳細出力を期待	他のスキルがこれをリゾルバーとして呼び出した	最小限の出力を返す。呼び出し元はカタログ参照が必要であり、フォーマット済み概要ではない

原則

• search-tables をデータベース反復より優先する必須。1 つの API 呼び出しが N を上回ります。
• get-tables を呼び出す場合、Expression フィルタを渡す必須。それなしで呼び出しない。
• データベースごとに別の CLI 呼び出しを発行しない必須。広範スキャンが必要な場合は、ステップ 4b の boto3 ページネーター スクリプトを使用して単一ターンで実行します。
• 素早く解決し、早期停止する推奨。追加の API 呼び出しはすべてトークンをコストします。
• 解決モードでは資産が存在すると想定する推奨。資産を確認するのではなく、それを見つけるために検索します。

追加リソース

• 検索戦略の詳細
• AWS Glue SearchTables API
• S3 Tables 概要
• S3 メタデータ テーブル