Sobre a pesquisa no Knowledge Catalog

Use a pesquisa do Knowledge Catalog (antigo Dataplex Universal Catalog) para descobrir recursos na sua organização usando consultas de linguagem natural com correspondência semântica, palavras-chave e predicados estruturados.

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 direcionada: encontre um recurso específico pesquisando palavras-chave relacionadas ao nome, às colunas ou à descrição do recurso.

    Exemplo de consultas

    • retail_transactions_2026
    • customer_id
    • column:customer_id

  • Descoberta de dados ampla: identifique recursos relevantes na sua 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 é usada com frequência para fluxos de trabalho programáticos e agênticos.

    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 Google Cloud fontes de dados, como o BigQuery e o Cloud SQL
  • Contexto para recursos ingeridos por conectores e integrações
  • Contexto adicional criado 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 comerciais vinculados.

Ao processar a 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 substrings em elementos de metadados, como nome, descrição e esquema de recursos. prd_fin_invoices_fct_v02
Palavras-chave parciais e fragmentos tokenizados Corresponde a substrings no 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 de linguagem natural Usa a correspondência semântica sem exigir correspondências exatas de nome ou coluna matches. 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 pesquisa precisa, restrita a um escopo específico. A sintaxe estendida é usada com mais frequência 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 contém essa tabela, ela ainda vai aparecer como esperado na pesquisa do Knowledge Catalog.

Por padrão, a pesquisa tem escopo para sua organização. Os resultados incluem apenas recursos da mesma organização que o 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 Google Cloud console, 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 Google Cloud console 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 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 só retornam resultados para 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 total. Uma consulta pode omitir resultados correspondentes, e os resultados retornados podem variar entre consultas repetidas.

Causas da perda de recall

Ao pesquisar, 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 parar a verificação mais cedo 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 for verdadeira:

  • Papéis do IAM atribuídos diretamente a centenas de recursos individuais.
  • Participações em muitos Grupos do Google que concedem acesso a recursos individuais.
  • Participaçõ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 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