在 Knowledge Catalog 中使用僅限關鍵字的搜尋功能

在 Knowledge Catalog 中使用僅限關鍵字的搜尋功能，透過特定關鍵字、篩選器和定義的語法尋找資源。僅限關鍵字的搜尋功能可精確控管搜尋查詢，並根據中繼資料欄位縮小搜尋結果範圍。

事前準備

執行搜尋前，請確認您已獲派必要角色，並啟用必要的 API。

必要的角色

如要取得在 Knowledge Catalog 中搜尋項目及存取搜尋結果所需的權限，請要求管理員授予您下列 IAM 角色：

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

使用僅限關鍵字的搜尋

控制台

如要使用關鍵字搜尋資源，請按照下列步驟操作：

  1. 前往 Google Cloud 控制台的 Knowledge Catalog「Search」(搜尋) 頁面。

    前往「Search」(搜尋) 頁面

  2. 在「尋找各項專案的資源」欄位中輸入查詢。

  3. 如要縮小搜尋範圍，請使用「篩選條件」面板。可用的篩選器如下：

    • 「系統」會列出可用的系統，例如 BigQuery 或 Cloud SQL。Knowledge Catalog 系統含有自訂項目。
    • 切面可讓您查詢使用特定範本標記的資產。您可以使用「自訂」選單進一步修正結果，並依特定層面值篩選。
    • 「專案」會列出可將搜尋範圍限定於其中的專案。
    • 型別別名是與項目類型相關聯的資料型別。項目類型可能有名為 projects/test-project/locations/us/entryTypes/my-entry-type 的名稱，但您可以使用類型別名 TABLE 或 DATABASE 搜尋。您可以在建立或更新項目類型時，設定一或多個型別別名。
    • 資料集來自 BigQuery。

    您可以手動新增下列篩選器：

    • 新增專案篩選器：在「專案」中，按一下「新增專案」。搜尋特定專案，選取專案，然後按一下「開啟」。
    • 新增切面類型篩選器：在「切面」中，按一下「新增更多切面類型」選單。搜尋並選取特定範本，然後按一下「確定」。

  4. 選用：除了可用的資產外，您也可以選取「Include public datasets」(納入公開資料集)，搜尋 Google Cloud 中公開提供的資源。

    請參考下列提示建構搜尋查詢：

    • 如果搜尋運算式含有空格，請在前後加上引號。例如 "search terms"。
    • 在關鍵字前面加上 NOT，即可比對 keyword:term 篩選器的邏輯否定。您也可以使用 AND 和 OR 布林運算子，合併搜尋運算式。AND、OR 和 NOT 運算子不區分大小寫。

    舉例來說，NOT column:term 會列出所有資料欄，但符合指定字詞的資料欄除外。

  5. 如要查看搜尋資源的詳細資訊，請在搜尋結果中點選資源名稱。系統會開啟項目詳細資料頁面。

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

在試用這個範例之前，請先按照「使用用戶端程式庫的 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 方法。

僅限關鍵字的搜尋語法

如要精確搜尋，可以使用特定語法建構查詢，包括限定詞、邏輯運算子和面向搜尋。

具有限定詞的述詞

您可以在述詞前面加上鍵，限制比對特定中繼資料：

  • 等號 (=) 會將搜尋範圍限制為完全比對。
  • 鍵後方的半形冒號 (:) 會將述詞比對至搜尋結果值中的子字串或符記。

斷詞會將文字串流分割成一系列詞元，每個詞元通常對應一個字詞。

述詞鍵 type、system、location 和 orgid 僅支援完全比對 (=) 限定詞，不支援子字串限定詞 (:)。例如 type=foo 或 orgid=number。

Knowledge Catalog 關鍵字搜尋支援下列限定詞：

限定詞 說明
name:x 與資源 ID 的子字串 x 相符。
displayname:x 與資源顯示名稱的子字串相符。x
column:x 與資源結構定義中的資料欄名稱 (或巢狀資料欄名稱) 的子字串 x 相符。
description:x 比對資源說明中的 x 符記。
label:bar 比對具有標籤 (含某個值) 的 BigQuery 資源，且標籤鍵含有 bar 子字串。
label=bar 比對具有標籤 (含某些值) 的 BigQuery 資源，且標籤鍵等於字串 bar。
label:bar:x 比對 x 是否為標籤值中的子字串，該標籤的鍵為 bar，且附加至 BigQuery 資源。
label=foo:bar 符合鍵等於 foo 且鍵值等於 bar 的 BigQuery 資源。
label.foo=bar 比對鍵等於 foo 且鍵值等於 bar 的 BigQuery 資源。
label.foo 比對標籤鍵等於 foo (字串) 的 BigQuery 資源。
type=TYPE 符合特定項目類型或其類型別名的資源。
projectid:bar 比對 Google Cloud 專案中 ID 包含bar子字串的資源。
parent:x 比對 x 是否為資源階層式路徑的子字串。父項路徑是父項資源的 fully_qualified_name。
orgid=number 在 Google Cloud 機構中，比對 ID 值與 number 完全相符的資源。
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-02-01T00: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-02-01T00:00:00 前更新的資源。
  • updatetime>2019-02 會比對 2019-02-01T00: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 x 是 fully_qualified_name 的子字串。
fully_qualified_name=x 符合 x 的 fully_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

支援的運算子清單取決於切面中的欄位類型，如下所示：

  • 字串：= (完全比對) 和 : (子字串)
  • 所有數字類型：=、:、<、>、<=、>=、=>、=<
  • Enum：=
  • 日期時間：與數字相同，但要比較的值會視為日期時間，而非數字
  • 布林值：=

只有切面的頂層欄位可供搜尋。

舉例來說，下列所有查詢都會比對 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

邏輯運算子

查詢可由多個述詞組成，並以邏輯運算子 AND、OR 或 NOT 連結。

  • 如果您未指定運算子，則默示使用邏輯 AND。舉例來說，foo bar 會傳回符合述詞 foo 和述詞 bar 的資源。
  • 使用 - (連字號) 或 NOT 前置字元否定述詞。例如，-name:foo 會傳回名稱不符合述詞 foo 的資源。

在僅限關鍵字的搜尋中，邏輯運算子不區分大小寫。

簡短語法

如要在查詢中使用縮寫語法，請以 | (垂直線) 代表 OR 運算子，並以 , (逗號) 代表 AND 運算子。除了 label 以外，縮寫語法適用於具有限定詞的述詞。

下列範例說明如何搭配僅限關鍵字的搜尋使用縮寫語法。

  • 使用 OR 運算子在多個專案中搜尋項目

    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)

後續步驟