Data Catalog でデータアセットを検索して表示する

このドキュメントでは、Data Catalog を使用してデータアセットを検索する方法について説明します。

検索できるデータアセットには、次のようなものがあります。

Analytics Hub にリンクされたデータセット。
BigQuery のデータセット、テーブル、ビュー、モデル
Bigtable のインスタンス、クラスタ、テーブル（列ファミリーの詳細を含む）
Data Catalog のタグテンプレート、エントリグループ、カスタムエントリ。
Dataplex のレイク、ゾーン、テーブル、ファイルセット
Dataproc Metastore のサービス、データベース、テーブル
Pub/Sub データストリーム
Spanner のインスタンス、データベース、テーブル、ビュー
Vertex AI モデル、データセット、Vertex AI Feature Store リソース
Data Catalog に接続されている、エンタープライズデータサイロ内のアセット。

検索範囲

権限によっては検索結果が異なる場合があります。 Data Catalog の検索結果は、ロールに応じて範囲を限定されます。

Data Catalog で使用できるさまざまな種類の IAM のロールと権限を確認できます。

たとえば、BigQuery メタデータの読み取りアクセス権がある場合、そのオブジェクトが Data Catalog の検索結果に表示されます。必要な最小限の権限は次のとおりです。

テーブルを検索するには、そのテーブルに対する bigquery.tables.get 権限が必要です。
データセットを検索するには、そのデータセットに対する bigquery.datasets.get 権限が必要です。
データセットまたはテーブルのメタデータを検索するには、roles/bigquery.metadataViewer のロールが必要です。
プロジェクト内または組織内のすべてのリソースを検索するには、datacatalog.catalogs.searchAll 権限が必要です。ソースシステムに依存しないすべてのリソースで機能します。

BigQuery テーブルにアクセスできるものの、そのテーブルを含むデータセットへのアクセス権がない場合でも、テーブルは Data Catalog の検索で想定どおりに表示されます。Pub/Sub や Data Catalog など、サポートされているすべてのシステムに同じアクセスロジックが適用されます。

検索での再現率の問題

Data Catalog の検索クエリは、完全な再現率を保証するものではありません。以降の結果ページであっても、クエリに一致する結果が返されない場合があります。また、検索クエリを繰り返すと、返される（返されない）結果が変わることがあります。

再現率の問題があり、特定の順序で結果を取得する必要がない場合は、catalog.search メソッドを呼び出すときに orderBy パラメータを default に設定することを検討してください。

`admin_search` フラグを使用する

検索リクエストで admin_search フラグを使用すると、完全な再呼び出しが保証されます。管理者検索を行うには、検索範囲内のすべてのプロジェクトと組織に datacatalog.catalogs.searchAll 権限を設定する必要があります。admin_search を使用する場合、default orderBy のみが許可されます。

日付別テーブル

Data Catalog は、日付別テーブルを単一の論理エントリに集計します。このエントリには、最新の日付のテーブルシャードと同じスキーマが含まれ、シャードの合計数に関する集計情報が含まれます。このエントリは、自身が属するデータセットのアクセスレベルを継承します。論理エントリを含むデータセットへのアクセス権をユーザーが持っている場合、Data Catalog の検索には、これらの論理エントリのみが表示されます。個々の日付共有テーブルは Data Catalog の検索に表示されません。これは、Data Catalog に日付共有テーブルが存在していて、タグ付けできる場合でも変わりません。

フィルタ

フィルタを使用すると、検索結果を絞り込むことができます。すべてのフィルタはセクションに分かれています。

スコープ: スター付きアイテムのみに検索を制限します。
システム: BigQuery、Pub/Sub、Dataplex、Dataproc Metastore、カスタムシステム、Vertex AI、Data Catalog など。Data Catalog システムには、ファイルセットとカスタムエントリが含まれています。
レイクとゾーン: Dataplex から取得されます。
データ型: データストリーム、データセット、レイク、ゾーン、ファイルセット、モデル、テーブル、ビュー、サービス、データベース、カスタムタイプなど。
[プロジェクト] には、使用可能なすべてのプロジェクトが一覧表示されます。
[タグ] には、利用可能なすべてのタグテンプレート（および個々のフィールド）が表示されます。
[データセット] は BigQuery と Vertex AI から取得されます。
[一般公開データセット] は、BigQuery の一般公開データです。

