Estabelecer um contexto de dados fundamental com o Knowledge Catalog

O Knowledge Catalog (antigo Dataplex Universal Catalog) permite anexar metadados estruturados e definições de negócios claras diretamente aos seus recursos de dados. Ao fornecer esse contexto, seus dados se tornam detectáveis, você gera confiança para os usuários e embasa os agentes de IA.

Neste tutorial para administradores de dados e analistas de negócios, você vai concluir etapas baseadas UI para criar termos de negócios padrão e contexto de metadados antes de automatizar esses fluxos de trabalho. Você também vai aprender como os principais conceitos do Knowledge Catalog funcionam juntos.

Objetivos

Neste tutorial, você aprenderá a realizar as seguintes tarefas:

• Crie uma única fonte de verdade para termos comerciais com um glossário empresarial.
• Estruture e organize metadados com tipos de aspecto.
• Anexe metadados a recursos de dados com aspectos.
• Use a pesquisa do Knowledge Catalog para encontrar exatamente o que você precisa usando esses novos metadados estruturados.

Antes de começar

Antes de começar, faça o seguinte:

• Selecione um projeto doGoogle Cloud para este tutorial.
• Confirme se o faturamento está ativado no projeto.

Configurar o ambiente

Neste tutorial, usamos o Cloud Shell, um ambiente de linha de comando executado na nuvem.

1. No console do Google Cloud , clique em Ativar o Cloud Shell na barra de ferramentas no canto superior direito. O provisionamento e a conexão do ambiente podem demorar um pouco.

2. No Cloud Shell, defina as variáveis PROJECT_ID e LOCATION para que todos os comandos futuros sejam direcionados ao seu projeto específico do Google Cloud .

   export PROJECT_ID=$(gcloud config get-value project)
   gcloud config set project $PROJECT_ID
   export LOCATION="us-central1"
   

   Observação:as sessões do Cloud Shell podem expirar. Antes de executar scripts de shell, verifique as variáveis de ambiente executando echo $PROJECT_ID. Se o comando retornar uma linha vazia, execute novamente os comandos de exportação desta etapa de configuração do ambiente.

3. Ative os serviços necessários do Google Cloud .

   gcloud services enable \
     dataplex.googleapis.com \
     bigquery.googleapis.com 
   

Criar um conjunto de dados do BigQuery e preparar dados de amostra

Use o código a seguir para criar um conjunto de dados do BigQuery e carregar algumas transações CSV de amostra em uma tabela. Depois que você cria a tabela, o Knowledge Catalog a descobre e cria uma entrada para ela no catálogo.

Pense em uma entrada como a representação de um recurso de dados no Knowledge Catalog. É como um registro no catálogo ao qual você pode anexar metadados. Em vez de adicionar contexto (ou enriquecer) diretamente à tabela do BigQuery, você o adiciona à entrada dela no Knowledge Catalog.

# Create the BigQuery Dataset in the us-central1 region
bq --location=$LOCATION mk --dataset \
    --description "Sample retail data for foundational data context tutorial" \
    $PROJECT_ID:retail_data

# Create a temporary CSV file with the sample data
echo "transaction_id,user_email,gmv,transaction_date
1001,[e-mail],150.50,2025-08-28
1002,[e-mail],75.00,2025-08-28" > /tmp/transactions.csv

# Load the data from the temporary CSV file into a BigQuery table
bq load \
    --source_format=CSV \
    --autodetect \
    retail_data.transactions \
    /tmp/transactions.csv

# (Optional) Clean up the temporary file
rm /tmp/transactions.csv

Execute uma consulta SELECT para verificar sua configuração:

bq query --nouse_legacy_sql "SELECT * FROM retail_data.transactions"

Exemplo de saída:

+----------------+------------------+-------+------------------+
| transaction_id |    user_email    |  gmv  | transaction_date |
+----------------+------------------+-------+------------------+
|           1001 | [e-mail] | 150.5 |       2025-08-28 |
|           1002 | [e-mail] |  75.0 |       2025-08-28 |
+----------------+------------------+-------+------------------+

Observação :não é necessário registrar ou importar manualmente a tabela para o Knowledge Catalog. O Knowledge Catalog ingere automaticamente metadados técnicos de tabelas do BigQuery e cria entradas.

Estabelecer termos comuns com um glossário empresarial

Um bom contexto de dados depende de definições claras que respondam a perguntas como "O que significa o nome desta coluna?" Por exemplo, um desenvolvedor não deve ter que adivinhar se uma coluna chamada gmv significa valor bruto de mercadoria ou se inclui impostos e devoluções. Um glossário empresarial cria uma única fonte de verdade para essas definições em toda a organização. Quando colegas de equipe ou agentes de IA analisam seus dados, eles herdam esse contexto de negócios preciso. As definições compartilhadas alinham as métricas entre equipes, como finanças, vendas e operações, e ajudam os agentes de IA a evitar alucinações.

