Knowledge Catalog でキーワードのみの検索を使用する

Knowledge Catalog でキーワードのみの検索を使用して、特定のキーワード、フィルタ、定義された構文を使用してリソースを検索します。キーワードのみの検索では、検索クエリを正確に制御し、メタデータ フィールドに基づいて結果を絞り込むことができます。

始める前に

検索を実行する前に、必要なロールが付与され、必要な API が有効になっていることを確認してください。

必要なロール

Knowledge Catalog でエントリを検索して検索結果にアクセスするために必要な権限を取得するには、次の IAM ロールを付与するよう管理者に依頼してください。

  • エントリを検索する:
  • BigQuery データセットとテーブルのメタデータを検索する: データセットまたはテーブルに対する BigQuery メタデータ閲覧者 roles/bigquery.metadataViewer
  • カスタム エントリを検索する: プロジェクトに対する Dataplex Catalog 閲覧者 roles/dataplex.catalogViewer

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

キーワードのみの検索を使用する

コンソール

キーワード検索を使用してリソースを検索する手順は次のとおりです。

  1. Google Cloud コンソールで、Knowledge Catalog の [検索] ページに移動します。

    検索に移動

  2. 検索プラットフォームが [Data Catalog] に設定されている場合は、[検索プラットフォームの選択] メニューで [Knowledge Catalog] を選択します。

  3. [プロジェクト全体でリソースを検索] フィールドにクエリを入力します。

  4. 検索を絞り込むには、[フィルタ] パネルを使用します。次のフィルタを使用できます。

    • [システム] には、BigQuery や Cloud SQL など、使用可能なシステムのリストが表示されます。Knowledge Catalog システムにはカスタム エントリが含まれています。
    • [アスペクト(タグ)] を使用すると、特定のテンプレートを使用してタグ付けされたアセットにクエリを実行できます。[カスタマイズ] メニューを使用することで、結果をさらに絞り込んだり、特定のアスペクト値でフィルタしたりできます。
    • [プロジェクト] には、検索の範囲を設定できるプロジェクトが一覧表示されます。
    • タイプ エイリアスは、エントリ タイプに関連付けられたデータ型です。エントリタイプに projects/test-project/locations/us/entryTypes/my-entry-type という名前が付いている場合でも、型エイリアス TABLE または DATABASE を使用して検索できます。エントリタイプを作成または更新するときに、1 つ以上の型エイリアスを設定できます。
    • [データセット] は BigQuery から取得されます。

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

    • プロジェクト フィルタを追加する: [プロジェクト] で、[プロジェクトを追加] をクリックします。特定のプロジェクトを検索して選択し、[開く] をクリックします。
    • アスペクト タイプ フィルタを追加する: [アスペクト] で、[アスペクト タイプを追加] メニューをクリックします。特定のテンプレートを検索して選択し、[OK] をクリックします。
  5. 省略可: 使用可能なアセットだけでなく、[公開データセットを含める] を選択することで、 Google Cloud で一般公開されているリソースを検索できます。

    検索クエリを作成するには、次のヒントを参考にしてください。

    • スペースが含まれている場合は、検索式を引用符で囲みます。例: "search terms"
    • キーワードの前に NOT を付けると、keyword:term フィルタの論理否定に一致します。ANDOR のブール演算子を使用して検索式を結合することもできます。ANDORNOT 演算子の大文字と小文字は区別されません。

    たとえば、NOT column:term は、指定された用語に一致するものを除くすべての列を一覧表示します。

  6. 検索したリソースの詳細を表示するには、検索結果でリソース名をクリックします。エントリの詳細ページが開きます。

gcloud

リソースを検索するには、gcloud dataplex entries search コマンドを使用します。

C#

C#

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

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

using Google.Api.Gax;
using Google.Api.Gax.ResourceNames;
using Google.Cloud.Dataplex.V1;
using System;

