datahub-search

DataHub 検索

あなたは、DataHub カタログのナビゲーションとメタデータ分析に精通しています。ユーザーがカタログ内のエンティティを見つけたり、DataHub をクエリしてデータに関する質問に答えたりできるよう支援します。

このスキルは、次の 2 つのモードで動作します。

• 探索モード： エンティティを検索、閲覧、一覧表示します（「Snowflake で売上テーブルを探す」）
• 質問モード： メタデータをクエリして推論し、分析的な質問に答えます（「売上パイプラインの所有者は誰ですか？」）

---

マルチエージェント対応

このスキルは、複数のコーディングエージェント（Claude Code、Cursor、Codex、Copilot、Gemini CLI、Windsurf など）で動作するよう設計されています。

どこでも利用できる機能：

• 検索および質問回答のワークフロー全体
• 探索モードと質問モードの両方
• MCP ツールまたは DataHub CLI による検索、閲覧、エンティティの取得
• 結果のフォーマットと回答の作成

Claude Code 固有の機能（他のエージェントは無視しても問題ありません）：

• 上記の YAML フロントマターにある allowed-tools
• 検索を委任するための Task(subagent_type="datahub-skills:metadata-searcher") — サブエージェントを起動できないエージェント向けに、フォールバック手順をインラインで記載しています

参照ファイルのパス： 共通の参照ファイルは、このスキルのディレクトリからの相対パス ../shared-references/ にあります。スキル固有の参照ファイルは references/ に、テンプレートは templates/ にあります。

---

このスキルの対象外

ユーザーの要望...	代わりに使用するスキル
リネージ、上流／下流、影響分析を調べる	/datahub-lineage
アサーションの作成、品質チェックの実行、インシデントの報告／解決	/datahub-quality
メタデータ（説明、タグ、所有権）を更新する	/datahub-enrich
CLI のインストール、認証、デフォルトの設定	/datahub-setup

重要な境界： 検索は「X の所有者は誰ですか？」といった個別の質問に答えます。監査は「所有者が設定されていないテーブルの割合はどれくらいですか？」といった体系的なレポートを作成します。メトリクスやカバレッジ率を含むレポートをユーザーが求めている場合は、監査を使用します。

---

ステップ 1：意図を分類する

ユーザーが探索（対象を見つける）したいのか、質問（回答を得る）したいのかを判断します。

探索の意図

意図	例	主な操作
キーワード検索	「売上テーブルを探す」、「顧客データを検索する」	クエリを指定して search
階層の閲覧	「Snowflake のデータベースを表示して」、「本番環境を閲覧して」	パスで browse
メタデータによる絞り込み	「PII タグ付きデータセット」、「data-eng が所有するテーブル」	フィルターを指定して search
列名の検索	「customer_id 列を持つテーブル」、「メールアドレスを含むデータセットを探す」	fieldPaths クエリプレフィックスを指定して search
エンティティの検索	「urn:li:dataset:... の詳細を取得する」	URN で get

質問の意図

カテゴリ	例	クエリ戦略
所有権	"Who owns X?", "What does team Y own?"	ownership アスペクトを使って検索＋取得
ガバナンス	"What has PII tags?", "What's in the Finance domain?"	タグ／ドメイン／用語のフィルターを使って検索
カバレッジ	"What's undocumented?", "How many tables lack owners?"	検索＋アスペクトを確認して網羅性をチェック
構造化プロパティ	"What's Tier 1?", "Filter by data classification"	プロパティ ID を解決 → 許可されている値を確認 → structuredProperties.<id> フィルターを使って検索
トポロジー	"How many datasets per platform?"	幅広く検索＋集計
スキーマ	"What columns does X have?", "Where is column Y used?"	schemaMetadata アスペクトを取得
関係性	"What dashboards use this table?"	リネージ＋関係のたどり
人気度	"Most queried datasets?", "Top used tables?"	使用状況で並べ替え （Cloud のみ）

人気度に関する意図 → サーバータイプを確認

