Esta página foi traduzida pela API Cloud Translation.

Pesquisar recursos de dados com o Data Catalog

Este documento descreve como usar o Data Catalog para pesquisar recursos de dados.

É possível pesquisar os seguintes recursos de dados:

Conjuntos de dados vinculados ao Analytics Hub
Conjuntos de dados, tabelas, visualizações e modelos do BigQuery
Instâncias, clusters e tabelas do Bigtable (incluindo detalhes do grupo de colunas)
Modelos de tags, grupos de entradas e entradas personalizadas do Data Catalog
Lakes, zonas, tabelas e conjuntos de arquivos do Dataplex
Serviços, bancos de dados e tabelas do Dataproc Metastore
Fluxos de dados do Pub/Sub
Instâncias, bancos de dados, tabelas e visualizações do Spanner
Modelos, conjuntos de dados e recursos do Feature Store da Vertex AI
Recursos em silos de dados corporativos conectados ao Data Catalog

Escopo de pesquisa

Você pode ter resultados de pesquisa diferentes com base nas suas permissões. O escopo dos resultados de pesquisa do Data Catalog é definido de acordo com sua função.

Confira os diferentes tipos de função e permissões do IAM disponíveis para o Data Catalog. Por exemplo, se você tiver acesso de leitura de metadados do BigQuery a um objeto, esse objeto vai aparecer nos resultados da pesquisa do Data Catalog.

A lista a seguir descreve as permissões mínimas necessárias para realizar a pesquisa:

Para pesquisar uma tabela, você precisa da permissão bigquery.tables.get para ela.
Para pesquisar um conjunto de dados, você precisa da permissão bigquery.datasets.get para esse conjunto.
Para pesquisar metadados de um conjunto de dados ou de uma tabela, você precisa do papel do IAM roles/bigquery.metadataViewer.
Para pesquisar todos os recursos em um projeto ou organização, você precisa da permissão datacatalog.catalogs.searchAll. Ele funciona para todos os recursos, independente do sistema de origem.

Se você tiver acesso a uma tabela do BigQuery, mas não ao conjunto de dados que contém essa tabela, ela ainda será exibida como esperado na pesquisa do Data Catalog. A mesma lógica de acesso se aplica a todos os sistemas compatíveis, como o Pub/Sub e o Data Catalog.

Problemas de recuperação na pesquisa

As consultas de pesquisa do Data Catalog não garantem o recall total. É possível que os resultados que correspondem à consulta não sejam retornados, mesmo em páginas de resultados subsequentes. Além disso, se você repetir consultas de pesquisa, os resultados retornados (e não retornados) podem variar.

Se você estiver enfrentando problemas de recall e não precisar buscar os resultados em uma ordem específica, configure o parâmetro orderBy como default ao chamar o método catalog.search.

Use a sinalização `admin_search`.

O uso da flag admin_search na solicitação de pesquisa garante a recuperação completa. A pesquisa do administrador exige que a permissão datacatalog.catalogs.searchAll seja definida em todos os projetos e organizações no escopo da pesquisa. Ao usar admin_search, apenas default orderBy é permitido.

Tabelas fragmentadas por data

O Data Catalog agrega tabelas fragmentadas por data em uma única entrada lógica. Essa entrada tem o mesmo esquema que o fragmento da tabela com a data mais recente e contém informações agregadas sobre o número total de fragmentos. A entrada deriva o nível de acesso dela usando o conjunto de dados a que ela pertence. A pesquisa do Data Catalog mostrará essas entradas lógicas somente se o usuário tiver acesso ao conjunto de dados que as contém. Tabelas individuais fragmentadas por data não ficam visíveis na pesquisa do Data Catalog, mesmo que estejam presentes no Data Catalog e possam receber tags.

Filtros

Os filtros permitem restringir os resultados da pesquisa. Todos os filtros são agrupados em seções:

Escopo para limitar a pesquisa apenas a itens com estrela.
Sistemas, como BigQuery, Pub/Sub, Dataplex, metastore do Dataproc, sistemas personalizados, Vertex AI e o próprio Data Catalog. O sistema do Data Catalog contém conjuntos de arquivos e entradas personalizadas.
Lagos e zonas vêm do Dataplex.
Tipos de dados, como fluxos de dados, conjuntos de dados, data lakes, zonas, conjuntos de arquivos, modelos, tabelas, visualizações, serviços, bancos de dados e tipos personalizados.
Projetos lista todos os projetos disponíveis para você.
Tags lista todos os modelos de tag (e os campos individuais) disponíveis.
Os conjuntos de dados são provenientes do BigQuery e da Vertex AI.
Os conjuntos de dados públicos são dados disponíveis publicamente no BigQuery.

