Pesquisar recursos de dados com o Data Catalog

Neste documento, explicamos como você pode usar o Data Catalog para fazer uma pesquisa de recursos de dados, como:

• Conjuntos de dados, tabelas, visualizações e modelos do BigQuery
• Fluxos de dados do Pub/Sub
• Serviços, bancos de dados e tabelas do metastore do Dataproc
• Modelos de tags, grupos de entradas e entradas personalizadas do Data Catalog
• Recursos em silos de dados corporativos conectados ao Data Catalog

Escopo de pesquisa

Os resultados da pesquisa podem ser diferentes para usuários com permissões distintas. O escopo dos resultados de pesquisa do Data Catalog é definido de acordo com o papel e as permissões do IAM do usuário.

Por exemplo, se um usuário tiver acesso de leitura do BigQuery a um objeto, esse objeto aparecerá nos resultados da pesquisa do Data Catalog. 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.tables.get para esse conjunto de dados. O papel de visualizador de metadados do BigQuery (roles/bigquery.metadataViewer) inclui a permissão mínima de leitura de metadados para que um conjunto de dados, tabela ou visualização apareça nos resultados da pesquisa.

Observação: 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.

Observação: as consultas de pesquisa do Data Catalog não garantem o recall total. É possível que os resultados correspondentes à consulta não sejam retornados, mesmo em páginas de resultados subsequentes. Além disso, os resultados retornados (e não retornados) poderão variar se você repetir as consultas de pesquisa. 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.

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 específicas fragmentads por data não ficarão visíveis na pesquisa do Data Catalog, mesmo que estejam presentes no Data Catalog e possam receber tags.

Como pesquisar recursos de dados

Console

Console

1. Para pesquisar recursos de dados, abra a página inicial do Data Catalog no Console do Google Cloud e digite uma consulta de pesquisa.
2. Quando você clica em PESQUISAR ou faz uma seleção nos painéis Explorar recursos de dados ou Dicas de pesquisa na página inicial do Cloud Data Catalog, a página Pesquisar é aberta. Se você fez uma seleção a partir dos painéis na página inicial, ela será transferida para a expressão da caixa de pesquisa para qualificar sua pesquisa.
3. Você também pode filtrar os resultados de pesquisa selecionando no painel Filtros à esquerda.

Filtros

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

• Sistemas, como BigQuery, Pub/Sub, metastore do Dataproc, sistemas personalizados e o próprio Data Catalog

  Observação: o sistema do Data Catalog contém conjuntos de arquivos e entradas personalizadas.

• Tipos de dados, como fluxos de dados, conjuntos de dados, 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 disponíveis.

• Os conjuntos de dados são provenientes do BigQuery.

A seção Tags mostra os modelos de tags que serão filtrados. Um modelo selecionado filtra recursos de dados com tags que usam o modelo escolhido. Se nenhuma entrada tiver essas tags, todos os resultados da pesquisa serão excluídos, mesmo que a consulta de pesquisa original corresponda a algumas entradas.

Observação: da mesma forma, se você selecionar vários filtros e um deles não corresponder a nada, todos os resultados serão excluídos.

Todos os conjuntos de filtros, exceto Tags, são atualizados dependendo da alteração na consulta de pesquisa. Os filtros são preenchidos com uma amostra dos resultados da pesquisa atuais. Portanto, todo o conjunto de resultados da pesquisa pode incluir entradas que correspondam à consulta atual, mas é possível que os filtros que correspondem a essas entradas não sejam exibidos no painel Filtros.

Observação: no momento, os conjuntos de filtros não serão atualizados se você alterar os filtros selecionados. Por exemplo, se você selecionar o sistema BigQuery naSistemas, os filtros de tipo de dados na seção correspondente não serão restritos aos específicos do BigQuery, como tabela, visualização, conjunto de dados etc.

É possível adicionar manualmente os seguintes filtros:

• Em Projetos, filtre um projeto clicando no botão ADICIONAR PROJETO, procure um projeto específico, selecione-o e clique em ABRIR.
• Em Tags, um filtro de modelo de tag clicando na lista suspensa Adicionar mais tags, pesquisando um modelo específico, selecionando-o e clicando em OK. de dados.

Além disso, você pode:

• Marque Incluir conjuntos de dados públicos para pesquisar os recursos de dados disponíveis publicamente no Google Cloud, além dos recursos disponíveis para você.
• Volte à experiência de pesquisa antiga clicando no botão correspondente no canto superior direito. A experiência antiga oferece uma filtragem mais simples.

Exemplo de pesquisa

Por exemplo, vamos pesquisar a tabela "trips" que você configurou no Guia de início rápido para inclusão de tags em tabelas:

1. Digite "viagens" na caixa de pesquisa e clique em PESQUISAR.
2. Selecione BigQuery na seção Sistemas para excluir recursos de dados com o mesmo nome que pertencem a outros sistemas.
3. Selecione o ID do projeto na seção Projetos para excluir recursos de dados de outros projetos. Se o projeto não for exibido na seção, clique em ADICIONAR PROJETO e selecione-o na janela de diálogo.
4. Selecione o Modelo de tag de demonstração na seção Tags para ver se uma tag que usa esse modelo está anexada à tabela "trips". Se esse modelo não for exibido na seção, clique na lista suspensa Adicionar mais tags, encontre-a e selecione-a. Em seguida, clique em OK.

Com todos os filtros selecionados, os resultados da pesquisa devem conter apenas uma entrada: a tabela "trips" do BigQuery no projeto com uma tag anexada que usa o "Modelo de tag de demonstração".

Além disso, há outras possibilidades:

1. Filtre a pesquisa adicionando keyword:value aos termos de pesquisa na caixa de pesquisa:

   Keyword	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

   Dicas de expressão de pesquisa:

   • Coloque sua expressão de pesquisa entre aspas ("search terms") se ela contiver espaços.
   • É possível preceder uma palavra-chave com "NOT" (tudo em maiúsculas) para corresponder à negação lógica da palavra-chave: filtro de termos (por exemplo, NOT column:term listará nos resultados da pesquisa todas as colunas, exceto aquelas que correspondem ao termo especificado). Também é possível usar os operadores booleanos "AND" e "OR", em letras maiúsculas, para combinar expressões de pesquisa.
   • Consulte Sintaxe de pesquisa do Data Catalog para obter uma lista de palavras-chave e outros termos que você pode usar em uma expressão de pesquisa do Data Catalog.

2. 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

Java

Antes de testar essa amostra, siga as instruções de configuração para 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 em Java.

Ver no GitHub Feedback

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 essa amostra, siga as instruções de configuração para 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 em Node.js.

Ver no GitHub Feedback

// 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=dataset';

  // 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 essa amostra, siga as instruções de configuração para 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 em Python.

Ver no GitHub Feedback

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

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

1. Pesquisar no catálogo

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

• includeOrgIds: organization-id

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: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para o caminho do arquivo da chave privada da conta de serviço.

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

curl -X POST \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://datacatalog.googleapis.com/v1/catalog:search"

PowerShell (Windows)

Observação: verifique se você definiu a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS para o caminho do arquivo da chave privada da conta de serviço.

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

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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