A partir de 10 de abril de 2026, o Dataplex Universal Catalog será chamado de Knowledge Catalog. Os nomes da API, da biblioteca de cliente, da CLI e do IAM permanecem inalterados. Para mais informações, consulte Apresentação do Knowledge Catalog do Google Cloud.

O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Sintaxe de pesquisa do Catálogo de Conhecimento

As consultas de pesquisa no Knowledge Catalog permitem encontrar recursos de dados específicos no catálogo usando correspondência semântica e de palavras-chave. Ao combinar linguagem natural, filtros de metadados e operadores lógicos, é possível localizar entradas relevantes para descobrir, gerenciar e entender os dados da sua organização.

O Knowledge Catalog também oferece suporte a um modo de pesquisa somente por palavras-chave para compatibilidade com versões anteriores. Para mais informações sobre esse modo, os filtros dele e como usá-lo, consulte Pesquisa somente por palavra-chave.

Visão geral da sintaxe de consulta

É possível criar consultas de pesquisa do Knowledge Catalog usando os seguintes componentes:

Pesquisa simples: encontre recursos de dados usando um único termo de pesquisa.
Pesquisa de texto livre: encontre recursos de dados usando frases em linguagem natural ou palavras-chave.
Predicados qualificados: refine sua pesquisa usando campos de metadados específicos, como nome, local, sistema ou tipo.
Pesquisa de aspectos: pesquise entradas com base nos metadados comerciais e técnicos anexados.
Operadores lógicos: combine vários critérios de pesquisa usando os operadores AND, OR ou NOT para criar consultas complexas.

Predicados qualificados

Use um predicado qualificado para restringir os resultados da pesquisa instruindo explicitamente a pesquisa a avaliar um campo de metadados específico, como um nome, tipo ou sistema de recurso.

É possível qualificar um predicado prefixando-o com uma chave que restringe a correspondência a um metadado específico:

Um sinal de igual (=) para restringir a pesquisa a uma correspondência exata.
Dois-pontos (:) após a chave para corresponder o predicado a uma substring ou a um token no valor nos resultados da pesquisa.

A tokenização divide o fluxo de texto em uma série de tokens, em que cada token geralmente corresponde a uma única palavra.

Exemplo:

name:foo seleciona recursos com nomes que contêm a substring foo, como foo1 e barfoo.
description:foo seleciona recursos com o token foo na descrição, como bar e foo.
location=foo corresponde aos recursos em um local especificado com foo como o nome do local.

Qualificadores compatíveis

A pesquisa do Knowledge Catalog é compatível com os seguintes qualificadores:

Qualificador	Descrição
`name:x`	Corresponde a `x` como uma substring do ID ou do nome de exibição do recurso.
`displayname:x`	Corresponde a `x` como uma substring do nome de exibição do recurso.
`column:x`	Corresponde a `x` como uma substring do nome da coluna (ou nome da coluna aninhada) no esquema do recurso.
`description:x`	Corresponde a `x` como um token na descrição do recurso. Por exemplo: `description:"products"` mostra todos os recursos que têm o token `products` na descrição. Por exemplo, "lista de produtos no inventário". `description:"prod"` não mostra os recursos que têm o token `products` na descrição. Em vez disso, ele mostra todos os recursos que têm o token `prod` na descrição. Por exemplo, "ambiente de produção".
`labels:bar`	Corresponde a recursos que têm um rótulo (com algum valor) e a chave do rótulo tem `bar` como uma substring.
`labels=bar`	Corresponde a recursos que têm um rótulo (com algum valor) e a chave do rótulo é igual a `bar` como uma string.
`labels.bar:x`	Corresponde a `x` como uma substring no valor de um rótulo com a chave `bar` anexada a um recurso.
`labels.foo=bar`	Corresponde a recursos em que a chave é igual a `foo` e o valor da chave é igual a `bar`.
`type=TYPE`	Corresponde a recursos de um tipo de entrada específico ou ao alias de tipo dele. Requer o qualificador `=`.
`projectid:bar`	Corresponde a recursos em projetos do Google Cloud que correspondem a `bar` como uma substring no ID.
`parent:x`	Corresponde a `x` como uma substring do caminho hierárquico de um recurso.
`system=SYSTEM`	Corresponde a recursos de um sistema especificado. Requer o qualificador `=`.
`location=LOCATION`	Corresponde a recursos em um local especificado com um nome exato. Requer o qualificador `=`. Por exemplo, `location=us-central1` corresponde a recursos hospedados em Iowa. Os recursos do BigQuery Omni são compatíveis com esse qualificador usando o nome do local do BigQuery Omni. Por exemplo, `location=aws-us-east-1` corresponde aos recursos do BigQuery Omni no norte da Virgínia.
`createtime`	Encontra recursos que foram criados em, antes ou depois de uma determinada data, carimbo de data/hora ou tempo relativo em dias. Para conferir os formatos e operadores compatíveis, consulte Filtros de tempo.
`updatetime`	Encontra recursos que foram atualizados em, antes ou depois de uma determinada data, carimbo de data/hora ou tempo relativo em dias. Para conferir os formatos e operadores aceitos, consulte Filtros de tempo.