É possível combinar filtros de várias seções para encontrar recursos que correspondam a pelo menos uma condição de cada seção selecionada. Vários filtros selecionados em uma única seção são avaliados usando o operador lógico OR. Por exemplo, considere a seguinte combinação de filtros:

O Data Catalog procura o seguinte:

Conjuntos de dados do BigQuery com a tag do modelo MyTemplate1.
Conjuntos de dados do BigQuery com a tag do modelo MyTemplate2.
Tabelas do BigQuery marcadas com o modelo MyTemplate1.
Tabelas do BigQuery marcadas com o modelo MyTemplate2.

Filtrar por valor da tag

Os filtros Tags permitem consultar recursos marcados com um modelo específico. Use o menu Personalizar para refinar ainda mais os resultados e filtrar por valores de tag específicos. As condições do filtro de valor da tag dependem do tipo de dados do campo. Por exemplo, para campos de data e hora e número, é possível especificar uma data específica ou um intervalo.

Filtra a visibilidade

Os filtros mostrados em cada seção dependem da consulta atual na caixa Pesquisar. Todo o conjunto de resultados da pesquisa pode incluir entradas que correspondem à consulta atual, mas é possível que os filtros que correspondem a essas entradas não sejam exibidos no painel Filtros.

Pesquisar recursos de dados

Console

No console do Google Cloud, acesse a página Pesquisa do Dataplex.

Acessar a Pesquisa do Dataplex
Em Escolher plataforma de pesquisa, selecione Data Catalog como o modo de pesquisa.
No campo de pesquisa, digite sua consulta ou use o painel Filtros para refinar os parâmetros de pesquisa.

É possível adicionar manualmente os seguintes filtros:
- Em Projetos, adicione um filtro de projeto. Clique em Adicionar projeto, pesquise e selecione um projeto específico e clique em Abrir.
- Em Tags, adicione um filtro de modelo de tag. Clique no menu Adicionar mais modelos de tag, pesquise e selecione um modelo específico e clique em OK.
Para pesquisar recursos de dados disponíveis publicamente no Google Cloud, além dos recursos disponíveis para você, selecione Incluir conjuntos de dados públicos.

Além disso, há outras possibilidades:

Filtre a pesquisa adicionando keyword:value aos termos de pesquisa no campo de pesquisa:

Palavra-chave	Descrição
`name:`	Corresponder a um nome de recurso de dados
`column:`	Nome da coluna correspondente ou da coluna aninhada
`description:`	Corresponder à descrição de uma tabela

Você pode fazer uma pesquisa por tag adicionando um dos seguintes prefixos de palavra-chave aos termos de pesquisa:

Tag	Descrição
`tag:project-name.tag_template_name`	Corresponde ao nome da tag.
`tag:project-name.tag_template_name.key`	Corresponder a uma chave de tag
`tag:project-name.tag_template_name.key:value`	Par de `key:string value` tag de correspondência

Dicas de pesquisa por expressão

Insira sua expressão de pesquisa entre aspas ("search terms") se ela contiver espaços.
Você pode preceder uma palavra-chave com "NOT" (tudo em maiúsculas) para corresponder à negação lógica do filtro keyword:term. Também é possível usar os operadores booleanos "AND" e "OR", em letras maiúsculas, para combinar expressões de pesquisa.

Por exemplo, NOT column:term lista todas as colunas, exceto aquelas que correspondem ao termo especificado. Para conferir uma lista de palavras-chave e outros termos que podem ser usados em uma expressão de pesquisa do Data Catalog, consulte Sintaxe de pesquisa do Data Catalog.

Exemplo de pesquisa

Considere um exemplo em que você quer pesquisar a tabela trips que configurou em Marcar uma tabela do BigQuery usando o Data Catalog:

No campo de pesquisa, digite trips e clique em Pesquisar.
No painel Filtros, selecione:
- Na seção Sistemas, selecione BigQuery para excluir recursos de dados com o mesmo nome que pertencem a outros sistemas.
- Na seção Projects, selecione o ID do projeto para excluir recursos de dados de outros projetos. Se o projeto não aparecer, clique em Adicionar projeto e selecione o projeto.
- Na seção Tags, selecione Modelo de tag de demonstração para verificar se uma tag que usa esse modelo está anexada à tabela trips. Se esse modelo não for exibido, clique em Adicionar mais modelos de tag, pesquise e selecione o modelo de tag e clique em OK.

