data-matching

データの照合

スキーマナレッジベースでは候補を見つけます。このスキルでは、候補がユーザーの質問に実際に合致するかどうかを判断します。意味的に似ているテーブルが、必ずしも適切な指標とは限りません。

新しいデータソースを導入する際は、このスキルを取得してください。以前に確認した保存済みクエリを限定的に改良する場合、指標、ソース、対象範囲、解釈が変わらない限り、繰り返し取得する必要はありません。

1. 質問をデータ契約に落とし込む

ソースを選ぶ前に、以下の要件を明確にしてください。

• 対象 — トランザクション、ウォレット、保有者、ポジション、トークン、プロトコル、エンティティ、またはその他の単位。
• 指標 — 件数、残高、供給量、取引量、価格、手数料、アクティブなウォレット、または定義済みの派生指標。
• 粒度 — イベント、ブロック、日、月、ウォレットとトークンの組み合わせ、プロトコルとチェーンの組み合わせなど。
• 対象範囲 — ネットワーク、アドレス、アセット、母集団、含める対象、除外する対象。
• 時間に関する意味 — 現在の状態、特定時点のスナップショット、一定期間のアクティビティ、または過去の時系列。
• 鮮度と出力 — リアルタイムの検索、その場限りの分析、再利用可能なクエリ、ダッシュボード、または定期実行のワークフロー。

不足している項目によってソースや結論が大きく変わる可能性がある場合は、確認の質問をしてください。そうでなければ、クエリを実行する前に妥当な仮定を明示してください。

2. 候補を探して確認する

1. プロダクト、指標、既知の分野の用語を使って search_docs を実行します。
2. search_schemas を使って、候補テーブルを3～5個見つけます。ユーザーのプロジェクト名だけでなく、対象と指標を使って検索してください。
3. 有望な候補に対して search_schemas(id=..., include_content=True) を実行します。カラム、粒度、説明、注意事項を確認してください。検索結果のタイトルだけで選択してはいけません。
4. よく使われる指標を再作成する前に、関連する標準的な Terminal の結果を search_terminal と get_terminal_results で確認します。

単一チェーンに関する質問には、チェーンごとのテーブルを優先してください。比較対象が実際に複数のチェーンにまたがり、ソースのチェーンおよびアセットの意味が質問に合致する場合に限り、クロスチェーンのソースを使用します。既知のアセットまたはウォレットの現在の状態には Realtime を、過去の分析、比較分析、集計分析には Explorer／SQL を使用してください。

質問が対応対象のセクター（実世界資産、ステーブルコイン、ブリッジ、DEX／AMM の取引、またはレンディング）に該当する場合、テーブルを独自に選ぶ前に、セクター固有のスキル（rwa-analysis、stablecoin-analysis、bridge-analysis、dex-analysis、lending-analysis）が利用可能か確認してください。これらのスキルには、そのセクターで繰り返し発生するテーブルやカラムの落とし穴がまとめられており、網羅性を調べるサイクルを省ける場合があります。

3. 候補をデータ契約と照合する

本命候補ごとに、以下を確認してください。

• 行の粒度は要求された単位に合っていますか。集計や結合によって意味が変わりませんか。
• フロー、スナップショット、累積値のどれですか。明示せずに別の種類で代用してはいけません。
• 要求されたネットワーク、日付、アセット、エンティティの対象範囲が含まれていますか。
• トークンの単位、価格、ラベル、ブリッジされた表現、帰属フィールドは、必要な確実性のレベルで定義されていますか。
• 指標を生の行から導出するより、安全に使えるキュレーション済みの指標や標準ダッシュボードがありますか。

曖昧さを、検索順位が最も高い候補を選ぶことで解消してはいけません。異なる、妥当性のある指標を表す候補は両方残し、その違いを説明してください。

4. 分析を構築する前に網羅性を確かめる

指標が分析の要となる場合、新たに選んだチェーンを使う場合、または網羅性に不確実さがある場合は、推奨ソースに対して範囲を絞った小規模なクエリを実行してください。数行と、短い時系列または集計結果を確認します。

検索でチェーンやテーブルが見つかっただけでは、網羅性が確認できたことにはなりません。要求された期間のデータが空、少量、古い、または異なる経済的対象を表している場合は、処理を止めて対象範囲を見直してください。ラップ済みアセットやブリッジされたアセットが存在しても、ネイティブチェーンのデータが網羅されている証拠にはなりません。

5. 一致マニフェストを返す

完全なクエリを作成する前に、次の形式で判断を提示します。

Field	Record
求める意味	オブジェクト、指標、粒度、対象範囲、時間の意味
推奨ソース	テーブル、エンドポイント、または標準ダッシュボード／クエリ
適合する理由	スキーマ／ドキュメントとカバレッジ調査による根拠
却下した代替案	候補と意味上の不一致
注意点	カバレッジ、鮮度、帰属、単位、集計に関する制限
判断	使用／注意点付きで使用／対象範囲を再設定／利用不可

選択したソース、注意点、カバレッジの結果をクエリと最終回答に反映します。結果が意思決定に関わるものになった場合は、create_explorer_query で保存し、共有する前に allium-investigation の再現性に関する手順に従ってください。