public sealed partial class GeneratedCatalogServiceClientSnippets
{
    /// <summary>Snippet for SearchEntries</summary>
    /// <remarks>
    /// This snippet has been automatically generated and should be regarded as a code template only.
    /// It will require modifications to work:
    /// - It may require correct/in-range values for request initialization.
    /// - It may require specifying regional endpoints when creating the service client as shown in
    ///   https://cloud.google.com/dotnet/docs/reference/help/client-configuration#endpoint.
    /// </remarks>
    public void SearchEntriesRequestObject()
    {
        // Create client
        CatalogServiceClient catalogServiceClient = CatalogServiceClient.Create();
        // Initialize request argument(s)
        SearchEntriesRequest request = new SearchEntriesRequest
        {
            LocationName = LocationName.FromProjectLocation("[PROJECT]", "[LOCATION]"),
            Query = "",
            OrderBy = "",
            Scope = "",
            SemanticSearch = false,
        };
        // Make the request
        PagedEnumerable<SearchEntriesResponse, SearchEntriesResult> response = catalogServiceClient.SearchEntries(request);

        // Iterate over all response items, lazily performing RPCs as required
        foreach (SearchEntriesResult item in response)
        {
            // Do something with each item
            Console.WriteLine(item);
        }

        // Or iterate over pages (of server-defined size), performing one RPC per page
        foreach (SearchEntriesResponse page in response.AsRawResponses())
        {
            // Do something with each page of items
            Console.WriteLine("A page of results:");
            foreach (SearchEntriesResult item in page)
            {
                // Do something with each item
                Console.WriteLine(item);
            }
        }

        // Or retrieve a single page of known size (unless it's the final page), performing as many RPCs as required
        int pageSize = 10;
        Page<SearchEntriesResult> singlePage = response.ReadPage(pageSize);
        // Do something with the page of items
        Console.WriteLine($"A page of {pageSize} results (unless it's the final page):");
        foreach (SearchEntriesResult item in singlePage)
        {
            // Do something with each item
            Console.WriteLine(item);
        }
        // Store the pageToken, for when the next page is required.
        string nextPageToken = singlePage.NextPageToken;
    }
}

Go

Go

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

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


//go:build examples

package main

import (
	"context"

	dataplex "cloud.google.com/go/dataplex/apiv1"
	dataplexpb "cloud.google.com/go/dataplex/apiv1/dataplexpb"
	"google.golang.org/api/iterator"
)

func main() {
	ctx := context.Background()
	// This snippet has been automatically generated and should be regarded as a code template only.
	// It will require modifications to work:
	// - It may require correct/in-range values for request initialization.
	// - It may require specifying regional endpoints when creating the service client as shown in:
	//   https://pkg.go.dev/cloud.google.com/go#hdr-Client_Options
	c, err := dataplex.NewCatalogClient(ctx)
	if err != nil {
		// TODO: Handle error.
	}
	defer c.Close()

	req := &dataplexpb.SearchEntriesRequest{
		// TODO: Fill request struct fields.
		// See https://pkg.go.dev/cloud.google.com/go/dataplex/apiv1/dataplexpb#SearchEntriesRequest.
	}
	it := c.SearchEntries(ctx, req)
	for {
		resp, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			// TODO: Handle error.
		}
		// TODO: Use resp.
		_ = resp

		// If you need to access the underlying RPC response,
		// you can do so by casting the `Response` as below.
		// Otherwise, remove this line. Only populated after
		// first call to Next(). Not safe for concurrent access.
		_ = it.Response.(*dataplexpb.SearchEntriesResponse)
	}
}

Java

Java

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

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

import com.google.cloud.dataplex.v1.CatalogServiceClient;
import com.google.cloud.dataplex.v1.LocationName;
import com.google.cloud.dataplex.v1.SearchEntriesRequest;
import com.google.cloud.dataplex.v1.SearchEntriesResult;

public class SyncSearchEntries {

  public static void main(String[] args) throws Exception {
    syncSearchEntries();
  }

  public static void syncSearchEntries() throws Exception {
    // This snippet has been automatically generated and should be regarded as a code template only.
    // It will require modifications to work:
    // - It may require correct/in-range values for request initialization.
    // - It may require specifying regional endpoints when creating the service client as shown in
    // https://cloud.google.com/java/docs/setup#configure_endpoints_for_the_client_library
    try (CatalogServiceClient catalogServiceClient = CatalogServiceClient.create()) {
      SearchEntriesRequest request =
          SearchEntriesRequest.newBuilder()
              .setName(LocationName.of("[PROJECT]", "[LOCATION]").toString())
              .setQuery("query107944136")
              .setPageSize(883849137)
              .setPageToken("pageToken873572522")
              .setOrderBy("orderBy-1207110587")
              .setScope("scope109264468")
              .setSemanticSearch(true)
              .build();
      for (SearchEntriesResult element : catalogServiceClient.searchEntries(request).iterateAll()) {
        // doThingsWith(element);
      }
    }
  }
}

Node.js

Node.js

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

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