Qualificadores de correspondência exata

As chaves de predicado type, system, location e a pesquisa de aspectos (exceto has) são compatíveis apenas com o qualificador de correspondência exata (=), não com o qualificador de substring (:).

Use a seguinte sintaxe de correspondência exata para esses predicados:

Chave de predicado	Sintaxe correta	Sintaxe incorreta
`type`	`type=table` (ou `type=view`, `type=dataset`)	`type:table` ou `type:tab`
`system`	`system=bigquery` (ou `system=spanner`)	`system:bigquery` ou `system:big`
`location`	`location=us-central1` (ou `location=europe-west1`)	`location:us-central1` ou `location:us`

Qualificadores de substring

Predicados como name, displayname, column, projectid e parent oferecem suporte à correspondência de substring com o qualificador de dois pontos (:):

name:transactions corresponde a recursos com ID ou nome de exibição que contenham transactions. Por exemplo, daily_transactions_raw e transactions_v2.
column:customer_id corresponde a recursos com um nome de coluna que contém customer_id.
projectid:prod corresponde a recursos em projetos com ID que contém prod. Por exemplo, finance-prod-2026.

Filtros de tempo

É possível filtrar recursos por horário de criação (createtime) ou horário da última atualização (updatetime).

Operadores e formatos compatíveis

Operadores aceitos: :, =, <, >, <=, >=, =>, =<
Dias relativos (-Nd): filtre por um número relativo de dias no passado (por exemplo, -30d, -7d, -1d).
Datas da agenda (YYYY-MM-DD ou YYYY/MM/DD): filtre por uma data específica em GMT/UTC.
Carimbos de data/hora completos (YYYY-MM-DDTHH:MM:SS ou YYYY-MM-DDTHH:MM:SSZ): filtre por um carimbo de data/hora preciso em GMT/UTC. Carimbos de data/hora parciais, como YYYY-MM-DDTHH:MM ou YYYY-MM-DDTHH, também são aceitos.

Sintaxe do filtro de tempo

A tabela a seguir explica a sintaxe do filtro de tempo:

Categoria dos formatos	Sintaxe válida	Sintaxe inválida	Descrição
Unidades de tempo relativas	`createtime>-30d` (últimos 30 dias) `createtime<=-7d` (há 7 dias ou mais) `updatetime=-1d` (dia anterior) `updatetime>=-90d`	`createtime>-24h` `createtime>-60m` `createtime>-2w` `createtime>30d`	Somente unidades de dia negativas (`-Nd`) são aceitas para o tempo relativo. Unidades mais curtas (horas `h`, minutos `m`) e mais longas (semanas `w`, meses `m`) não são aceitas. Desvios positivos sem um sinal de subtração à esquerda (`-`) são inválidos.
Datas da agenda	`createtime:2025-01-15` `createtime>2025-01-01` `createtime<=2025-06-30` `createtime:2025/01/15` `createtime:2025-01` `createtime:2025`	`createtime:15-01-2025` `createtime:Jan-15-2025` `createtime:01/15/2025`	As datas precisam seguir o formato `YYYY-MM-DD` ou `YYYY/MM/DD`. Formatos com ordem de componentes não padrão (como `DD-MM-YYYY` ou `MM/DD/YYYY`) ou nomes de meses são inválidos.
Carimbos de data/hora e fusos horários	`createtime:2025-01-15T05:30:00` `createtime>2025-01-15T05:30:00Z` `createtime:2025-01-15T05:30`	`createtime:2025-01-15T05:30:00-08:00` `createtime:2025-01-15T05:30:00 EST` `createtime:2025-01-15T05:30:00+05:30`	Todos os carimbos de data/hora são avaliados em GMT/UTC. Diferenças de fuso horário que não sejam GMT (como `-08:00` ou `+05:30`) e abreviações de fuso horário (como `EST` ou `PST`) não são aceitas.
Intervalos de hora do dia	`createtime>=2025-01-15T09:00:00 createtime<=2025-01-15T17:00:00`	`createtime:09:00:00..17:00:00` `createtime:09:00-17:00`	A sintaxe de intervalo de hora do dia não é compatível. Em vez disso, use comparações separadas de limite inferior e superior com strings completas de data e hora.
Datas em linguagem natural	`createtime=-1d` `createtime>-30d`	`createtime:yesterday` `createtime:"last week"` `createtime:today`	Frases de data em linguagem natural não são compatíveis com os qualificadores `createtime` ou `updatetime`. Use a sintaxe de dia relativo (`-1d`, `-7d`) ou datas explícitas.