複数のセクションのフィルタを組み合わせると、選択したすべてのセクションから 1 つ以上の条件に一致するアセットを見つけることができます。1 つのセクション内で選択した複数のフィルタは、「OR」論理演算子を使用して評価されます。たとえば、次のフィルタの組み合わせがあるとします。

Data Catalog は以下を探します。

MyTemplate1 テンプレートがタグ付けされた BigQuery データセット。
MyTemplate2 テンプレートがタグ付けされた BigQuery データセット。
MyTemplate1 テンプレートがタグ付けされた BigQuery テーブル。
MyTemplate2 テンプレートがタグ付けされた BigQuery テーブル。

タグ値でフィルタ

[タグ] フィルタを使用すると、特定のテンプレートを使用してタグ付けされたアセットにクエリを実行できます。 [カスタマイズ] メニューを使用すると、結果をさらに絞り込んだり、特定のタグ値でフィルタしたりできます。タグ値のフィルタ条件は、そのタグフィールドのデータ型によって異なります。たとえば、日時フィールドと数値フィールドには、特定の日付または範囲を指定できます。

フィルタの可視性

各セクションに表示されるフィルタは、検索ボックスの現在のクエリによって異なります。検索結果セット全体に現在のクエリに一致するエントリが含まれていても、それらのエントリに対応するフィルタが [フィルタ] パネルに表示されない場合があります。

データアセットを検索する方法

コンソール

Console

Google Cloud コンソールで Dataplex 検索クエリを起動するには、[Dataplex 検索] ページに移動します。

[Dataplex Search] に移動
[検索プラットフォームの選択] で、検索モードとして [Data Catalog] を選択します。
検索フィールドにクエリを入力するか、[フィルタ] パネルを使用して検索パラメータを絞り込みます。

次のフィルタを手動で追加できます。

[プロジェクト] でプロジェクトフィルタの [プロジェクトを追加] のボタンをクリックし、特定のプロジェクトを検索して選択し、[開く] をクリックします。
[タグ] でタグ　テンプレート　フィルタの [タグ　テンプレートをさらに追加] プルダウンをクリックして特定のテンプレートを検索し、テンプレートを選択して [OK] をクリックします。

さらに、次のことが可能です。

[一般公開データセットを含める] をオンにすると、使用可能なアセットに加えて、Google Cloud で一般公開されているデータアセットを検索できます。

検索の例

たとえば、タグテンプレート、タグ、概要、データスチュワードの構成で設定した trips テーブルを検索するには:

検索フィールドに「trips」と入力して [検索] をクリックします。
[BigQuery] セクションから [BigQuery] を選択し、他のシステムに属する同じ名前のデータアセットを除外します。
他のプロジェクトのデータアセットを除外するには、[プロジェクト] セクションからプロジェクト ID を選択します。プロジェクトがセクションに表示されていない場合は、[プロジェクトを追加] をクリックしてダイアログウィンドウでプロジェクトを選択します。
[タグ　テンプレート] セクションから [デモタグテンプレート] を選択し、このテンプレートを使用するタグが trips テーブルに添付されているかどうかを確認します。このテンプレートがセクションに表示されていない場合は、[タグをさらに追加] プルダウンをクリックして検索、選択し、[OK] をクリックします。

選択したすべてのフィルタで、検索結果に含まれるエントリは、プロジェクト内の Demo Tag Template を使用したタグが付いた BigQuery の trips テーブル 1 つだけです。

また、次の操作も行うことができます。

検索フィールドの検索キーワードに「keyword:value」をつけて検索すると絞り込みができます。

キーワード	説明
`name:`	データアセット名に一致する
`column:`	列名またはネストされた列名に一致する
`description:`	テーブルの説明に一致する

検索フィールドで検索キーワードに次のいずれかのタグプレフィックスを追加すると、タグ検索を実行できます。

タグ	説明
`tag:project-name.tag_template_name`	タグ名に一致する
`tag:project-name.tag_template_name.key`	タグキーに一致する
`tag:project-name.tag_template_name.key:value`	`key:string value` タグのペアに一致

検索式のヒント