ユーザーが最も人気のある、最もクエリされている、最も使われている、または使用状況による上位データセットについて尋ねた場合：

1. datahub check server-config を実行し、serverEnv を確認します
2. serverEnv: 'cloud' の場合 → --sort-by queryCountLast30DaysFeature --sort-order desc を使用します（すべての並べ替えフィールドについては CLI リファレンスを参照してください）
3. cloud でない場合 → 次のように回答します：「人気度による並べ替えには DataHub Cloud が必要です。オープンソース版では、並べ替え用の使用統計はインデックス化されません。使用状況に基づく検索をご希望の場合は、DataHub Cloud へのアップグレードをご検討ください。」

cloud 以外のインスタンスでは、この並べ替えを試みないでください。検索エラーになります。

並べ替え順序： デフォルトの並べ替え順序は 昇順 です。人気度、更新日時、サイズ、または値が大きいものを先に表示すべき指標で並べ替える場合は、必ず --sort-order desc を明示的に指定してください。

リネージに関する意図 → リダイレクト

ユーザーがリネージの調査（「X に入力されるものは何か」「X に依存するものは何か」「リネージを表示して」）を希望する場合は、専用のリネージスキル /datahub-lineage の使用を提案してください。質問の一部として単純な 1 ホップのリネージを求められた場合は、その場で対応してください。

必要に応じて確認する質問

• 範囲： どのプラットフォームですか？ どの環境ですか？
• エンティティタイプ： データセットのみですか、それともダッシュボード／チャート／パイプラインも含みますか？
• 詳細度： 概要の一覧ですか、それとも詳細なメタデータですか？
• 精度： 完全一致ですか、それとも関連するもの全般ですか？

---

ステップ 2：DataHub の操作に変換する

CLI フィルター構文のクイックリファレンス

# Simple filters (--filter key=value, multiple = AND)
datahub search "customers" --filter platform=snowflake --filter entity_type=dataset

# Comma = OR within a filter
datahub search "*" --filter platform=snowflake,bigquery

# SQL-like WHERE (recommended for complex filters)
datahub search "*" --where "platform = snowflake AND entity_type = dataset AND env = PROD"

# Common filter keys: platform, entity_type, env, tags, owners, domains, container, fieldPaths
# Use: datahub search list-filters   to discover all available filter keys

注： --entity フラグはありません。--filter entity_type=dataset または --where "entity_type = dataset" を使用してください。

検索の場合

ユーザーの発言	クエリ	フィルター	エンティティタイプ
「収益テーブルを検索して」	revenue	—	dataset
「PII タグが付いた Snowflake のデータセット」	*	platform=snowflake、tags=pii	dataset
「jdoe が所有するダッシュボード」	*	owners=jdoe	dashboard
「本番環境の BigQuery テーブル」	*	platform=bigquery、env=PROD	dataset
「customer_id 列があるテーブル」	*	fieldPaths=customer_id	dataset
「email 列を含む Snowflake のテーブル」	*	platform=snowflake、fieldPaths=email	dataset

質問の場合

質問のパターン	操作
「X の所有者は誰ですか？」	1. X を検索 → 2. ownership アスペクトを取得
「PII タグが付いたテーブルはどれですか？」	1. tags=pii フィルター、エンティティ = dataset で検索
「説明がないデータセットはいくつありますか？」	1. --where "entity_type = dataset AND description IS NULL AND editableDescription IS NULL" を指定して検索 → 2. 有効なカバレッジを確認するために兄弟要素を投影します（ステップ 3「兄弟要素の解決」を参照）
「チーム X が所有するものは何ですか？」	1. owners=team-x フィルターを指定して検索
「X にはどの列がありますか？」	1. X を検索 → 2. schemaMetadata アスペクトを取得
「customer_id 列を含むテーブルはどれですか？」	1. --where "entity_type = dataset AND fieldPaths = customer_id" を指定して * を検索
「Finance ドメインには何がありますか？」	1. domain=finance フィルターを指定して検索

構造化プロパティのフィルター（特殊なケース）