Filtros de rótulo

Use o predicado labels para filtrar recursos por rótulos anexados. É possível filtrar por chave de rótulo, valor de rótulo ou ambos:

Padrão de consulta	Exemplo	Descrição
`labels=KEY`	`labels=environment`	Corresponde a recursos que têm um rótulo com a chave exata `environment`, independentemente do valor.
`labels:KEY_SUBSTRING`	`labels:tier`	Corresponde a recursos com uma chave de rótulo que contém `tier` como uma substring (como `service_tier` ou `storage_tier`).
`labels.KEY=VALUE`	`labels.env=prod`	Corresponde a recursos em que a chave do rótulo é `env` e o valor é exatamente `prod`.
`labels.KEY:VALUE_SUBSTRING`	`labels.owner:analytics`	Corresponde a recursos com a chave de rótulo `owner` em que o valor contém `analytics` como uma substring (como `analytics-team` ou `data-analytics`).
Vários rótulos (AND)	`labels.env=prod labels.data_tier=tier1`	Corresponde a recursos que têm os rótulos `env=prod` e `data_tier=tier1` anexados.
Combinado com sistema e tipo	`system=bigquery type=table labels.env=prod labels.confidentiality=high`	Corresponde às tabelas do BigQuery rotuladas com `env=prod` e `confidentiality=high`.

Pesquisa de aspectos

É possível usar a sintaxe de consulta para pesquisar entradas com base nos aspectos anexados.

A correspondência de substring tenta corresponder a um número limitado de aspectos. Se não for possível encontrar a entrada usando um fragmento do caminho, use o caminho completo para restringir a pesquisa e aumentar o recall.

Qualificador Descrição

aspect:x
ou
has:x Corresponde a x como uma substring do caminho completo para o tipo de aspecto de um aspecto anexado à entrada, no formato projectid.location.ASPECT_TYPE_ID.

aspect=x
ou
has=x Corresponde a x como o caminho completo para o tipo de aspecto de um aspecto anexado à entrada, no formato projectid.location.ASPECT_TYPE_ID.

Qualificador	Descrição
`aspect:x` ou `has:x`	Corresponde a `x` como uma substring do caminho completo para o tipo de aspecto de um aspecto anexado à entrada, no formato `projectid.location.ASPECT_TYPE_ID`.
`aspect=x` ou `has=x`	Corresponde a `x` como o caminho completo para o tipo de aspecto de um aspecto anexado à entrada, no formato `projectid.location.ASPECT_TYPE_ID`.
`x OPERATOR value`	Pesquisa valores de campo de aspecto. Corresponde a `x` como uma substring do caminho completo para o tipo de aspecto e o nome do campo de um aspecto anexado à entrada, nos seguintes formatos: Sintaxe para tipos de aspecto do sistema: `ASPECT_TYPE_ID.FIELD_NAME` `dataplex-types.ASPECT_TYPE_ID.FIELD_NAME` `dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME` Por exemplo, as consultas a seguir correspondem a entradas em que o valor do campo `type` no aspecto `bigquery-dataset` é `default`: `bigquery-dataset.type=default` `dataplex-types.bigquery-dataset.type=default` `dataplex-types.global.bigquery-dataset.type=default` Sintaxe para tipos de aspecto personalizados: Se o aspecto for criado na região global: `PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME` Se o aspecto for criado em uma região específica: `PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME` Por exemplo, as consultas a seguir correspondem a entradas em que o valor do campo `is-enrolled` no aspecto `employee-info` é `true`. `example-project.us-central1.employee-info.is-enrolled=true` `example-project.employee-info.is-enrolled=true` A lista de operadores compatíveis depende do tipo de campo no aspecto, conforme mostrado abaixo: String: `=` (correspondência exata) Todos os tipos de números: `=`, `:`, `<`, `>`, `<=`, `>=`, `=>`, `=<` Tipo enumerado: `=` Data e hora: o mesmo que para números, mas os valores a serem comparados são tratados como data e hora em vez de números. Booleano: `=` Somente os campos de nível superior do aspecto são pesquisáveis.

