此页面由 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 角色。
如需搜索项目或组织内的所有资源，您需要拥有 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 表。

按标记值过滤

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

过滤条件显示设置

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

如何搜索数据资产

控制台

如需在 Google Cloud 控制台中启动 Dataplex 搜索查询，请前往 Dataplex 搜索页面。

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

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

在项目中，添加项目过滤条件，方法是点击添加项目按钮，搜索特定项目，选择该项目，然后点击打开。
在代码中，点击添加更多标记模板下拉菜单，搜索并选中特定模板，然后点击确定，使用标记模板进行过滤。

此外，您可以：

勾选包括公共数据集以公开搜索数据资产以及 Google Cloud 中提供的各种资源。

搜索示例

例如，如需搜索您在配置标记模板、标记、概览和数据管家中设置的 trips 表，请执行以下操作：

在搜索字段中输入 trips，然后点击搜索。
在系统部分中选择 BigQuery，以排除属于其他系统的同名数据资源。
在项目部分中选择您的项目 ID，以排除其他项目中的数据资源。如果你的项目未显示在该部分中点击添加项目，然后在对话框窗口中选择该项目。
在标记模板部分中选择演示标记模板，以查看使用此模板的标记是否已附加到 trips 表中。如果此模板未显示在该部分中，请点击添加更多标记下拉列表，找到并选择该模板，然后点击确定。

选中所有过滤条件后，搜索结果将仅包含一个过滤条件条目 - 项目中带有附加标记的 BigQuery trips 表使用 Demo Tag Template。

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

添加 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 搜索语法。

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

在尝试此示例之前，请按照Node.js Data Catalog 快速入门：使用客户端库。如需了解详情，请参阅 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"
    }
  ]
}

查看表详细信息

在 Cloud 控制台中，您可以使用 Data Catalog 查看表的详细信息。

转到 Dataplex 搜索页面。

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

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

此时会打开 BigQuery 表详情页面。

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

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

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

如果您经常浏览相同的数据资产，可以使用星号标记它们，在个性化列表中添加它们的条目。如需在 Dataplex 界面中执行此操作，请执行以下操作：

转到 Dataplex 搜索页面。

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

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

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

如需仅搜索加星标的条目，请在过滤条件面板上选择范围 > 加星标选项。

您还可以使用 Data Catalog API，用于为和删除条目的星标。搜索素材资源时，请在以下位置使用 starredOnly 参数： scope 对象。请参阅 catalog.search 方法。

使用 Data Catalog 搜索和查看数据资源

搜索范围

搜索中的召回率问题

使用 admin_search 标志

日期分片表

过滤条件

按标记值过滤

过滤条件显示设置

如何搜索数据资产

控制台

控制台

搜索示例

搜索表达式提示

Java

Node.js

Python

REST 和命令行

REST

1.搜索目录

curl（Linux、macOS 或 Cloud Shell）

PowerShell (Windows)

查看表详细信息

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

使用 `admin_search` 标志