Sobre a pesquisa no Knowledge Catalog

A pesquisa no Knowledge Catalog (antigo Dataplex Universal Catalog) permite descobrir recursos em toda a organização usando consultas de linguagem natural com correspondência semântica, palavras-chave e predicados estruturados. É possível procurar recursos de dados específicos, explorar metadados relevantes em todos os sistemas ou recuperar resultados com escopo para Agentic Workflows programáticos e de agentes.

Casos de uso

A lista a seguir descreve casos de uso comuns de pesquisa, além de descrições e exemplos de consultas:

  • Pesquisa de recursos segmentados: encontre um recurso específico pesquisando palavras-chave relacionadas ao nome, às colunas ou à descrição dele.

    Exemplo de consultas

    • retail_transactions_2026
    • customer_id
    • column:customer_id

  • Descoberta ampla de dados: identifique recursos relevantes em toda a organização usando consultas de linguagem natural ou palavras-chave abertas.

    Exemplo de consultas

    • quarterly financial reports
    • ad campaign click through rates tables
    • server health metrics
    • audit logs system=bigquery

  • Recuperação de recursos com escopo para fluxos de trabalho: enumere recursos em um contêiner específico, como um projeto, ou com propriedades específicas, como tipo ou sistema. Essa abordagem é frequentemente usada para fluxos de trabalho programáticos e de agentes.

    Exemplo de consultas

    • type=table projectid:banking-prod aspect:classification.tier=PII
    • system=spanner projectid:inventory-service (parent=marketing_analytics OR parent=finance_analytics)

Como funciona

A pesquisa indexa automaticamente todo o contexto dos recursos de dados mantidos no Knowledge Catalog. Isso inclui o seguinte:

  • Metadados ingeridos automaticamente de fontes de dados do Google Cloud , como o BigQuery e o Cloud SQL
  • Contexto para recursos ingeridos por conectores e integrações
  • Contexto adicional que você cria para recursos, por exemplo, representando o contexto de negócios ou descrevendo a semântica de dados. O contexto também pode ser capturado na forma de aspectos ou termos de negócios vinculados.

Ao processar sua consulta, a pesquisa aplica uma combinação de correspondência semântica e de palavras-chave. A tabela a seguir descreve os tipos de consulta que podem ser usados com a pesquisa do Knowledge Catalog, além de descrições e exemplos de consultas:

Tipo de consulta Uso Exemplos
Palavra-chave única Para correspondência exata e de substring em elementos de metadados, como nome, descrição e esquema do recurso. prd_fin_invoices_fct_v02
Palavras-chave parciais e fragmentos tokenizados Faz a correspondência de substrings em todo o conteúdo de metadados, encontrando recursos mesmo com termos abreviados, palavras separadas ou variações de nomenclatura. fin transactions 2026 (corresponde a prd_fin_transactions_fy2026_raw)
Consultas em linguagem natural Usa correspondência semântica sem exigir correspondências exatas de nome ou coluna. customer churn prediction features
Predicados estruturados Combina consultas de texto livre com filtros de predicado explícitos para restringir os resultados da pesquisa. audit logs system=bigquery
Sintaxe estendida Para uma pesquisa precisa, restrita a um escopo específico. A sintaxe estendida é mais usada em casos de uso agênticos e programáticos. Para mais informações, consulte Sintaxe de pesquisa. (system:bigquery OR system:spanner) AND column:credit_card_number aspect:classification.tier=PII -projectid:sandbox-project

Você tem as seguintes opções para acessar a pesquisa no Knowledge Catalog:

Escopo de pesquisa

Os resultados da pesquisa no Knowledge Catalog respeitam as permissões que você tem sobre os recursos correspondentes nos sistemas de origem.

Por exemplo, se você tiver acesso de leitura de metadados do BigQuery a um objeto, ele vai aparecer nos resultados da pesquisa do Knowledge Catalog. Se você tiver acesso a uma tabela do BigQuery, mas não ao conjunto de dados que a contém, ela ainda vai aparecer como esperado na pesquisa do Knowledge Catalog.

Por padrão, a pesquisa é limitada à sua organização. Os resultados incluem apenas recursos da mesma organização do projeto em que você está pesquisando.