/**
 * This snippet has been automatically generated and should be regarded as a code template only.
 * It will require modifications to work.
 * It may require correct/in-range values for request initialization.
 * TODO(developer): Uncomment these variables before running the sample.
 */
/**
 *  Required. The project to which the request should be attributed in the
 *  following form: `projects/{project}/locations/global`.
 */
// const name = 'abc123'
/**
 *  Required. The query against which entries in scope should be matched.
 *  The query syntax is defined in Search syntax for Dataplex Universal
 *  Catalog (https://cloud.google.com/dataplex/docs/search-syntax).
 */
// const query = 'abc123'
/**
 *  Optional. Number of results in the search page. If <=0, then defaults
 *  to 10. Max limit for page_size is 1000. Throws an invalid argument for
 *  page_size > 1000.
 */
// const pageSize = 1234
/**
 *  Optional. Page token received from a previous `SearchEntries` call. Provide
 *  this to retrieve the subsequent page.
 */
// const pageToken = 'abc123'
/**
 *  Optional. Specifies the ordering of results.
 *  Supported values are:
 *  * `relevance`
 *  * `last_modified_timestamp`
 *  * `last_modified_timestamp asc`
 */
// const orderBy = 'abc123'
/**
 *  Optional. The scope under which the search should be operating. It must
 *  either be `organizations/<org_id>` or `projects/<project_ref>`. If it is
 *  unspecified, it defaults to the organization where the project provided in
 *  `name` is located.
 */
// const scope = 'abc123'
/**
 *  Optional. Specifies whether the search should understand the meaning and
 *  intent behind the query, rather than just matching keywords.
 */
// const semanticSearch = true

// Imports the Dataplex library
const {CatalogServiceClient} = require('@google-cloud/dataplex').v1;

// Instantiates a client
const dataplexClient = new CatalogServiceClient();

async function callSearchEntries() {
  // Construct request
  const request = {
    name,
    query,
  };

  // Run request
  const iterable = dataplexClient.searchEntriesAsync(request);
  for await (const response of iterable) {
      console.log(response);
  }
}

callSearchEntries();

PHP

PHP

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

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

use Google\ApiCore\ApiException;
use Google\ApiCore\PagedListResponse;
use Google\Cloud\Dataplex\V1\Client\CatalogServiceClient;
use Google\Cloud\Dataplex\V1\SearchEntriesRequest;
use Google\Cloud\Dataplex\V1\SearchEntriesResult;

/**
 * Searches for Entries matching the given query and scope.
 *
 * @param string $formattedName The project to which the request should be attributed in the
 *                              following form: `projects/{project}/locations/global`. Please see
 *                              {@see CatalogServiceClient::locationName()} for help formatting this field.
 * @param string $query         The query against which entries in scope should be matched.
 *                              The query syntax is defined in [Search syntax for Dataplex Universal
 *                              Catalog](https://cloud.google.com/dataplex/docs/search-syntax).
 */
function search_entries_sample(string $formattedName, string $query): void
{
    // Create a client.
    $catalogServiceClient = new CatalogServiceClient();

    // Prepare the request message.
    $request = (new SearchEntriesRequest())
        ->setName($formattedName)
        ->setQuery($query);

    // Call the API and handle any network failures.
    try {
        /** @var PagedListResponse $response */
        $response = $catalogServiceClient->searchEntries($request);

        /** @var SearchEntriesResult $element */
        foreach ($response as $element) {
            printf('Element data: %s' . PHP_EOL, $element->serializeToJsonString());
        }
    } catch (ApiException $ex) {
        printf('Call failed with message: %s' . PHP_EOL, $ex->getMessage());
    }
}

/**
 * Helper to execute the sample.
 *
 * This sample has been automatically generated and should be regarded as a code
 * template only. It will require modifications to work:
 *  - It may require correct/in-range values for request initialization.
 *  - It may require specifying regional endpoints when creating the service client,
 *    please see the apiEndpoint client configuration option for more details.
 */
function callSample(): void
{
    $formattedName = CatalogServiceClient::locationName('[PROJECT]', '[LOCATION]');
    $query = '[QUERY]';

    search_entries_sample($formattedName, $query);
}

Python

Python

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

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

# This snippet has been automatically generated and should be regarded as a
# code template only.
# It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
#   client as shown in:
#   https://googleapis.dev/python/google-api-core/latest/client_options.html
from google.cloud import dataplex_v1


