Gerenciar recursos de dados usando o Knowledge Catalog

O Knowledge Catalog cataloga automaticamente os metadados sobre recursos do Bigtable. Esse recurso ajuda a pesquisar e gerenciar os recursos de dados do Bigtable.

Os metadados são sincronizados automaticamente do Bigtable para o Knowledge Catalog para os seguintes recursos do Bigtable:

  • Instâncias
  • Clusters
  • Tabelas, incluindo detalhes do grupo de colunas

  • Visualizações:

    • Visualizações autorizadas
    • Visualizações materializadas contínuas
    • Visualizações lógicas

    As visualizações não têm entradas de catálogo global. Para acessar os metadados da visualização, consulte a região atribuída à instância. Para mais informações, consulte a seção Acessar metadados de visualização deste documento.

O Knowledge Catalog é um serviço de gerenciamento de metadados totalmente gerenciado. Ele oferece mecanismos unificados de visualização e inclusão de tags para metadados técnicos e comerciais. Para saber mais sobre o Knowledge Catalog e por que usá-lo, consulte Visão geral do Knowledge Catalog.

Benefícios do uso do Knowledge Catalog com o Bigtable

As informações do Knowledge Catalog sobre seus dados ajudam na análise, na reutilização de dados, no desenvolvimento de aplicativos e no gerenciamento de dados.

É possível pesquisar entradas no Knowledge Catalog por detalhes, como o nome do recurso. Por exemplo, pesquise um nome de instância para encontrar a entrada de uma instância ou um grupo de colunas para encontrar a entrada de uma tabela. Você também pode usar a pesquisa de atributo, aplicando filtros para refinar a pesquisa. Para mais informações, consulte Pesquisar recursos no Knowledge Catalog.

A ingestão e a catalogação de visualizações do Bigtable permitem fazer o seguinte:

  • Encontre recursos de dados granulares, como visualizações materializadas autorizadas, lógicas e contínuas, em um inventário central.
  • Ter visibilidade sobre quais visualizações existem e quem tem acesso a elas, o que permite que as equipes de governança apliquem políticas e controles de acesso.
  • Entenda como as visualizações autorizadas se conectam a tabelas e como as visualizações materializadas lógicas e contínuas se conectam a instâncias para um melhor contexto.

Enriquecer os metadados com aspectos ajuda a entender e catalogar os dados nas tabelas do Bigtable. Os aspectos permitem anexar metadados comerciais e técnicos personalizados às entradas catalogadas, tornando os dados mais fáceis de descobrir em todo o seu patrimônio de dados e permitindo pesquisas direcionadas. Para mais informações, consulte Gerenciar aspectos e enriquecer metadados.

Comece a usar o Knowledge Catalog

Para começar a usar o Knowledge Catalog para gerenciar seus recursos de dados do Bigtable, conclua as seguintes tarefas:

  1. Opcional: se você não conhece o Knowledge Catalog, ative a API Dataplex.

  2. Conceda papéis do IAM aos principais que exigem acesso às entradas do Bigtable no Knowledge Catalog.

  3. Saiba como pesquisar recursos de dados.

  4. Consulte a sintaxe de pesquisa do Knowledge Catalog para entender como encontrar os metadados.

  5. Leia os conceitos sobre como gerenciar metadados com aspectos. Para mais informações, consulte Sobre metadados no Knowledge Catalog.

Ver metadados no Knowledge Catalog

Cada tipo de visualização do Bigtable é representado como um tipo de entrada distinto no catálogo. O Knowledge Catalog armazena metadados específicos (aspectos) para cada tipo:

Tipo de visualização Campos de metadados
Visualização autorizada Definição completa do subconjunto, status da proteção contra exclusão. O ID da tabela base faz parte do caminho do recurso e da entrada pai da entrada, e não de um campo de aspecto separado.
Visualização lógica Consulta SQL, esquema, status da proteção contra exclusão. A tabela base é referenciada na consulta SQL.
Visualização materializada contínua Consulta SQL, esquema, status da proteção contra exclusão, detalhes do armazenamento. A tabela base é referenciada na consulta SQL. No aspecto de armazenamento, o campo sourceUri aponta para o próprio recurso de visualização, não para a tabela base.

Maneiras de pesquisar metadados do Bigtable