Siga estas etapas para criar um glossário e definir seu primeiro termo:

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

   Acessar Glossários

2. Clique em Criar glossário empresarial.

3. Digite os seguintes detalhes:

   • Nome de exibição: Retail Business Glossary
   • Local: us-central1 (Iowa)

4. Clique em Criar.

5. Clique em Criar categoria.

6. Nomeie a categoria como Sales Metrics e clique em Criar.

7. Selecione a categoria Métricas de vendas e clique em Adicionar termo.

8. Dê o nome Gross Merchandise Value ao termo e clique em Criar.

9. Clique no termo Valor bruto de mercadorias para abrir a página de detalhes.

10. Clique em Adicionar ao lado de Visão geral. Insira os seguintes detalhes: The total value of merchandise sold over a given period of time before the deduction of any fees or expenses. This is a key indicator of e-commerce business growth.

11. Clique em Salvar.

Você criou um termo de glossário que pode ser vinculado a entradas de dados em toda a organização.

Definir metadados técnicos com um tipo de aspecto

Ao trabalhar com dados, muitas vezes você precisa responder a perguntas como "Quem é o proprietário deste conjunto de dados corrompido?" ou "Esta tabela foi aprovada para uso?" As tags de metadados não estruturados tentam responder a essas perguntas, mas rapidamente se tornam desatualizadas ou inconsistentes. Por exemplo, uma tabela pode ser marcada como owner:bob e outra como steward:[e-mail]. Para manter os metadados organizados em escala, é necessário um esquema consistente.

É aí que entram os tipos de aspecto. Um tipo de aspecto é um blueprint de metadados que permite definir regras claras e campos obrigatórios. Exigir campos padrão, como endereços de e-mail válidos para gestores de dados, permite que os scripts downstream validem e protejam seus metadados automaticamente.

Siga estas etapas para criar um tipo de aspecto:

1. No console Google Cloud , acesse a guia Tipos de aspecto do Knowledge Catalog na página Tipos de metadados.

   Acessar Tipos de aspecto

2. Na guia Personalizado, clique em Criar.

3. Digite os seguintes detalhes:

   • Nome de exibição: Data Asset Context
   • Local: us-central1 (Iowa)

4. Na seção Modelo, clique em Adicionar campo para criar os três campos a seguir:

   • Campo 1:

     • Nome de exibição: Data Steward
     • Tipo: Text
     • Obrigatório: marque a caixa de seleção.
     • Tipo de texto: Plain text

   • Campo 2 (clique em Adicionar campo):

     • Nome de exibição: Data Sensitivity
     • Tipo: Enum
     • É obrigatório: deixe como opcional.
     • Valores: adicione Public, Internal e Confidential.

   • Campo 3 (clique em Adicionar campo):

     • Nome de exibição: Last Review Date
     • É obrigatório: deixe como opcional.
     • Tipo: Date and time

5. Clique em Salvar.

Agora você tem um tipo de aspecto para campos de metadados relacionados à governança de dados, como administrador de dados, nível de confidencialidade e data de revisão. Na próxima seção, você vai aplicar esse esquema a uma entrada de tabela anexando um aspecto com valores específicos para esses campos.

Enriquecer uma entrada com contexto comercial e técnico

Os nomes das colunas costumam ser abreviados ou ambíguos. Vincular uma coluna a um termo no glossário empresarial fornece uma definição clara e consistente. Nesta etapa, você vai enriquecer a entrada da tabela retail_data.transactions vinculando o termo Gross Merchandise Value a uma coluna chamada gmv e anexando um aspecto à entrada da tabela usando seu tipo de aspecto.

Vincular uma coluna a um termo de negócios

Para esclarecer o que é a coluna gmv em retail_data.transactions, vincule-a ao termo Gross Merchandise Value.

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

   Acesse Pesquisar

2. Clique em Filtros para abrir o painel Filtros.

3. Em Escopo, selecione Projeto atual.

4. Pesquise retail_data.transactions e clique na tabela de transações retornada.

5. Clique na guia Esquema.

6. Marque a caixa de seleção ao lado da coluna gmv e clique em Adicionar termo comercial.

7. Selecione Gross Merchandise Value.

Anexar um aspecto à entrada da tabela

Além de vincular termos de negócios a colunas, é possível anexar um aspecto a uma entrada de tabela para capturar metadados no nível da tabela, como propriedade e confidencialidade dos dados.

Um aspecto é uma instância de um tipo de aspecto, com valores específicos para campos de metadados. Quando você anexa um aspecto a uma entrada, o Knowledge Catalog verifica as informações fornecidas em relação ao esquema definido no tipo de aspecto para garantir a consistência.