def sample_search_entries():
    # Create a client
    client = dataplex_v1.CatalogServiceClient()

    # Initialize request argument(s)
    request = dataplex_v1.SearchEntriesRequest(
        name="name_value",
        query="query_value",
    )

    # Make the request
    page_result = client.search_entries(request=request)

    # Handle the response
    for response in page_result:
        print(response)

Ruby

Ruby

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

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

require "google/cloud/dataplex/v1"

##
# Snippet for the search_entries call in the CatalogService service
#
# This snippet has been automatically generated and should be regarded as a code
# template only. It will require modifications to work:
# - It may require correct/in-range values for request initialization.
# - It may require specifying regional endpoints when creating the service
# client as shown in https://cloud.google.com/ruby/docs/reference.
#
# This is an auto-generated example demonstrating basic usage of
# Google::Cloud::Dataplex::V1::CatalogService::Client#search_entries.
#
def search_entries
  # Create a client object. The client can be reused for multiple calls.
  client = Google::Cloud::Dataplex::V1::CatalogService::Client.new

  # Create a request. To set request fields, pass in keyword arguments.
  request = Google::Cloud::Dataplex::V1::SearchEntriesRequest.new

  # Call the search_entries method.
  result = client.search_entries request

  # The returned object is of type Gapic::PagedEnumerable. You can iterate
  # over elements, and API calls will be issued to fetch pages as needed.
  result.each do |item|
    # Each element is of type ::Google::Cloud::Dataplex::V1::SearchEntriesResult.
    p item
  end
end

REST

リソースを検索するには、searchEntries メソッドを使用します。

キーワードのみの検索構文

正確な検索を行うには、修飾子、論理演算子、アスペクト検索など、特定の構文を使用してクエリを作成します。

修飾された述語

述語の先頭にキーを付けて修飾すると、照合範囲を特定のメタデータ部分に限定できます。

  • 等号(=)は、検索の対象を完全一致に制限します。
  • キーの後のコロン(:)は、述語を検索結果内の値に含まれる部分文字列またはトークンと照合します。

トークン化により、テキストのストリームが一連のトークン(各トークンは通常 1 つの単語に対応)に分割されます。

述語キー typesystemlocationorgid は、部分文字列修飾子(:)ではなく、完全一致修飾子(=)のみをサポートします(例: type=fooorgid=number)。

Knowledge Catalog のキーワード検索では、次の修飾子がサポートされています。

限定子 説明
name:x x をリソース ID の部分文字列として一致させます。
displayname:x x をリソースの表示名の部分文字列と照合します。
column:x x をリソースのスキーマの列名(またはネストされた列名)の部分文字列として一致させます。
description:x x をリソースの説明のトークンとして一致させます。
label:bar ラベル(値があるもの)を持つ BigQuery リソースと一致させます。ラベルキーには部分文字列として bar があります。
label=bar ラベル(値があるもの)を持つ BigQuery リソースと一致させます。ラベルキーは文字列として bar と等しくなります。
label:bar:x x を BigQuery リソースにアタッチされたキー bar を含むラベルの値の部分文字列として一致させます。
label=foo:bar キーが foo でキー値が bar である BigQuery リソースと一致させます。
label.foo=bar キーが foo でキー値が bar である BigQuery リソースと一致させます。
label.foo ラベルを持ち、ラベルキーが文字列として foo と等しい BigQuery リソースと一致させます。
type=TYPE 特定のエントリタイプまたはそのタイプ エイリアスのリソースと一致させます。
projectid:bar ID の部分文字列として bar と一致する Google Cloud プロジェクト内のリソースと一致させます。
parent:x x をリソースの階層パスの部分文字列として一致させます。親パスは、親リソースの fully_qualified_name です。
orgid=number Google Cloud 組織内のリソースを number の正確な ID 値と一致させます。
system=SYSTEM 指定されたシステムのリソースを一致させます。
location=LOCATION

指定されたロケーションのリソースを正確な名前と一致させます。たとえば、location=us-central1 はアイオワでホストされているアセットに一致します。

BigQuery Omni アセットは、BigQuery Omni のロケーション名を使用してこの修飾子をサポートしています。たとえば、location=aws-us-east-1 は北バージニアの BigQuery Omni アセットに一致します。

createtime

指定した日時以前または以降に作成されたリソースを検索します。

例:

  • createtime:2019-01-01 は、2019 年 1 月 1 日に作成されたリソースに一致します。
  • createtime<2019-02 は、2019 年 2 月 1 日 00:00:00 以前に作成されたリソースに一致します。
  • createtime>2019-02 は、2019 年 2 月 1 日 00:00:00 以降に作成されたリソースに一致します。

