在 Knowledge Catalog 中使用仅限关键字的搜索

在 Knowledge Catalog 中使用仅限关键字的搜索，以使用特定关键字、过滤条件和定义的语法查找资源。仅限关键字的搜索可让您精确控制搜索查询，并根据元数据字段缩小搜索结果范围。

准备工作

在执行搜索之前，请确保您已被授予所需角色并已启用必要的 API。

所需角色

如需获得在 Knowledge Catalog 中搜索条目和访问搜索结果所需的权限，请让您的管理员为您授予以下 IAM 角色：

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义 角色或其他预定义 角色来获取所需的权限。

使用仅限关键字的搜索

控制台

如需使用关键字搜索来搜索资源，请按照以下步骤操作：

  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 进行搜索。您可以在创建或更新条目类型时设置一个或多个类型别名。
    • 数据集 ，来自 BigQuery。

    您可以手动添加以下过滤条件：

    • 添加项目过滤条件：在项目 中，点击添加项目 。搜索特定项目，选择该项目，然后点击打开 。
    • 添加切面类型过滤条件：在切面 中，点击添加更多切面类型 菜单。搜索特定模板，选择该模板，然后点击确定 。

  5. 可选：除了您可以使用的资产之外，您还可以通过选择 包括公共数据集 来搜索在 Google Cloud 中公开提供的资源。

    使用以下提示构建搜索查询：

    • 如果搜索表达式包含空格，请将其用英文引号括起来。例如，"search terms"。
    • 在关键字前面加上 NOT，以匹配 keyword:term 过滤条件的逻辑否定。您还可以使用 AND 和 OR 布尔运算符来组合搜索表达式。AND、OR 和 NOT 运算符不区分大小写。

    例如，NOT column:term 会列出除与指定术语匹配的列之外的所有列。

  6. 如需查看有关搜索到的资源的更多信息，请在搜索结果中点击资源名称。系统随即会打开条目详情页面。

gcloud

如需搜索资源，请使用 gcloud dataplex entries search 命令。

C#

C#

试用此示例之前，请按照 C# 设置说明进行操作。请按照 Knowledge Catalog 快速入门：使用 客户端库中的说明进行操作。 如需了解详情，请参阅 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

试用此示例之前，请按照 Go 设置说明进行操作。请按照 Knowledge Catalog 快速入门：使用 客户端库中的说明进行操作。 如需了解详情，请参阅 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

试用此示例之前，请按照 Java 设置说明进行操作，具体请参阅 Knowledge Catalog 快速入门：使用 客户端库。 如需了解详情，请参阅 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

试用此示例之前，请按照 Node.js 设置说明进行操作。请按照 Knowledge Catalog 快速入门：使用 客户端库中的说明进行操作。 如需了解详情，请参阅 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

试用此示例之前，请按照 PHP 设置说明进行操作，具体请参阅 Knowledge Catalog 快速入门：使用 客户端库。 如需了解详情，请参阅 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

试用此示例之前，请按照 Python 设置说明进行操作，具体请参阅 Knowledge Catalog 快速入门：使用 使用客户端库。 如需了解详情，请参阅 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

试用此示例之前，请按照 Ruby 设置说明进行操作。请参阅 Knowledge Catalog 快速入门：使用客户端库。如需了解详情，请参阅 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 匹配具有标签（带有某个值）且标签键中含有 bar 作为子字符串的 BigQuery 资源。
label=bar 匹配具有标签（带有某个值）且标签键等于 bar 作为字符串的 BigQuery 资源。
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 匹配 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-01-01 创建的资源。
  • 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-01-01 更新的资源。
  • 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)

后续步骤