Gerenciar recursos usando o Knowledge Catalog

Neste documento, explicamos como pesquisar e gerenciar os recursos do Spanner usando o Knowledge Catalog.

O Knowledge Catalog cataloga metadados sobre instâncias, bancos de dados, tabelas, colunas e visualizações do Spanner em Google Cloud, permitindo que agentes de IA e ferramentas de análise recuperem contexto fundamentado e relevante.

Sobre o Knowledge Catalog e o Spanner

O Knowledge Catalog se refere aos recursos no Spanner e em outros serviços do Google Cloud como recursos. No Knowledge Catalog, cada recurso do Spanner, como uma instância, um banco de dados, uma tabela ou uma visualização, é representado por uma entrada de catálogo que armazena metadados técnicos e comerciais (aspectos) sobre o recurso.

É possível usar o Knowledge Catalog nos seguintes fluxos de trabalho para descobrir e entender seus recursos do Spanner:

  • Análise: entenda as dependências entre os recursos de dados e avalie a adequação deles para casos de uso específicos.
  • Gerenciamento de mudanças: acompanhe as modificações estruturais em todos os bancos de dados.
  • Movimentação de dados: rastreie as origens e os destinos do pipeline.
  • Evolução do esquema: monitorar as definições de tabelas e colunas ao longo do tempo.
  • Embasamento de IA contextual: forneça um esquema e um contexto de negócios para agentes de IA.

O Knowledge Catalog cataloga automaticamente os seguintes metadados para recursos do Spanner:

  • Nome do recurso e nome totalmente qualificado (FQN)
  • Local (região)
  • Carimbos de data/hora de criação e última modificação
  • Definições de esquema (para tabelas e visualizações)
  • Tipos de dados de coluna, nulidade e indicadores de chave primária
  • Descrições e identificadores de usuário

A descoberta de metadados do Knowledge Catalog é um processo automatizado que verifica fontes de dados conectadas, como o Spanner, para identificar recursos de dados, como tabelas, visualizações e bancos de dados. Em seguida, o Knowledge Catalog extrai metadados técnicos dos recursos, como esquemas, descrições e locais.

O Spanner sincroniza metadados com o Knowledge Catalog em intervalos regulares, geralmente a cada seis horas. Portanto, as alterações de metadados feitas nos recursos do Spanner podem levar aproximadamente seis horas para serem propagadas.

Antes de começar

Antes de usar o Knowledge Catalog com o Spanner, conclua as seguintes tarefas de configuração:

  1. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  2. Verify that billing is enabled for your Google Cloud project.

  3. Ativar a API Dataplex para o projeto.

    Ativar a API Dataplex

Funções exigidas

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

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para gerenciar recursos do Spanner no Knowledge Catalog. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para gerenciar recursos do Spanner no Knowledge Catalog:

  • Crie um tipo de aspecto: dataplex.aspectTypes.create
  • Pesquise instâncias do Spanner:
    • dataplex.projects.search
    • spanner.instances.get
  • Pesquise bancos de dados, tabelas e visualizações do Spanner:
    • dataplex.projects.search
    • spanner.databases.get
  • Ver aspectos nas instâncias do Spanner:
    • dataplex.aspectTypes.get
    • spanner.instances.get
  • Ver aspectos em bancos de dados, tabelas e visualizações do Spanner:
    • dataplex.aspectTypes.get
    • spanner.databases.get
  • Anexe um aspecto a um recurso do Spanner usando um tipo de aspecto:
    • dataplex.aspectTypes.use
    • dataplex.entries.update

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

O Knowledge Catalog é compatível com a pesquisa semântica, que ajuda a encontrar recursos usando linguagem cotidiana, eliminando a necessidade de uma sintaxe de pesquisa complexa. Por exemplo, insira uma consulta como List all Spanner tables related to sales.

Se preferir, pesquise recursos usando palavras-chave específicas, filtros e uma sintaxe de pesquisa baseada em predicados.

Para pesquisar recursos do Spanner no Knowledge Catalog, siga estas etapas:

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

    Acesse Pesquisar

  2. No painel Filtros, em Sistemas, selecione Spanner.

    O Knowledge Catalog mostra todos os recursos do Spanner que você pode acessar nos seus projetos do Google Cloud .

  3. Use o campo de pesquisa para inserir uma consulta em linguagem natural, como List all Spanner tables related to sales.

  4. Opcional: use a pesquisa filtrada na página Pesquisa. Selecione filtros em Tipo, Projetos, Locais e Tipos de aspecto.

  5. Opcional: no campo de pesquisa, anexe um parâmetro de pesquisa após system=spanner. Separe vários parâmetros com espaços ou use parênteses e os operadores lógicos AND, OR e NOT.

    Por exemplo, para visualizar apenas bancos de dados, insira a seguinte consulta:

    system=spanner type=database

    Também é possível usar type=service para pesquisar instâncias ou instance_config=CONFIGURATION_NAME para pesquisar uma configuração de instância.

    Para mais opções de consulta, consulte Sintaxe de pesquisa do Knowledge Catalog.

  6. Na lista de resultados da pesquisa, clique no nome de um recurso para abrir a página de detalhes da entrada dele no Knowledge Catalog.