タイムスタンプ形式(YYYY-MM-DDThh:mm:ss

すべてのタイムスタンプは GMT にする必要があります(タイムゾーンはサポートされていません)。部分的なタイムスタンプ、ハイフン(-)の日付区切り文字、スラッシュ(/)の日付区切り文字がサポートされています。

例:

  • 2010-10-22T05:36:24
  • 2010-10-22T05:36
  • 2010-10-22T05
  • 2010-10-22
  • 2010-10
  • 2010
  • 2010/10/22
updatetime

指定した日時以前または以降に更新されたリソースを検索します。

例:

  • updatetime:2019-01-01 は、2019 年 1 月 1 日に更新されたリソースに一致します。
  • updatetime<2019-02 は、2019 年 2 月 1 日 00:00:00 以前に更新されたリソースに一致します。
  • updatetime>2019-02 は、2019 年 2 月 1 日 00:00:00 以降に更新されたリソースに一致します。

タイムスタンプ形式(YYYY-MM-DDThh:mm:ss

すべてのタイムスタンプは GMT にする必要があります(タイムゾーンはサポートされていません)。部分的なタイムスタンプ、ハイフン(-)の日付区切り文字、スラッシュ(/)の日付区切り文字がサポートされています。

例:

  • 2010-10-22T05:36:24
  • 2010-10-22T05:36
  • 2010-10-22T05
  • 2010-10-22
  • 2010-10
  • 2010
  • 2010/10/22
fully_qualified_name:x xfully_qualified_name の部分文字列として一致させます。
fully_qualified_name=x xfully_qualified_name として一致させます。

付加されたアスペクトに基づいてエントリを検索するには、次のクエリ構文を使用します。

修飾子 説明
aspect:x エントリにアタッチされているアスペクトのアスペクト タイプの完全パスの部分文字列として x と一致させます(projectid.location.ASPECT_TYPE_ID 形式)。
aspect=x エントリにアタッチされているアスペクトのアスペクト タイプの完全パスとして x と一致させます(projectid.location.ASPECT_TYPE_ID 形式)。
aspect:xOPERATORvalue

アスペクト フィールドの値を検索します。エントリにアタッチされているアスペクトのアスペクト タイプとフィールド名の完全パスの部分文字列として x と一致させます(projectid.location.ASPECT_TYPE_ID.FIELD_NAME 形式)。

サポートされる演算子のリストは、次のようにアスペクト内のフィールドのタイプによって異なります。

  • 文字列: =(完全一致)と :(部分文字列)
  • すべての数値タイプ: =:<><=>==>=<
  • 列挙型: =
  • 日時: 数値の場合と同じですが、比較する値は数値ではなく日時として扱われます。
  • ブール値: =

検索できるのは、アスペクトの最上位フィールドのみです。

たとえば、次のクエリはすべて、employee-info アスペクトの is-enrolled フィールドの値が true であるエントリに一致します。部分文字列に一致するほかのエントリも返されます。

  • aspect:example-project.us-central1.employee-info.is-enrolled=true
  • aspect:example-project.us-central1.employee=true
  • aspect:employee=true

論理演算子

クエリは、論理演算子 ANDORNOT でリンクされた複数の述語で構成できます。

  • 演算子を指定しないと、論理 AND が使用されます。たとえば、foo bar は、述語 foo と述語 bar の両方に一致するリソースを返します。
  • 述語を否定するには、-(ハイフン)または NOT 接頭辞を使用します。たとえば、-name:foo は、述語 foo と一致しない名前のリソースを返します。

キーワードのみの検索では、論理演算子で大文字と小文字は区別されません。

簡略構文

クエリで簡略構文を使用するには、OR 演算子には |(垂直バー)を、AND 演算子には ,(カンマ)を使用します。この簡略構文は、label を除く修飾された述語で使用できます。

次の例は、キーワードのみの検索で簡略構文を使用する方法を示しています。

  • OR 演算子を使用して、複数のプロジェクトの 1 つのエントリを検索する

    projectid:(id1|id2|id3|id4)
    

    簡略構文を使用しない同じ検索は次のようになります。

    projectid:id1 OR projectid:id2 OR projectid:id3 OR projectid:id4
    
  • 列名が一致するエントリを検索します。

    • AND: column:(name1,name2,name3)
    • OR: column:(name1|name2|name3)

次のステップ