Para definir a propriedade e a sensibilidade da tabela retail_data.transactions, anexe o aspecto Data Asset Context:

1. Na guia Detalhes da página de entrada retail_data.transactions, clique em Adicionar ao lado de Aspectos opcionais.
2. Selecione Data Asset Context na lista.

3. Insira valores nos campos:

   • Administrador de dados:[e-mail]
   • Sensibilidade de dados:selecione Interno.
   • Data da última revisão:selecione a data de hoje.

4. Clique em Salvar.

Ao enriquecer os dados de amostra de transações de varejo, você estabeleceu uma base sólida de contexto de dados no Knowledge Catalog.

Pesquisar entradas usando metadados enriquecidos

Agora você pode usar a pesquisa do Knowledge Catalog para encontrar entradas com base no contexto de negócios que você configurou. Por exemplo, é possível encontrar todos os recursos com um nível de confidencialidade específico ou pesquisar o termo do glossário para descobrir as tabelas subjacentes.

Dica: o Knowledge Catalog oferece duas experiências de pesquisa distintas com sintaxes diferentes: Linguagem natural (com assistência de IA) e Palavra-chave (correspondência estruturada/exata). Este tutorial se concentra na linguagem natural.

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

   Acesse Pesquisar

2. Clique em Filtros para abrir o painel Filtros.

3. Em Escopo, selecione Projeto atual.

4. Na barra de pesquisa, digite Find tables where the Data Asset Context aspect has Internal sensitivity..

5. A tabela retail_data.transactions vai aparecer na lista de resultados.

6. Limpe a barra de pesquisa e digite Find tables with the Gross Merchandise Value term attached..

7. A tabela retail_data.transactions vai aparecer novamente nos resultados, já que a coluna gmv está diretamente vinculada a esse termo de negócios.

Quando você conecta um agente de IA ao Knowledge Catalog, ele herda esses metadados enriquecidos automaticamente. Por exemplo, quando você pede a um agente para recuperar métricas de vendas internas, ele lê o aspecto de sensibilidade de dados (que você definiu como Interno) e o termo do glossário de valor bruto de mercadorias vinculado. Esse contexto compartilhado ajuda o agente a verificar as fontes de dados, respeitar as políticas de acesso e evitar alucinações.

Limpar

Para evitar cobranças, exclua os recursos criados neste tutorial.

Excluir o conjunto de dados de amostra

Para excluir o conjunto de dados de amostra do BigQuery e todas as tabelas dele, use o comando a seguir. Essa ação é irreversível.

Aviso :esse comando de exclusão recursiva não pede confirmação. Para evitar a perda acidental de dados devido a variáveis de ambiente incorretas, verifique o ID do projeto e o nome do conjunto de dados antes de executar o comando.

# Re-run these exports if your Cloud Shell session timed out
export PROJECT_ID=$(gcloud config get-value project)

# Manually type this command to confirm you are deleting the correct dataset
bq rm -r -f --dataset $PROJECT_ID:retail_data

Excluir artefatos do Knowledge Catalog

1. No console Google Cloud , acesse a guia Tipos de aspecto do Knowledge Catalog na página Tipos de metadados.

   Acessar Tipos de aspecto

2. Selecione o tipo de aspecto Data Asset Context e clique em Excluir.

3. No console Google Cloud , acesse a página Glossários do Knowledge Catalog.

   Acessar Glossários

   Observação: é preciso excluir todos os termos e categorias antes de excluir o glossário.

4. Selecione o termo Gross Merchandise Value e clique em Excluir.

5. Selecione a categoria Sales Metrics e clique em Excluir.

6. Selecione Retail Business Glossary e clique em Excluir.

A seguir

Para saber mais sobre a curadoria de catálogos e a criação de agentes com o Knowledge Catalog, consulte os seguintes recursos:

• Gerenciar aspectos e enriquecer metadados:saiba como definir esquemas personalizados e anexar metadados estruturados em Gerenciar aspectos e enriquecer metadados.
• Gerenciar glossários empresariais:saiba como estabelecer um vocabulário padronizado para sua organização em Gerenciar um glossário empresarial.
• Governe com o Terraform:saiba como provisionar tipos de aspectos e glossários personalizados usando o Terraform.
• Trabalhar com termos de glossário em grande escala:realize o enriquecimento de metadados em massa usando arquivos JSON em Sobre a importação e exportação de glossários e links de entrada.
• Enriquecer metadados com agentes:crie um agente de IA para extrair contexto e enriquecer seus recursos de dados em Criar um agente para enriquecer seus metadados.
• Descoberta avançada de casos de uso:descubra outros fluxos de trabalho e cenários personalizáveis em Casos de uso.