此页面由 Cloud Translation API 翻译。

使用 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 IAM 角色。
如需搜索项目或组织中的所有资源，您需要具备 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 中公开提供的数据。

您可以组合使用多个部分中的过滤条件，以查找与所选每个部分中的至少一个条件匹配的素材资源。系统会使用 OR 逻辑运算符评估单个部分中选择的多个过滤条件。例如，请考虑以下过滤器组合：

Data Catalog 会查找以下内容：

标记了 MyTemplate1 模板的 BigQuery 数据集。
标记了 MyTemplate2 模板的 BigQuery 数据集。
标记了 MyTemplate1 模板的 BigQuery 表。
标记了 MyTemplate2 模板的 BigQuery 表。

按标记值过滤

借助标记过滤条件，您可以查询使用特定模板标记的资源。您可以使用 Customize 菜单进一步优化结果，并按特定标记值进行过滤。标记值过滤条件取决于该标记字段的数据类型。例如，对于日期时间字段和数字字段，您可以指定特定日期或日期范围。

过滤条件公开范围

每个部分中显示的过滤条件取决于搜索框中的当前查询。整个搜索结果集中可能包含与当前查询匹配的条目，但与这些条目对应的过滤条件可能不会显示在过滤条件窗格中。

搜索数据资源

控制台

在 Google Cloud 控制台中，转到 Dataplex 搜索页面。

转到“Dataplex 搜索”
对于选择搜索平台，请选择 Data Catalog 作为搜索模式。
在搜索字段中输入查询，或使用过滤条件窗格优化搜索参数。

您可以手动添加以下过滤条件：
- 在项目中，添加项目过滤条件。点击添加项目，搜索并选择特定项目，然后点击打开。
- 在标记中，添加标记模板过滤条件。点击添加更多标记模板菜单，搜索并选择特定模板，然后点击确定。
如需搜索 Google Cloud 中公开提供的数据资产以及您可以使用的资源，请选择包括公共数据集

此外，您还可以执行以下操作：

在搜索字段中为搜索字词添加 keyword:value 来过滤搜索：

关键字说明

name: 匹配数据资源名称

column: 匹配列名称或嵌套列名称

description: 匹配表的说明

关键字	说明
`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 搜索语法。

搜索示例

假设您要搜索在使用 Data Catalog 标记 BigQuery 表中设置的 trips 表，请按以下步骤操作：

在搜索字段中输入 trips，然后点击搜索。
在过滤条件窗格中，选择以下内容：
- 在系统部分中，选择 BigQuery，以排除属于其他系统的同名数据资源。
- 在项目部分中选择您的项目 ID，以排除其他项目中的数据资源。如果系统未显示您的项目，请点击添加项目，然后选择您的项目。
- 在标记部分中，选择演示标记模板，检查使用此模板的标记是否已附加到 trips 表中。如果此模板未显示，请点击添加更多标记模板，搜索并选择该标记模板，然后点击确定。

通过所有选定的过滤条件，搜索结果应只包含一个条目，即您的项目中的 BigQuery trips 表，并附加了使用 Demo Tag Template 模板的标记：

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 参考文档。

如需向 Data Catalog 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

// 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 参考文档。

如需向 Data Catalog 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。

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 方法和网址：

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"
    }
  ]
}

查看表详情

使用 Data Catalog 查看表的详细信息。

在 Google Cloud 控制台中，转到 Dataplex 搜索页面。

转到 Data Catalog 搜索
对于选择搜索平台，请选择 Data Catalog 作为搜索模式。
在搜索框中，输入包含表的数据集的名称。

例如，如果您已完成使用 Data Catalog 标记 BigQuery 表快速入门，则可以搜索 demo-dataset 并选择 trips 表。
点击表。

系统随即会打开 BigQuery 表详情页面。

表的详细信息包括以下部分：

BigQuery 表详情。包括创建时间、上次修改时间、到期时间、资源网址和标签等信息。
标记。列出已应用的代码。您可以在此页面修改代码并查看代码模板。点击操作图标。
架构和列标记。列出应用的架构及其值。

为您喜爱的条目加星标并搜索它们

如果您经常浏览相同的数据资产，可以使用星号标记它们，在个性化列表中添加它们的条目。

在 Google Cloud 控制台中，前往 Dataplex 搜索页面。

转到 Data Catalog 搜索
对于选择搜索平台，请选择 Data Catalog 作为搜索模式。
找到您的资源，然后通过以下两种方式之一为其条目加星标：
- 点击搜索结果中条目旁边的。
- 点击条目名称以打开其详情页面，然后点击顶部操作栏上的 STAR。

您最多可以为 200 个条目加星标。

在搜索栏中输入搜索查询之前，加星标的条目会显示在搜索页面上的加星标的条目列表中。此列表仅对您可见。

如需仅搜索加星标的条目，请在过滤条件窗格中的范围部分，选择加星标。

您还可以使用 Data Catalog API 的相应方法为条目加星标和移除星标。搜索资源时，请使用 scope 对象中的 starredOnly 参数。如需了解详情，请参阅 catalog.search 方法。

后续步骤

了解 Data Catalog 的搜索语法。
了解如何在 Dataplex Catalog 中搜索资源。

使用 Data Catalog 搜索数据资源

搜索范围

搜索中的召回率问题

使用 admin_search 标志

日期分片表

过滤条件

按标记值过滤

过滤条件公开范围

搜索数据资源

控制台

控制台

搜索表达式提示

搜索示例

Java

Node.js

Python

REST 和命令行

REST

1. 搜索目录

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

查看表详情

为您喜爱的条目加星标并搜索它们

后续步骤

使用 `admin_search` 标志