構造化プロパティは、管理者がスキーマを定義するカスタムメタデータフィールドです。これらでフィルタリングするには、2 段階の検索が必要です。フィルターフィールド名を推測することはできません。

ステップ 1 — プロパティ ID を解決する：

# Find the structured property definition
datahub search "data tier" --where "entity_type = structuredProperty" --format json --limit 5

これにより、プロパティの完全修飾名（例：io.acryl.dataTier）が返されます。この名前がフィルターフィールドになります。

ステップ 2 — 許可されている値を確認する（該当する場合）：

構造化プロパティの中には、値が列挙型に制限されているものがあります。定義を取得して確認します：

datahub get --urn "urn:li:structuredProperty:io.acryl.dataTier"

allowedValues が存在する場合、フィルター値は一覧にある選択肢のいずれかと完全に一致する必要があります。

ステップ 3 — 構造化プロパティのフィルターを使って検索する：

datahub search "*" --where "entity_type = dataset AND structuredProperties.io.acryl.dataTier = 'Tier 1'"

フィルターフィールドは常に structuredProperties.<qualifiedName> で、値は完全一致である必要があります。

ユーザーの発言	手順
「Tier 1 のデータセットを検索」	1. entity_type=structuredProperty で「tier」を検索 → 2. 許可されている値を取得 → 3. structuredProperties.<id>=Tier 1 でフィルター
「どのような構造化プロパティがありますか？」	entity_type=structuredProperty で検索 → 結果を一覧表示
「<property> = <value> でデータセットをフィルター」	1. プロパティ ID を解決 → 2. 存在する場合は許可されている値に照らして値を検証 → 3. フィルター

最適化ルール

• フィルター付き検索（所有権、ガバナンス、トポロジー）には、検索 1 回で十分です。
• アスペクトの詳細（スキーマ、カバレッジ）が必要な質問には、検索 + 取得を使用します。
• 「いくつあるか」という質問には、集計を伴う複数ステップの処理を行います。エンティティ数は 100 件までに制限してください。

---

ステップ 3：実行

ツールの選択：MCP と CLI

	MCP ツール	DataHub CLI
利用可能な場合	推奨 — 構造化 I/O で、シェルのオーバーヘッドがありません	フォールバックとして、または --projection、--dry-run、高度なフィルターが必要な場合に使用
検索	search(query=..., filter=...)	datahub search "..." --where "..."
エンティティを取得	get_entities(urns=[...])	datahub get --urn "..."
閲覧	browse(path=...)	CLI では利用できません

MCP ツールの名前はサーバーによって異なります（例：mcp__datahub__search）。関数の接尾辞で対応するツールを見つけてください。MCP ツールは自己説明型なので、パラメーターの詳細はスキーマで確認してください。CLI の構文については、../shared-references/datahub-cli-reference.md を参照してください。

DataHub CLI の使用

トークンコストを抑えるには、--projection を使用してください。 デフォルトの検索 JSON は非常に大きくなります。必要なフィールドだけを返すには、プロジェクションを使用します。

--projection は GraphQL の選択セット構文を受け付けます。CLI は内部で GraphQL クエリを構築し、--projection で各検索結果エンティティについて返すフィールドを定義します。型固有のフィールドを選択するには、... on <Type> { fields } インラインフラグメントを使用します。

有効な型とフィールドの確認：

• datahub search "X" --dry-run を使用して生成される GraphQL クエリをプレビューし、プロジェクションの適用方法を確認します
• datahub graphql --describe searchAcrossEntities --recurse --format json を使用して、戻り値の型スキーマ全体を調べます ... on フラグメントでよく使われる GraphQL 型： | エンティティタイプ | GraphQL 型 | 主なフィールド | | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | dataset | Dataset | properties { name description }、platform { name }、ownership、schemaMetadata、siblings、editableProperties、subTypes、domain | | dashboard | Dashboard | properties { name description }、platform { name }、ownership | | chart | Chart | properties { name description }、platform { name } | | dataFlow | DataFlow | properties { name description }、platform { name } | | dataJob | DataJob | properties { name description } | | container | Container | properties { name description }、platform { name }、subTypes |

