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

注意： 如要查詢 Knowledge Catalog 資料，請使用 Knowledge Catalog 搜尋功能。僅為回溯相容性而使用僅限關鍵字的搜尋。

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

事前準備

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

必要的角色

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

• 搜尋項目：
  • Dataplex Catalog 管理員 (roles/dataplex.catalogAdmin) (用於搜尋的專案)
  • Dataplex Catalog 編輯者 (roles/dataplex.catalogEditor) 在用於搜尋的專案中
  • Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer) 在用於搜尋的專案中
• 搜尋 BigQuery 資料集和資料表的中繼資料： 資料集或資料表上的 BigQuery 中繼資料檢視者 (roles/bigquery.metadataViewer)
• 搜尋自訂項目： 專案的 Dataplex Catalog 檢視者 (roles/dataplex.catalogViewer)

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

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

使用僅限關鍵字的搜尋

控制台

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

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

   前往「Search」(搜尋) 頁面

2. 如果搜尋平台設為「Data Catalog」，請在「選擇搜尋平台」選單中選取「Knowledge Catalog」。

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

4. 如要修正搜尋範圍，請使用「篩選器」面板。可用的篩選器如下：

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

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

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

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

   請參考下列訣竅建構搜尋查詢：

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

   舉例來說，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

在試用這個範例之前，請先按照「使用用戶端程式庫的 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	將 x 做為資源 ID 的子字串比對。
displayname:x	將 x 做為資源顯示名稱的子字串比對。
column:x	將 x 做為資源結構定義中資料欄名稱 (或巢狀資料欄名稱) 的子字串比對。
description:x	將 x 做為資源說明中的符記比對。
label:bar	符合條件的 BigQuery 資源必須具有標籤 (具有某些值)，且標籤鍵包含 bar 做為子字串。
label=bar	比對具有標籤 (具有某些值) 的 BigQuery 資源，且標籤鍵等於 bar 字串。
label:bar:x	比對附加至 BigQuery 資源的標籤 (鍵為 bar) 值中的子字串 x。
label=foo:bar	符合鍵等於 foo 且鍵值等於 bar 的 BigQuery 資源。
label.foo=bar	符合鍵等於 foo 且鍵值等於 bar 的 BigQuery 資源。
label.foo	比對具有標籤的 BigQuery 資源，標籤的鍵等於 foo (以字串形式表示)。
type=TYPE	比對特定項目類型或類型別名的資源。
projectid:bar	比對 Google Cloud 專案中的資源，這些專案的 ID 包含 bar 做為子字串。
parent:x	將 x 做為資源階層式路徑的子字串比對。父項路徑是父項資源的 fully_qualified_name。
orgid=number	符合 ID 值為 number 的機構內資源。 Google Cloud
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-02-01T00: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 支援的運算子清單取決於層面中的欄位類型，如下所示： 字串：= (完全比對) 和 : (子字串) 所有數字類型：=、:、<、>、<=、>=、=>、=< 列舉：= 日期時間：與數字相同，但要比較的值會視為日期時間，而非數字 布林值：= 只有層面頂層欄位可供搜尋。 舉例來說，下列所有查詢都會比對項目，其中 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)

後續步驟

• 進一步瞭解 Knowledge Catalog 中的中繼資料管理功能。
• 瞭解如何使用層面，透過中繼資料擴充項目和項目連結。
• 瞭解如何管理項目及擷取自訂來源。