Com todos os filtros selecionados, os resultados da pesquisa contêm apenas uma entrada: a tabela trips do BigQuery no projeto com uma tag anexada que usa o modelo Demo Tag Template.

Java

Antes de testar este exemplo, siga as instruções de configuração do Java no Guia de início rápido do Data Catalog: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Catalog Java.

Para autenticar no Data Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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

Antes de testar este exemplo, siga as instruções de configuração do Node.js no Guia de início rápido do Data Catalog: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Catalog Node.js.

Para autenticar no Data Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

// 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

Antes de testar este exemplo, siga as instruções de configuração do Python no Guia de início rápido do Data Catalog: como usar as bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Data Catalog Python.

Para autenticar no Data Catalog, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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 e LINHA DE CMD

REST

Se você não tiver acesso às bibliotecas do Cloud Client para seu idioma ou querer testar a API usando solicitações REST, consulte os exemplos a seguir e consulte a documentação da API REST do Data Catalog.

1. Pesquisar no catálogo

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

organization-id: ID da organização do GCP
project-id: ID de projeto do GCP.

Método HTTP e URL:

POST https://datacatalog.googleapis.com/v1/catalog:search

Corpo JSON da solicitação:

{
  "query":"trips",
  "scope":{
    "includeOrgIds":[
      "organization-id"
    ]
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

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)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$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

Você receberá uma resposta JSON semelhante a esta:

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

Ver detalhes da tabela

Use o Data Catalog para conferir os detalhes da tabela.

No console do Google Cloud, acesse a página Pesquisa do Dataplex.

Acessar a pesquisa do Data Catalog
Em Escolher plataforma de pesquisa, selecione Data Catalog como o modo de pesquisa.
Na caixa de pesquisa, digite o nome de um conjunto de dados que tenha uma tabela.

Por exemplo, se você concluiu o guia de início rápido Marcar uma tabela do BigQuery usando o Data Catalog, você pode pesquisar demo-dataset e selecionar a tabela trips.
Clique na tabela.

A página de detalhes da tabela do BigQuery é aberta.

Os detalhes da tabela incluem as seguintes seções:

Detalhes da tabela do BigQuery. Inclui informações como horário de criação, horário da última modificação, horário de expiração, URLs de recursos e rótulos.
Tags. Lista as tags aplicadas.Você pode editar as tags nesta página e conferir o modelo de tag. Clique no ícone Ações.
Tags de esquema e colunas. Lista o esquema aplicado e os valores dele.

Marcar suas entradas favoritas com estrela e pesquisar

Se você navega com frequência nos mesmos recursos de dados, pode incluir as entradas deles em uma lista personalizada marcando-as com estrelas.

No console do Google Cloud, acesse a página Pesquisa do Dataplex.

Acessar a pesquisa do Data Catalog
Em Escolher plataforma de pesquisa, selecione Data Catalog como o modo de pesquisa.
Encontre o recurso e marque a entrada dele de uma destas duas maneiras:
- Clique em ao lado da entrada nos resultados da pesquisa.
- Clique no nome da entrada para abrir a página de detalhes e clique na STAR na barra de ações na parte de cima.

Você pode marcar com estrela até 200 entradas.

As entradas marcadas com estrela aparecem na lista Entradas marcadas com estrela na página de pesquisa antes de você digitar uma consulta na barra de pesquisa. Essa lista só fica visível para você.

Para pesquisar apenas as entradas marcadas com estrela, no painel Filtros, na seção Escopo, selecione Marcadas com estrela.

Também é possível usar os métodos correspondentes da API Data Catalog para marcar com estrela e remover a marca de estrela das entradas. Ao pesquisar recursos, use o parâmetro starredOnly no objeto scope. Para mais informações, consulte o método catalog.search.

A seguir

Entenda a sintaxe de pesquisa do Data Catalog.
Saiba como pesquisar recursos no Dataplex Catalog.

Pesquisar recursos de dados com o Data Catalog

Escopo de pesquisa

Problemas de recuperação na pesquisa

Use a sinalização admin_search.

Tabelas fragmentadas por data

Filtros

Filtrar por valor da tag

Filtra a visibilidade

Pesquisar recursos de dados

Console

Console

Dicas de pesquisa por expressão

Exemplo de pesquisa

Java

Node.js

Python

REST e LINHA DE CMD

REST

1. Pesquisar no catálogo

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Ver detalhes da tabela

Marcar suas entradas favoritas com estrela e pesquisar

A seguir

Use a sinalização `admin_search`.