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

本文档介绍了如何使用 Data Catalog 搜索数据资源,例如:

  • Analytics Hub 关联的数据集
  • BigQuery 数据集、表、视图和模型
  • Data Catalog 标记模板、条目组和自定义条目
  • Dataplex 数据湖、可用区、表和文件集
  • Dataproc Metastore 服务、数据库和表
  • Pub/Sub 数据流
  • 连接到 Data Catalog 的企业数据孤岛中的资产
  • Bigtable 实例、集群和表(包括列族详细信息)
  • Vertex AI 模型、数据集和 Vertex AI Feature Store 资源
  • Spanner 实例、数据库、表和视图

搜索范围

您可能会看到不同的搜索结果,具体取决于您的权限。 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 标志可保证完全召回率。管理员搜索要求对搜索范围内的所有项目和组织设置datacatalog.catalogs.searchAll权限。使用 admin_search 时,系统只允许使用 defaultorderBy

日期分片表

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 表。

按标记值过滤

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

过滤条件可见性

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

如何搜索数据资产

控制台

控制台

  1. 如需在 Google Cloud 控制台中启动 Dataplex 搜索查询,请转到 Dataplex Search 页面。

    转到 Dataplex Search

  2. 在搜索字段中输入您的查询,或使用过滤条件面板优化搜索参数。

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

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

此外,您可以:

  • 选中包括公共数据集,即可搜索在 Google Cloud 中公开提供的数据资源以及您可以使用的资源。

搜索示例

例如,要搜索您在配置代码模板、标记、概览和数据管理员中设置的 trips 表,请执行以下操作:

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

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

此外,您还可以执行以下操作:

  1. 在搜索字段中向搜索字词添加 keyword:value 可过滤搜索:

    关键字说明
    name: 匹配数据资源名称
    column: 匹配列名称或嵌套列名称
    description: 匹配表的说明

  2. 执行标记搜索,在搜索字段中为您的搜索字词添加以下标记关键字前缀之一:

    标记说明
    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

在试用此示例之前,请按照 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"
    ]
  }
}

如需发送您的请求,请展开以下选项之一:

您应该收到类似以下内容的 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 查看表的详细信息。

  1. 转到 Dataplex 搜索页面。

    转到 Data Catalog

  2. 在搜索框中,输入包含表的数据集的名称。

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

  3. 点击表。

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

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

  • BigQuery 表详情。包括创建时间、上次修改时间、到期时间、资源网址、标签等信息。

  • 标记。列出已应用的标记。您可以在此页面中修改标记并查看标记模板。点击 操作图标。

  • 架构和列标记。列出已应用的架构及其值。

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

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

  1. 转到 Dataplex 搜索页面并找到您的资产。

    转到 Data Catalog

  2. 通过以下两种方式之一为其条目加星标:

    • 点击搜索结果中条目旁边的 图标。
    • 点击条目名称以打开其详情页面,然后点击顶部操作栏上的 加星标按钮。

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

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

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

您还可以使用 Data Catalog API 的相应方法为条目加星标和移除星标。搜索资产时,请在 scope 对象中使用 starredOnly 参数。请参阅 catalog.search 方法