スペースが含まれている場合は、検索式を引用符で囲みます（"search terms"）。
キーワードの前に "NOT"（すべて大文字）を付けると、keyword:term フィルタの論理否定に一致します。ブール演算子「AND」と「OR」（すべて大文字）を使って、検索式を結合することもできます。

たとえば、NOT column:term と指定すると、指定した用語と一致する列を除くすべての列が一覧表示されます。Data Catalog 検索式で使用できるキーワードとその他の用語のリストについては、Data Catalog の検索構文をご覧ください。

Java

このサンプルを試す前に、クライアントライブラリを使用した Data Catalog のクイックスタートにある Java の設定手順を行ってください。詳細については、Data Catalog Java API のリファレンスドキュメントをご覧ください。

Data Catalog への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。

import com.google.cloud.datacatalog.v1.DataCatalogClient;
import com.google.cloud.datacatalog.v1.DataCatalogClient.SearchCatalogPagedResponse;
import com.google.cloud.datacatalog.v1.SearchCatalogRequest;
import com.google.cloud.datacatalog.v1.SearchCatalogRequest.Scope;
import com.google.cloud.datacatalog.v1.SearchCatalogResult;
import java.io.IOException;

// Sample to search catalog
public class SearchAssets {

  public static void main(String[] args) throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project-id";
    String query = "type=dataset";
    searchCatalog(projectId, query);
  }

  public static void searchCatalog(String projectId, String query) throws IOException {
    // Create a scope object setting search boundaries to the given organization.
    // Scope scope = Scope.newBuilder().addIncludeOrgIds(orgId).build();

    // Alternatively, search using project scopes.
    Scope scope = Scope.newBuilder().addIncludeProjectIds(projectId).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (DataCatalogClient dataCatalogClient = DataCatalogClient.create()) {
      // Search the catalog.
      SearchCatalogRequest searchCatalogRequest =
          SearchCatalogRequest.newBuilder().setScope(scope).setQuery(query).build();
      SearchCatalogPagedResponse response = dataCatalogClient.searchCatalog(searchCatalogRequest);

      System.out.println("Search results:");
      for (SearchCatalogResult result : response.iterateAll()) {
        System.out.println(result);
      }
    }
  }
}

Node.js

このサンプルを試す前に、クライアントライブラリを使用した Data Catalog のクイックスタートにある Node.js の設定手順を行ってください。詳細については、Data Catalog Node.js API のリファレンスドキュメントをご覧ください。

// Import the Google Cloud client library.
const {DataCatalogClient} = require('@google-cloud/datacatalog').v1;
const datacatalog = new DataCatalogClient();

async function searchAssets() {
  // Search data assets.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const projectId = 'my_project'; // Google Cloud Platform project

  // Set custom query.
  const query = 'type=lake';

  // Create request.
  const scope = {
    includeProjectIds: [projectId],
    // Alternatively, search using Google Cloud Organization scopes.
    // includeOrgIds: [organizationId],
  };

  const request = {
    scope: scope,
    query: query,
  };

  const [result] = await datacatalog.searchCatalog(request);

  console.log(`Found ${result.length} datasets in project ${projectId}.`);
  console.log('Datasets:');
  result.forEach(dataset => {
    console.log(dataset.relativeResourceName);
  });
}
searchAssets();

Python

このサンプルを試す前に、クライアントライブラリを使用した Data Catalog のクイックスタートにある Python の設定手順を行ってください。詳細については、Data Catalog Python API のリファレンスドキュメントをご覧ください。

from google.cloud import datacatalog_v1

datacatalog = datacatalog_v1.DataCatalogClient()

# TODO: Set these values before running the sample.
project_id = "project_id"

# Set custom query.
search_string = "type=dataset"
scope = datacatalog_v1.types.SearchCatalogRequest.Scope()
scope.include_project_ids.append(project_id)

# Alternatively, search using organization scopes.
# scope.include_org_ids.append("my_organization_id")

search_results = datacatalog.search_catalog(scope=scope, query=search_string)

print("Results in project:")
for result in search_results:
    print(result)

REST とコマンドライン

REST

ご使用の言語の Cloud クライアントライブラリにアクセスしない場合、または REST リクエストを使用して API をテストする場合は、次の例を参照して、Data Catalog REST API のドキュメントをご覧ください。

1. カタログを検索。