Na página de detalhes da entrada, é possível fazer o seguinte:

  • Para ver os resumos dos recursos e adicionar uma descrição, acesse a guia Detalhes e, na seção Visão geral, clique em Adicionar.
  • Para conferir ou anexar metadados comerciais e operacionais, acesse a guia Detalhes e, na seção Aspectos, clique em Adicionar ao lado de Aspectos opcionais.
  • Para visualizar os bancos de dados dos membros de uma instância, clique na guia Lista de entradas e depois em Mostrar todas as entradas filhas na pesquisa.
  • Para inspecionar os tipos de dados, as chaves e as definições de coluna de uma tabela, clique na guia Esquema.

Caso de uso: detalhamento da instância para as colunas

Neste caso de uso, você pesquisa uma instância do Spanner e, em seguida, detalha um dos bancos de dados listados na instância para visualizar as tabelas e colunas dele.

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

    Acesse Pesquisar

  2. No painel Filtros, em Sistemas, selecione Spanner.

  3. Para conferir todas as instâncias do Spanner no Knowledge Catalog, use o campo de pesquisa para inserir uma consulta em linguagem natural, como List all Spanner instances, e pressione Enter.

  4. Selecione um nome de instância.

  5. Na página Detalhes do Spanner, clique na guia Lista de entradas e depois em Mostrar todas as entradas filhas na pesquisa.

    O Knowledge Catalog mostra os bancos de dados na instância. Se não houver uma guia Lista de entrada, volte à página Pesquisa e escolha uma instância diferente.

  6. Selecione um nome de banco de dados. Na página Detalhes do banco de dados do Spanner, clique na guia Lista de entradas e depois em Mostrar todas as entradas filhas na pesquisa.

    O Knowledge Catalog exibe as tabelas no banco de dados.

  7. Selecione um nome de tabela e, na página Detalhes da tabela do Spanner, clique em Esquema para ver as colunas da tabela.

  8. Opcional: para adicionar um aspecto a uma coluna, selecione a coluna e clique em Adicionar aspecto.

Enriquecer metadados com aspectos

Para enriquecer os metadados e pesquisar recursos por contexto personalizado, crie aspectos com base em tipos de aspecto (modelos reutilizáveis) e anexe-os aos recursos do Spanner. Com os aspectos, é possível adicionar metadados de negócios estruturados, como propriedade de dados, classificações de governança ou políticas de retenção.

Por exemplo, você pode anexar o seguinte aspecto a uma coluna que contenha um CPF ou CNPJ, que são informações de identificação pessoal (PII):

pii:true
pii_type:SSN

Para anexar um aspecto a um recurso do Spanner, siga estas etapas:

  1. Na página de Pesquisa do Knowledge Catalog, clique no recurso que você quer enriquecer.
  2. Na página de detalhes da entrada, na guia Detalhes, acesse a seção Aspectos.
  3. Ao lado de Aspectos opcionais, clique em Adicionar.
  4. Pesquise e selecione o tipo de aspecto que você quer adicionar, como um esquema personalizado para governança de dados ou privacidade.
  5. Na janela Adicionar aspecto, especifique os campos de aspecto necessários.
  6. Clique em Salvar.

Para instruções detalhadas sobre como criar tipos de aspecto e gerenciar aspectos, consulte Gerenciar aspectos e enriquecer metadados.

Exportar e importar aspectos

Quando você move uma instância do Spanner para uma configuração de instância diferente, o processo exclui as entradas e os aspectos associados à configuração da instância de origem no Knowledge Catalog. Para preservar os aspectos personalizados, faça o seguinte:

  1. Exporte os aspectos associados às entradas na configuração da instância de origem.
  2. Mova a instância para a configuração de destino.
  3. Importe os aspectos para a configuração da instância de destino.

Exportar aspectos da configuração da instância de origem

Antes de mover a instância, recupere os aspectos das entradas do Spanner na configuração da instância de origem usando a Google Cloud CLI, a API Dataplex ou um job de exportação de metadados:

gcloud

Para recuperar os aspectos de uma entrada do Spanner no grupo de entradas do sistema @spanner, use o comando gcloud dataplex entries lookup:

gcloud dataplex entries lookup SOURCE_ENTRY_ID \
  --entry-group=@spanner \
  --location=LOCATION \
  --project=PROJECT_ID \
  --view=all