x
OPERATOR
value

Pesquisa valores de campo de aspecto. Corresponde a x como uma substring do caminho completo para o tipo de aspecto e o nome do campo de um aspecto anexado à entrada, nos seguintes formatos:

Sintaxe para tipos de aspecto do sistema:
- ASPECT_TYPE_ID.FIELD_NAME
- dataplex-types.ASPECT_TYPE_ID.FIELD_NAME
- dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME
Por exemplo, as consultas a seguir correspondem a entradas em que o valor do campo type no aspecto bigquery-dataset é default:
- bigquery-dataset.type=default
- dataplex-types.bigquery-dataset.type=default
- dataplex-types.global.bigquery-dataset.type=default
Sintaxe para tipos de aspecto personalizados:
- Se o aspecto for criado na região global: PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME
- Se o aspecto for criado em uma região específica: PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME
Por exemplo, as consultas a seguir correspondem a entradas em que o valor do campo is-enrolled no aspecto employee-info é true.
- example-project.us-central1.employee-info.is-enrolled=true
- example-project.employee-info.is-enrolled=true
A lista de operadores compatíveis depende do tipo de campo no aspecto, conforme mostrado abaixo:
- String: = (correspondência exata)
- Todos os tipos de números: =, :, <, >, <=, >=, =>, =<
- Tipo enumerado: =
- Data e hora: o mesmo que para números, mas os valores a serem comparados são tratados como data e hora em vez de números.
- Booleano: =

Somente os campos de nível superior do aspecto são pesquisáveis.

Operadores lógicos

Uma consulta pode combinar vários predicados usando operadores lógicos. Observação: os operadores lógicos AND, OR e NOT diferenciam maiúsculas de minúsculas e precisam estar em letras maiúsculas.

Operador `AND`

Se você separar vários termos de pesquisa ou predicados com um espaço, o operador lógico AND será implícito, o que significa que você não precisa escrevê-lo explicitamente.

Os exemplos a seguir mostram como criar consultas com o operador AND.

Pesquisar tabelas do BigQuery
```
system=bigquery type=table
```
Pesquisar recursos no projeto banking-prod com uma coluna chamada customer_id
```
projectid:banking-prod column:customer_id
```

Se necessário, use o operador AND explícito:

system=bigquery AND type=table AND location=us-central1

Operador `OR`

Use o operador OR para corresponder a qualquer uma das várias condições. Ao combinar OR com outros critérios, use parênteses ( ) para agrupar as expressões e definir a precedência.

Os exemplos a seguir mostram como criar consultas com o operador OR.

Pesquisar tabelas e visualizações do BigQuery
```
system=bigquery (type=table OR type=view)
```

Pesquisar tabelas em vários sistemas

(system=bigquery OR system=spanner) type=table

Pesquisar entradas nos conjuntos de dados de marketing ou finanças

system=bigquery (parent:marketing_analytics OR parent:finance_analytics)

Operador `NOT`

É possível negar um predicado prefixando-o com NOT em maiúsculas ou um - (hífen).

Os exemplos a seguir mostram como criar consultas com o operador NOT.

Encontrar todas as tabelas, exceto as de um projeto de sandbox
- Usar o operador NOT
```
type=table NOT projectid:sandbox-project
```
- Usar hífen
```
type=table -projectid:sandbox-project
```
Encontrar todos os recursos do BigQuery que não contêm test no nome
```
system=bigquery -name:test
```