リクエストのデータを使用する前に、次のように置き換えます。

organization-id: GCP 組織 ID
project-id: GCP プロジェクト ID

HTTP メソッドと URL:

POST https://datacatalog.googleapis.com/v1/catalog:search

リクエストの本文（JSON）:

{
  "query":"trips",
  "scope":{
    "includeOrgIds":[
      "organization-id"
    ]
  }
}

リクエストを送信するには、次のいずれかのオプションを展開します。

curl（Linux、macOS、Cloud Shell）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://datacatalog.googleapis.com/v1/catalog:search"

PowerShell（Windows）

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を request.json という名前のファイルに保存して、次のコマンドを実行します。

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://datacatalog.googleapis.com/v1/catalog:search" | Select-Object -Expand Content

次のような JSON レスポンスが返されます。

{
  "results":[
    {
      "searchResultType":"ENTRY",
      "searchResultSubtype":"entry.table",
"relativeResourceName":"projects/project-id/locations/US/entryGroups/@bigquery/entries/entry1-id",
      "linkedResource":"//bigquery.googleapis.com/projects/project-id/datasets/demo_dataset/tables/taxi_trips"
    },
    {
      "searchResultType":"ENTRY",
      "searchResultSubtype":"entry.table",
      "relativeResourceName":"projects/project-id/locations/US/entryGroups/@bigquery/entries/entry2-id",
      "linkedResource":"//bigquery.googleapis.com/projects/project-id/datasets/demo_dataset/tables/tlc_yellow_trips_2018"
    }
  ]
}

テーブルの詳細の表示

Cloud コンソール内で Data Catalog を使用して、テーブルの詳細を表示できます。

Dataplex の検索ページに移動します。

Data Catalog に移動
[検索プラットフォームの選択] で、検索モードとして [Data Catalog] を選択します。
検索ボックスに、テーブルを含むデータセットの名前を入力します。

たとえば、クイックスタートを完了した場合は、demo-dataset を検索して trips テーブルを選択できます。
テーブルをクリックします。

[BigQuery テーブルの詳細] ページが開きます。

テーブルの詳細には次のセクションが含まれます。

BigQuery テーブルの詳細。作成日時、前回の変更日時、有効期限、リソースの URL、ラベルなどの情報が含まれます。
タグ。適用されたタグを一覧表示します。このページでタグを編集し、タグテンプレートを表示できます。 [アクション] アイコンをクリックします。
スキーマと列のタグ。適用されたスキーマとその値を一覧表示します。

お気に入りのエントリにスターを付け、検索します

同じデータアセットを頻繁に閲覧する場合は、スターを使用してマークを付けて、パーソナライズされたリストにエントリを追加できます。この操作を Dataplex UI で行うには:

Dataplex の検索ページに移動します。

Data Catalog に移動
[検索プラットフォームの選択] で、検索モードとして [Data Catalog] を選択します。
アセットを見つけて、次の 2 つの方法のいずれかでエントリにスターを付けます。
- 検索結果のエントリの横にあるアイコンをクリックします。
- エントリ名をクリックして詳細ページを開き、上部のアクションバーにある STARボタンをクリックします。

最大 200 件のエントリにスターを付けることができます。

スター付きのエントリは、検索バーに検索クエリを入力する前に、検索ページの [スター付きエントリ] リストに表示されます。このリストは、本人だけに表示されます。

スター付きエントリのみを検索するには、[フィルタ] パネルで [スコープ] > [スター付き] オプションを選択します。

Data Catalog API の対応するメソッドを使用して、エントリにスターを付けたり、外したりすることもできます。アセットを検索する場合は、scope オブジェクトの starredOnly パラメータを使用します。catalog.search メソッドをご覧ください。

Data Catalog でデータアセットを検索して表示する

検索範囲

検索での再現率の問題

admin_search フラグを使用する

日付別テーブル

フィルタ

タグ値でフィルタ

フィルタの可視性

データアセットを検索する方法

コンソール

Console

検索の例

検索式のヒント

Java

Node.js

Python

REST とコマンドライン

REST

1. カタログを検索。

curl（Linux、macOS、Cloud Shell）

PowerShell（Windows）

テーブルの詳細の表示

お気に入りのエントリにスターを付け、検索します

`admin_search` フラグを使用する