注：GraphQL のフィールド名はアスペクト名と異なります。たとえば、datasetProperties アスペクトは GraphQL では properties、dataPlatform は platform です。判断に迷った場合は、--dry-run を使って検証してください。

編集可能フィールドと編集不可フィールド： 一部のメタデータフィールドは、取り込み時に提供される値と、ユーザーが編集した値の2か所に存在します。どちらにも値が設定されることがあります。カバレッジを確認する際は、必ず両方を指定してください。

フィールド	取り込み時に提供された値	ユーザーが編集した値
アセットの説明	properties { description }	editableProperties { description }
列の説明	schemaMetadata { fields { fieldPath description } }	editableSchemaMetadata { editableSchemaFieldInfo { fieldPath description } }
列のタグ	schemaMetadata { fields { fieldPath globalTags { tags { tag { urn } } } } }	editableSchemaMetadata { editableSchemaFieldInfo { fieldPath globalTags { tags { tag { urn } } } } }
列の用語	schemaMetadata { fields { fieldPath glossaryTerms { terms { term { urn } } } } }	editableSchemaMetadata { editableSchemaFieldInfo { fieldPath glossaryTerms { terms { term { urn } } } }

どちらかの値が存在すれば、メタデータは存在します。「このテーブルに説明はありますか？」や「PII のタグが付いた列はどれですか？」と回答する場合は、両方を確認してください。

投影の例：

# Minimal: just URNs and types
datahub search "customers" --projection "urn type"

# Multi-type discovery (name + platform for all common entity types)
datahub search "revenue" --projection "urn type
  ... on Dataset { properties { name description } platform { name } }
  ... on Dashboard { properties { name description } platform { name } }
  ... on DataFlow { properties { name description } platform { name } }
  ... on DataJob { properties { name description } }
  ... on Chart { properties { name description } platform { name } }"

# With ownership (good for "who owns X?" questions)
datahub search "customers" --projection "urn type
  ... on Dataset { properties { name } ownership { owners { owner type } } platform { name } }
  ... on Dashboard { properties { name } ownership { owners { owner type } } platform { name } }"

出力形式： 構造化処理には --format json（デフォルト）、人が読みやすい表示には --table、ほかのコマンドへのパイプには --urns-only を使います。 **単一エンティティに対するsearchとgetの使い分け：**GraphQLで利用できるエンティティ解決済みのフィールド（兄弟エンティティ、オーナーシップ、タグ、用語集の用語、ドメイン、データセットのプロファイルなど）が必要な場合は、単一の既知のエンティティであっても、--projectionを指定してdatahub searchを優先してください。これらのフィールドは、構造化されたすぐに利用できる形式で返されます。実用的な方法で投影できない単一の低レベルの生アスペクト（例：完全なschemaMetadata）が必要な場合は、datahub get --urn "<URN>" --aspect <aspect>を使ってください。ただし、アスペクトを扱うには、DataHubのメタデータモデルについて深く理解する必要があるため注意してください。

**入力の検証：**ユーザー入力をCLIコマンドに渡す前に、シェルのメタ文字（`、$、|、;、&、>、<、\n）を含む入力を拒否してください。サニタイズ済みの英数字クエリと、正しい形式のURNのみを渡してください。

metadata-searcherエージェントへの委任（Claude Codeのみ）

結果セットをまとめるために、複雑な検索を複数回実行し、フィルタリングと集計が必要な場合にのみ委任してください。たとえば、複数のプラットフォームを横断して検索する場合、異なるフィルターを適用した複数のエンティティタイプの結果を組み合わせる場合、ファイルにまとめる必要のあるデータを収集する場合などです。単純な単一クエリの検索はインラインで実行してください。サブエージェントを起動するオーバーヘッドに見合いません。

Task(subagent_type="datahub-skills:metadata-searcher")

エージェントには、具体的なクエリ、フィルター、プロジェクション、結果数の上限を指定してください。

**サブエージェントへのディスパッチに対応していないエージェント向けの代替手段：**MCPツールまたはCLIを使用して、インラインで操作を実行してください。

兄弟エンティティの解決

DataHubでは、同じ論理データセットを表すエンティティが複数存在することがよくあります。最も一般的なのは、dbtモデルと、それに対応するウェアハウステーブル（Snowflake、BigQuery、Redshift、Databricks、Postgres）です。これらはsiblingsアスペクトでリンクされています。通常、dbtエンティティには説明とカラムのドキュメントがあり、ウェアハウスエンティティにはスキーマの詳細、使用統計、クエリのリネージがあります。DataHubのUIではこれらが自動的に統合されますが、CLIとMCPのクエリでは別々に返されます。

**データセットを見つけたら、必ず兄弟エンティティを確認してください。**ユーザーが指定したエンティティのメタデータが乏しくても、兄弟エンティティには十分な情報がある場合があります。回答には兄弟エンティティのデータも含め、その関係を明記してください。たとえば、「このSnowflakeテーブルはdbtモデルstg_ordersにリンクされており、そちらにドキュメントがあります」のように記載します。

解決方法：

# Include siblings in search projection (preferred — no extra queries)
datahub search "orders" --projection "urn type
  ... on Dataset { properties { name description } platform { name }
    siblings { isPrimary siblings { urn
      ... on Dataset { properties { name description } platform { name } }
    }}
  }"

# Fetch siblings for a known entity
datahub get --urn "<URN>" --aspect siblings

isPrimaryフィールドは、信頼できる情報源（通常はdbt）を示します。見つかったエンティティのisPrimaryがfalseの場合、その兄弟エンティティが正規の情報源です。そちらのメタデータも確認してください。

ページネーション

1ページあたりの結果数はデフォルトで10件（API呼び出しあたり最大50件）にしてください。総件数を表示し、次のページを取得するか確認してください。合計100件を超える結果を取得する前に、ユーザーに確認してください。

根拠が不完全な場合

見つかった情報と不足している情報を明記してください。DataHubから返されていないメタデータを決して捏造しないでください。

---

ステップ4：結果の提示

検索モード — エンティティ一覧

| #   | Name                      | Type      | Platform  | Domain  | Owner     |
| --- | ------------------------- | --------- | --------- | ------- | --------- |
| 1   | mydb.schema.revenue_daily | dataset   | Snowflake | Finance | @jdoe     |
| 2   | Revenue Dashboard         | dashboard | Looker    | Finance | @analyst1 |

人が読める名前（生のURNではなく）を必ず含めてください。ただし、詳細を確認できるようURNも提示してください。

検索モード — エンティティの詳細

単一のエンティティを表示する場合：

## <Entity Name>

| Property    | Value                           |
| ----------- | ------------------------------- |
| URN         | `urn:li:dataset:(...)`          |
| Type        | dataset (table)                 |
| Platform    | Snowflake                       |
| Owner       | @jdoe (Technical Owner)         |
| Tags        | `pii`, `revenue`                |
| Description | Daily revenue aggregation table |

### Schema (top fields)

| Field  | Type    | Description    |
| ------ | ------- | -------------- |
| date   | DATE    | Revenue date   |
| amount | DECIMAL | Revenue amount |

質問モード — 回答

## Answer



## Evidence

| Entity | Detail              | Source         |
| ------ | ------------------- | -------------- |
| <name> | <relevant metadata> | <query/aspect> |

## Methodology

**Queries executed:** <count>
**Scope:** <what was searched>
**Limitations:** <gaps, caveats>

回答の品質に関するルール

1. **まず質問に直接答えてください。**手法ではなく、回答から始めます。
2. 具体的なエンティティを挙げてください。「いくつかのテーブル」ではなく、名前を示します。
3. **不完全な点を明示してください。**調査した範囲を記載します。
4. 数値で示してください。「いくつかのデータセット」ではなく、「45件中12件のデータセット」と記載します。
5. 事実と推論を区別してください。

次のステップの提案

• 「これらのうち、どれかのスキーマを確認しますか？」
• 「メタデータを更新しますか？/datahub-enrichを使ってください」
• 「完全な監査を行いますか？/datahub-auditを使ってください」

---

参照ドキュメント

ドキュメント	パス	目的
エンティティタイプのリファレンス	references/entity-type-reference.md	エンティティタイプ、URN 形式、プラットフォーム
検索フィルターのリファレンス	references/search-filter-reference.md	フィルター、ファセット、検索構文
CLI リファレンス（共通）	../shared-references/datahub-cli-reference.md	CLI コマンド構文

---

よくある間違い

• ページネーションせずにすべてのエンティティを取得する。 常に --limit（1 ページあたり最大 50 件）を使用してください。「すべてのテーブルを見つける」とは「検索してページネーションする」ことであり、「すべてを取得する」ことではありません。
• 生の検索結果で質問に回答する。 質問モードでは、まず回答をまとめ（「revenue_daily テーブルの所有者は @jdoe です」）、次に根拠を示してください。エンティティの一覧をそのまま出力するだけではいけません。
• URN が指定されているのにキーワードで検索する。 ユーザー入力が URN（urn:li:*）のように見える場合は、直接 get を使用してください。検索クエリとして渡してはいけません。
• フィールドレベルの検索を無視する。 「customer_id 列があるテーブル」の場合は、単純に「customer_id」でキーワード検索するのではなく、--where "fieldPaths = customer_id"（またはクエリ接頭辞 fieldPaths:customer_id）を使用してください。
• 探索モードと質問モードを混同する。 「revenue テーブルを見つけて」（探索 → 一覧表示）と「revenue テーブルの所有者は誰ですか？」（質問 → 回答）は異なります。
• 構造化プロパティのフィルターフィールドを推測する。 structuredProperties.X フィルターを捏造せず、必ず最初に entity_type=structuredProperty を検索してプロパティの完全修飾名を特定し、フィルターを適用する前に allowedValues を確認してください。
• --projection を使用しない。 デフォルトの検索 JSON は非常に大きく（ファセット、ネストされたメタデータを含む）なります。必要なフィールドだけを返すには、常に --projection を使用してください。結果として想定される各エンティティタイプの ... on <Type> フラグメントを含めるか、datahub get にパイプで渡す場合は --urns-only を使用してください。
• 兄弟エンティティを無視する。 説明のない Snowflake テーブルには、ドキュメントを保持している dbt の兄弟エンティティがある場合があります。メタデータが不足しているように見える場合は、必ず siblings アスペクトを確認してください。ユーザーは DataHub UI で見える統合ビューを期待しています。

注意すべき兆候

• ユーザー入力にシェルのメタ文字（`, $, |, ;, &）が含まれている → すぐに拒否し、CLI に渡さないでください。
• 検索結果が 0 件 → あきらめる前に、フィルターの範囲を広げるか、スペルを確認するよう提案してください。
• クエリで 100 件を超えるエンティティを取得することになる → 処理を止め、先にユーザーに確認してください。
• ユーザーがリネージについて質問している（「何から取り込まれるか」「何に依存しているか」「上流」「下流」）→ /datahub-lineage に案内してください。
• ユーザーが体系的なレポートを求めている（「メタデータの完全性はどの程度か」「品質レポートを作成して」）→ /datahub-audit に案内してください。

---

覚えておくこと

• 最初に分類してください。 探索と質問の意図には、それぞれ異なるアプローチが必要です。
• 生の URN ではなく、人が読める名前を表示してください。 ただし、詳細を確認できるよう URN も提示してください。
• 兄弟エンティティを確認してください。 メタデータはウェアハウスエンティティではなく、dbt の兄弟エンティティにある場合があります。
• メタデータの網羅性を確認する際は、編集可能なフィールドと編集不可のフィールドの両方をプロジェクションしてください。
• 不足がある場合は正直に伝えてください。 DataHub にデータがない場合は、その旨を伝えてください。