É possível pesquisar metadados sincronizados do Bigtable usando o Knowledge Catalog.

Além dos predicados qualificados, é possível pesquisar recursos do Bigtable com os seguintes campos de metadados:

  • Instância

    • Nome da instância do Bigtable
    • ID da instância do Bigtable
    • Local do cluster
    • ID do cluster

  • Tabela

    • ID da tabela
    • Nome do grupo de colunas
    • Nome da instância do Bigtable
    • ID da instância do Bigtable

É possível pesquisar visualizações pelas seguintes categorias:

  • Tipo de visualização:
    • type=cloud-bigtable-authorized-view
    • type=cloud-bigtable-logical-view
    • type=cloud-bigtable-materialized-view
  • Alias de visualização unificada: use o alias VIEW para encontrar todos os tipos de visualizações do Bigtable simultaneamente.
  • Detalhes de metadados: pesquise por texto de consulta, recurso pai, detalhes de definição de subconjunto ou atributos específicos, como proteção contra exclusão.
  • Região: no console do Google Cloud , use os filtros location=LOCATION ou de região para pesquisar visualizações ou qualquer outro recurso em uma região.

Quando você visualiza uma instância global do Bigtable ou uma entrada de tabela no console doGoogle Cloud , a guia Lista de entradas não inclui visualizações regionais. Da mesma forma, quando você visualiza uma entrada de visualização regional, o caminho de navegação estrutural não leva à instância ou tabela pai. Para encontrar esses recursos, pesquise-os diretamente usando as categorias de pesquisa anteriores.

Acessar metadados de visualização

Ao contrário das instâncias e tabelas do Bigtable, as visualizações não têm entradas de catálogo global. Os metadados das visualizações são armazenados exclusivamente na região atribuída à sua instância no Knowledge Catalog (knowledgeCatalogRegion).

Ao pesquisar recursos no Knowledge Catalog, use filtros de região para encontrar visualizações ou qualquer outro recurso em uma região específica. No entanto, ao usar a API Dataplex ou as bibliotecas de cliente para pesquisar, recuperar ou gerenciar aspectos em visualizações do Bigtable, é necessário especificar a região do Knowledge Catalog da instância no parâmetro location do URL da solicitação. Se você especificar o local como global, o comando retornará um erro NOT_FOUND.

As seções a seguir explicam como acessar os metadados de visualização na região da sua instância.

Encontrar a região do Knowledge Catalog de uma instância

Para encontrar o knowledgeCatalogRegion da sua instância do Bigtable, use o comando gcloud bigtable instances describe:

gcloud bigtable instances describe INSTANCE_ID

Substitua INSTANCE_ID pelo identificador exclusivo da sua instância.

A resposta ao comando inclui o campo knowledgeCatalogRegion, conforme mostrado no exemplo a seguir:

createTime: '2026-01-15T10:00:00.000000Z'
displayName: my-instance
edition: ENTERPRISE
knowledgeCatalogRegion: us-central1
name: projects/my-project/instances/my-instance
state: READY
type: PRODUCTION

Neste exemplo, o local das solicitações de API do Dataplex e os filtros de região para visualizações nessa instância é us-central1.

Inspecionar uma entrada do Knowledge Catalog de uma visualização

Console

Para inspecionar a entrada de uma visualização no Knowledge Catalog, siga estas etapas:

  1. No console Google Cloud , acesse a página Pesquisa do Knowledge Catalog.

    Acesse Pesquisar

  2. No campo de pesquisa, digite o nome ou o ID da visualização do Bigtable ou insira uma consulta de pesquisa e pressione Enter.

    É possível pesquisar visualizações usando os seguintes predicados:

    • Todas as visualizações: VIEW
    • Visualizações autorizadas: type=cloud-bigtable-authorized-view
    • Visualizações lógicas: type=cloud-bigtable-logical-view
    • Visualizações materializadas contínuas: type=cloud-bigtable-materialized-view
    • Visualizações por região: por exemplo, location=us-central1

  3. Para refinar a pesquisa, clique em Filtros.

  4. Nos resultados da pesquisa, clique no nome da visualização para abrir a página de detalhes da entrada.

    A página de detalhes da entrada mostra todos os atributos de entrada, incluindo informações gerais, aspectos do sistema, como a consulta SQL, o esquema ou a definição de subconjunto, e aspectos personalizados anexados.