Substitua:

  • SOURCE_ENTRY_ID: o ID de entrada do recurso do Spanner na configuração da instância de origem.

    Como encontrar o ID de entrada

    Para encontrar o nome da entrada ou traduzir um nome totalmente qualificado (FQN), como spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, use o comando gcloud dataplex entries search.

  • LOCATION: a região da configuração da instância do Spanner, como us-central1.

  • PROJECT_ID: o ID do projeto do Google Cloud que contém a instância do Spanner.

API REST

Para recuperar os aspectos de uma entrada do Spanner no grupo de entradas do sistema @spanner, envie uma solicitação GET ao endpoint projects.locations.lookupEntry.

curl -X GET \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION:lookupEntry?entry=projects/PROJECT_ID/locations/LOCATION/entryGroups/@spanner/entries/SOURCE_ENTRY_ID&view=ALL"

Substitua:

  • ACCESS_TOKEN: o token de acesso que seu aplicativo usa para se autenticar no serviço. Por exemplo, use $(gcloud auth print-access-token).

  • PROJECT_ID: o ID do projeto do Google Cloud que contém a instância do Spanner.

  • LOCATION: a região da configuração da instância do Spanner, como us-central1.

  • SOURCE_ENTRY_ID: o ID de entrada do recurso do Spanner na configuração da instância de origem.

    Como encontrar o ID de entrada

    Para encontrar o nome da entrada ou traduzir um nome totalmente qualificado (FQN), como spanner:PROJECT_ID.INSTANCE_CONFIG_ID.INSTANCE_ID.DATABASE_ID.TABLE_ID, use o comando gcloud dataplex entries search.

Job de exportação

Para exportar metadados de várias entradas em um lote para o Cloud Storage, execute um job de exportação de metadados.

Mover a instância para a configuração de destino

Antes de importar aspectos para a configuração da instância de destino, faça o seguinte:

  1. Mova a instância do Spanner para a configuração da instância de destino. Aguarde a sincronização dos metadados do Spanner da instância movida com o Knowledge Catalog, o que pode levar aproximadamente seis horas.

  2. Para verificar se a sincronização foi concluída, pesquise a instância movida usando um dos seguintes métodos:

    • Na página de Pesquisa do Knowledge Catalog, insira a seguinte consulta:

      system=spanner instance_config=DESTINATION_CONFIG_NAME

    • Execute o comando gcloud dataplex entries search:

      gcloud dataplex entries search "fqn=spanner:PROJECT_ID.DESTINATION_CONFIG_ID.INSTANCE_ID" \
    --project=PROJECT_ID

    Quando o comando retornar a entrada para a configuração da instância de destino, a sincronização estará concluída.

Importar aspectos para a configuração da instância de destino

Depois que os metadados forem sincronizados, anexe os aspectos copiados às entradas na configuração da instância de destino:

gcloud

Para anexar os aspectos copiados à entrada na configuração da instância de destino, use o comando gcloud dataplex entries update-aspects:

gcloud dataplex entries update-aspects DESTINATION_ENTRY_ID \
  --entry-group=@spanner \
  --location=DESTINATION_LOCATION \
  --project=PROJECT_ID \
  --aspects=ASPECTS_FILE

Substitua:

  • DESTINATION_ENTRY_ID: o ID de entrada do recurso do Spanner movido na configuração da instância de destino.

  • DESTINATION_LOCATION: a região da configuração da instância de destino do Spanner, como us-central1.

  • PROJECT_ID: o ID do projeto do Google Cloud que contém a instância do Spanner.

  • ASPECTS_FILE: o caminho para um arquivo JSON ou YAML que contém os aspectos a serem adicionados ou atualizados.

API REST

Para anexar os aspectos exportados à entrada na configuração da instância de destino, use o método da API REST projects.locations.entryGroups.entries.patch, conforme mostrado no exemplo a seguir:

curl -X PATCH \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"aspects":{"ASPECT_KEY":{"data":{"FIELD_NAME":"FIELD_VALUE"}}}}' \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/DESTINATION_LOCATION/entryGroups/@spanner/entries/DESTINATION_ENTRY_ID?updateMask=aspects"

Substitua:

  • ACCESS_TOKEN: o token de acesso que seu aplicativo usa para se autenticar no serviço. Por exemplo, use $(gcloud auth print-access-token).

  • ASPECT_KEY: a chave de aspecto no formato PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID para um aspecto de nível de entrada ou PROJECT_ID.ASPECT_LOCATION.ASPECT_TYPE_ID@Schema.COLUMN_NAME para um aspecto de nível de coluna.

  • FIELD_NAME e FIELD_VALUE: o nome e o valor do campo definidos pelo tipo de aspecto.

  • PROJECT_ID: o ID do projeto que contém a instância do Spanner.

  • DESTINATION_LOCATION: a região da configuração da instância de destino do Spanner, como us-central1.

  • DESTINATION_ENTRY_ID: o ID de entrada do recurso do Spanner movido na configuração da instância de destino.

Job de importação

Para importar aspectos de várias entradas em lote do Cloud Storage, execute um job de importação de metadados.

A seguir