Os resultados da pesquisa incluem apenas os recursos que pertencem ao mesmo perímetro do VPC Service Controls que o projeto em que a pesquisa é realizada. Ao usar o console doGoogle Cloud , esse é o projeto selecionado no console.

Para ampliar o escopo dos resultados da pesquisa além dos recursos no perímetro do VPC Service Controls do projeto, use as regras de entrada e saída do VPC Service Controls. Essas regras facilitam a troca de dados privada e eficiente em toda a organização. É possível configurar regras de entrada e saída usando o console doGoogle Cloud ou arquivos JSON ou YAML. Consulte o exemplo de YAML a seguir e a documentação do VPC Service Controls para adaptar a regra aos seus requisitos específicos.

egressPolicies:
  - egressFrom:
      identityType: ANY_USER_ACCOUNT
    egressTo:
      # Specify which resources should be present in the search results. In this example,
      # BigQuery.
      operations:
      - methodSelectors:
        - method: '*'
        serviceName: bigquery.googleapis.com
      # Specify project ids under which the search is performed.
      resources:
      - projects/SEARCH_PROJECT_ID
ingressPolicies:
  - ingressFrom:
      identityType: ANY_USER_ACCOUNT
      sources:
      - accessLevel: '*'
    ingressTo:
      # Specify which resources should be present in the search results. In this example,
      # BigQuery.
      operations:
      - methodSelectors:
        - method: '*'
        serviceName: bigquery.googleapis.com
      # Specify project ids to expose in search results.
      resources:
      - projects/INGRESS_PROJECT_ID

Para mais informações sobre os papéis do Identity and Access Management necessários para usar a pesquisa do Knowledge Catalog, consulte Papéis do IAM do Knowledge Catalog.

Isolar os resultados da pesquisa por ambiente usando o VPC Service Controls

Para isolar os resultados da pesquisa do Knowledge Catalog entre ambientes, como desenvolvimento, teste e produção, configure perímetros separados do VPC Service Controls para cada ambiente. Atribua os projetos que contêm os recursos de dados e os projetos usados para realizar pesquisas ao perímetro do ambiente correspondente. As pesquisas realizadas em um projeto dentro de um perímetro específico retornam apenas resultados de recursos localizados nesse mesmo perímetro.

Limitações de recall na pesquisa

A pesquisa do Knowledge Catalog é otimizada para descoberta exploratória, em vez de recuperação exaustiva de inventário. Portanto, as consultas de pesquisa não garantem o recall completo. Uma consulta pode omitir resultados correspondentes, e os resultados retornados podem variar entre consultas repetidas.

Causas da perda de recall

Quando você faz uma pesquisa, o Knowledge Catalog verifica dinamicamente suas permissões em relação a um limite de controle de acesso de 600 restrições (regras de avaliação de permissão). Se a verificação de acesso exceder esse limite, o sistema vai interromper a verificação antecipadamente para manter as pesquisas rápidas. Quando isso acontece, a pesquisa pode deixar de fora recursos correspondentes.

É mais provável que você atinja esse limite se alguma das seguintes condições se aplicar:

  • papéis do IAM atribuídos diretamente a centenas de recursos individuais.
  • Associações em muitos Grupos do Google que concedem acesso a recursos individuais.
  • Associações em Grupos do Google que têm acesso concedido diretamente a centenas de recursos individuais.

Resolver limitações de recall e resultados ausentes

Para resolver problemas de recall ou recuperar metadados completos, escolha a abordagem que corresponde à sua meta:

  • Para corrigir resultados de pesquisa ausentes ou inconsistentes:reduza o total de verificações de acesso para ficar abaixo do limite de 600 restrições. Conceda acesso apenas aos recursos necessários e remova o acesso de recursos ou Grupos do Google em que você não precisa de permissões. Também é possível conceder papéis no nível do projeto ou da pasta, em vez de em recursos individuais.
  • Para recuperar um inventário de metadados completo e garantido:não use a pesquisa. Em vez disso, exporte metadados para o Cloud Storage e consulte o conjunto de dados completo com o BigQuery.

A seguir