gcloud

Para inspecionar a entrada da visualização no Knowledge Catalog, use o comando gcloud dataplex entries lookup:

gcloud dataplex entries lookup "VIEW_RESOURCE_NAME" \
    --project="PROJECT_ID" \
    --location="LOCATION" \
    --entry-group="@bigtable" \
    --view="all"

Substitua:

  • VIEW_RESOURCE_NAME: o caminho do recurso do Bigtable para a visualização (omitindo o // inicial). Crie o caminho do recurso com base no tipo de visualização:
    • Visualização autorizada: bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/tables/TABLE_ID/authorizedViews/VIEW_ID
    • Visualização lógica: bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/logicalViews/VIEW_ID
    • Visualização materializada contínua: bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/materializedViews/VIEW_ID
  • PROJECT_ID: o identificador exclusivo do seu projeto doGoogle Cloud .
  • INSTANCE_ID: o identificador exclusivo da instância do Bigtable.
  • TABLE_ID: para visualizações autorizadas, o identificador exclusivo da tabela base que contém a visualização.
  • VIEW_ID: o identificador atribuído à visualização.
  • LOCATION: a região do Knowledge Catalog da instância do Bigtable (por exemplo, us-central1).

A saída retorna todos os atributos de entrada, incluindo os aspectos do sistema e os aspectos personalizados anexados. Na saída, o campo parentEntry contém um caminho de entrada regional para a tabela ou instância pai. Como o Bigtable armazena entradas de tabela e instância apenas no local global, essa entrada pai regional não pode ser acessada. Para procurar a tabela pai ou a entrada da instância, especifique global como o local.

REST

Para pesquisar uma entrada de visualização de maneira programática usando a API Dataplex, envie uma solicitação HTTP GET autenticada para o método lookupEntry:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntry?entry=projects/PROJECT_ID/locations/LOCATION/entryGroups/@bigtable/entries/VIEW_RESOURCE_NAME&view=ALL"

Substitua:

  • VIEW_RESOURCE_NAME: o caminho do recurso do Bigtable para a visualização (omitindo o // inicial). Crie o caminho do recurso com base no tipo de visualização:
    • Visualização autorizada: bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/tables/TABLE_ID/authorizedViews/VIEW_ID
    • Visualização lógica: bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/logicalViews/VIEW_ID
    • Visualização materializada contínua: bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/materializedViews/VIEW_ID
  • PROJECT_ID: o identificador exclusivo do seu projeto doGoogle Cloud .
  • INSTANCE_ID: o identificador exclusivo da instância do Bigtable.
  • TABLE_ID: para visualizações autorizadas, o identificador exclusivo da tabela base que contém a visualização.
  • VIEW_ID: o identificador atribuído à visualização.
  • LOCATION: a região do Knowledge Catalog da instância do Bigtable (por exemplo, us-central1).

A saída retorna todos os atributos de entrada, incluindo os aspectos do sistema e os aspectos personalizados anexados. Na saída, o campo parentEntry contém um caminho de entrada regional para a tabela ou instância pai. Como o Bigtable armazena entradas de tabela e instância apenas no local global, essa entrada pai regional não pode ser acessada. Para procurar a tabela pai ou a entrada da instância, especifique global como o local.

Funções exigidas

A visualização, inclusão de tags e pesquisa de recursos do Bigtable no Knowledge Catalog têm diferentes requisitos de permissão. Em geral, conceda aos principais da organização o papel mínimo necessário para realizar uma tarefa.

Permissão para visualizar aspectos públicos e privados

Para ter as permissões necessárias para visualizar aspectos públicos e privados nos recursos do Bigtable, peça ao administrador para conceder a você os seguintes papéis do IAM:

Esses papéis predefinidos têm as permissões necessárias para visualizar aspectos públicos e privados. As permissões exatas necessárias são as seguintes:

  • bigtable.instances.get
  • bigtable.clusters.get
  • bigtable.tables.get
  • dataplex.aspectTypes.get

As visualizações exigem as seguintes permissões:

  • Visualizações autorizadas: bigtable.authorizedViews.get
  • Visualizações lógicas: bigtable.logicalViews.get
  • Visualizações materializadas contínuas: bigtable.materializedViews.get

Permissão para pesquisar recursos do Bigtable

Para receber as permissões necessárias para pesquisar os recursos do Bigtable no Knowledge Catalog, peça ao administrador para conceder a você os seguintes papéis do IAM:

Esses papéis predefinidos contêm as permissões necessárias para pesquisar os recursos do Bigtable. As permissões exatas necessárias são as seguintes:

  • bigtable.instances.get
  • bigtable.clusters.get
  • bigtable.tables.get

As visualizações exigem as seguintes permissões:

  • Visualizações autorizadas: bigtable.authorizedViews.get
  • Visualizações lógicas: bigtable.logicalViews.get
  • Visualizações materializadas contínuas: bigtable.materializedViews.get

Permissão para pesquisar e visualizar metadados do Bigtable

Para pesquisar e visualizar metadados de recursos do Bigtable, é necessário ter um papel que inclua as seguintes permissões:

  • Instâncias e tabelas: bigtable.instances.get, bigtable.clusters.get, bigtable.tables.get
  • Visualizações autorizadas: bigtable.authorizedViews.get
  • Visualizações lógicas: bigtable.logicalViews.get
  • Visualizações materializadas contínuas: bigtable.materializedViews.get

Os papéis predefinidos, como roles/bigtable.viewer ou roles/bigtable.admin, geralmente contêm essas permissões.

Permissão para anexar aspectos aos recursos do Bigtable

Para receber as permissões necessárias para anexar aspectos aos recursos do Bigtable no Knowledge Catalog, peça ao administrador para conceder a você os seguintes papéis do IAM:

Esses papéis predefinidos têm as permissões necessárias para adicionar aspectos públicos e privados. As permissões exatas necessárias são as seguintes:

  • bigtable.instances.update
  • bigtable.clusters.update
  • bigtable.tables.update
  • dataplex.aspectTypes.use
  • dataplex.entries.update

As visualizações exigem as seguintes permissões:

  • Visualizações autorizadas: bigtable.authorizedViews.update
  • Visualizações lógicas: bigtable.logicalViews.update
  • Visualizações materializadas contínuas: bigtable.materializedViews.update

Opcional: criar um papel personalizado

É possível criar um papel personalizado para conceder a usuários que precisem de acesso completo a todos os metadados do Bigtable no Knowledge Catalog em todo o projeto ou organização. Em seguida, atribua qualquer conta de serviço ou usuário que precise acessar um principal do papel personalizado. Para saber mais sobre papéis personalizados, consulte Papéis e permissões.

Escolha um nome significativo para o papel, como Editor do Dataplex do Bigtable, e atribua apenas os principais que precisam de acesso a ele. Para instruções de configuração, consulte Criar e gerenciar papéis personalizados.

Conceda as seguintes permissões ao papel personalizado:

  • bigtable.instances.get
  • bigtable.instances.update
  • bigtable.clusters.get
  • bigtable.clusters.update
  • bigtable.tables.get
  • bigtable.tables.update
  • bigtable.authorizedViews.get
  • bigtable.authorizedViews.update
  • bigtable.logicalViews.get
  • bigtable.logicalViews.update
  • bigtable.materializedViews.get
  • bigtable.materializedViews.update
  • dataplex.aspectTypes.get
  • dataplex.aspectTypes.use

Para mais informações, consulte Permissões do IAM do Knowledge Catalog. Para ver descrições de permissões do Bigtable, consulte Permissões.

Limitações

As seções a seguir listam as restrições que você precisa considerar antes de usar o Knowledge Catalog para gerenciar os metadados do Bigtable.

Restrições de local

Se a organização aplicar restrições de local, as entradas de metadados dos recursos do Bigtable poderão não ser sincronizadas com o Knowledge Catalog. Todas as entradas criadas antes da aplicação das restrições de local são retidas pelo Knowledge Catalog.

Para permitir que o Knowledge Catalog carregue recursos, verifique se a política de local permite o seguinte:

  • A multirregião global para instâncias e tabelas.
  • A região específica que corresponde ao knowledgeCatalogRegion da sua instância para visualizações.

Exceção de nome do grupo de colunas

A API Dataplex rejeita solicitações em que o nome do grupo de colunas na solicitação inclui um ponto (.). Por exemplo, quando o nome do grupo de colunas é personal.info.

A seguir