Sintaxe abreviada

Se você quiser usar a sintaxe abreviada, use | (barra vertical) para operadores OR e , (vírgula) para operadores AND entre parênteses. Essa sintaxe abreviada funciona para os predicados qualificados.

Pesquisar em vários IDs de projeto

Use o operador OR:

projectid:(finance-prod|sales-prod|analytics-prod)

Use parênteses:

projectid:finance-prod OR projectid:sales-prod OR projectid:analytics-prod

Pesquisar entradas que correspondam a vários nomes de coluna (AND)
```
column:(customer_id,transaction_date,amount)
```
Pesquisar entradas que correspondam a qualquer um dos vários nomes de coluna (OR)
```
column:(customer_id|user_id|client_id)
```

Política de caracteres curinga

A sintaxe de pesquisa do Knowledge Catalog não aceita caracteres curinga, como * ou ?, em strings de consulta ou predicados.

Se você incluir um asterisco (*) ou um ponto de interrogação (?) em uma consulta, ele será tratado como um caractere literal, e não como um caractere curinga de correspondência de padrão.

Por exemplo, para pesquisar tabelas com nomes que terminam com _masked:

Compatível: name:_masked : usa o qualificador de correspondência de substring : para encontrar todos os recursos com nome que contenha _masked, como customer_records_masked ou transactions_masked.
Não aceito: name:*_masked: o * é tratado como um caractere literal, não como um caractere curinga de padrão.

Parênteses

Os parênteses nas consultas de pesquisa têm funções técnicas específicas. Se você usar parênteses em excesso ou aplicá-los a consultas em linguagem natural, poderá confundir o analisador de pesquisa e prejudicar a qualidade dos resultados.

Linguagem natural simples

Ao fazer uma pergunta de negócios, envie a consulta em texto simples. Não coloque entre parênteses. Por exemplo, escreva:

Find customer orders containing email addresses

Sintaxe de predicado abreviada

Os parênteses são muito eficazes quando usados com chaves de predicado para listar várias condições OR e AND em um formato compacto.

Agrupar chaves de predicado com OR (|)
- Pesquise entradas que residem em qualquer um dos projetos listados usando (|)
```
projectid:(finance-prod|finance-test|analytics-raw)
```
- Pesquise entradas que residem em qualquer um dos projetos listados usando (OR)
```
projectid:finance-prod OR projectid:finance-test OR projectid:finance-raw
```
Agrupar chaves de predicado com AND (,)
- Pesquise entradas que contenham todas as colunas especificadas usando (,)
```
column:(customer_id, order_date, total_amount)
```
- Pesquise entradas que contenham todas as colunas especificadas usando (AND)
```
column:customer_id AND column:order_date AND column:total_amount
```

Pesquisa híbrida

É possível combinar uma consulta em linguagem natural com filtros compactos.

Por exemplo, para encontrar tabelas que especificam usuários ativos por mês, mas restringir a pesquisa aos projetos especificados, use a seguinte consulta:

monthly active users type=table projectid:(data-warehouse|analytical-tier)

Práticas recomendadas para usar parênteses

Não coloque a pergunta inteira entre parênteses, porque o mecanismo semântico pode tratar os parênteses como caracteres literais, levando a resultados de baixa relevância.
- Incorreto: (Show me datasets about US population by state)
- Correto: Show me datasets about US population by state
Evite misturar árvores booleanas complexas e aninhadas com parênteses no campo de linguagem natural. A pesquisa é otimizada para a intenção de linguagem natural. Complicar demais a consulta com parênteses e blocos lógicos explícitos confunde o analisador.
- Incorreto: (revenue data) AND system=BIGQUERY AND projectid:(data-warehouse | analytical-tier)
- Correto: revenue data system=bigquery projectid:(data-warehouse|analytical-tier)
Não adicione espaços arbitrariamente, a menos que façam parte do valor.
- Incorreto: column:( email | id )
- Correto: column:(email|id).

A seguir

Saiba como pesquisar recursos no Knowledge Catalog
Saiba mais sobre o gerenciamento de metadados no Knowledge Catalog.
Saiba como enriquecer entradas e links de entrada com metadados usando aspectos.
Saiba como gerenciar entradas e ingerir fontes personalizadas.

Sintaxe de pesquisa do Catálogo de Conhecimento Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.