Sintaxe de pesquisa do Catálogo de Conhecimento

Observação: a pesquisa do Knowledge Catalog oferece suporte à correspondência semântica e de palavra-chave. Ele também oferece suporte ao modo de pesquisa somente por palavras-chave para compatibilidade com versões anteriores. Para informações sobre a pesquisa somente por palavra-chave, os filtros e como usar esse recurso, consulte Pesquisa somente por palavra-chave.

Com o Knowledge Catalog, é possível descobrir, catalogar de forma centralizada, gerenciar e entender os dados da sua organização. Para encontrar recursos de dados específicos no catálogo de dados com eficiência, use consultas de pesquisa avançadas. A sintaxe das consultas de pesquisa inclui:

• Pesquisa simples: encontrar recursos de dados usando um único termo de pesquisa.
• Pesquisa de texto livre: encontrar recursos de dados usando frases ou palavras-chave em linguagem natural.
• Predicados qualificados: refinam sua pesquisa usando campos de metadados específicos, como nome, local, sistema ou tipo.
• Pesquisa de aspectos: pesquisa de entradas com base nos metadados comerciais e técnicos anexados.
• Operadores lógicos: combinam vários critérios de pesquisa usando os operadores AND, OR ou NOT para criar consultas complexas. Ao entender essa sintaxe, você pode localizar rapidamente os dados necessários.

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 nome, tipo ou sistema de um recurso.

Você pode qualificar um predicado usando um prefixo com uma chave que restringe a correspondência a uma parte específica dos metadados:

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

A tokenização divide o fluxo de texto em uma série de tokens, cada um geralmente correspondente a uma 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 a recursos em um local especificado com foo como 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 x como substring do nome de exibição do recurso.
column:x	Corresponde x como uma substring do nome da coluna (ou nome da coluna aninhada) no esquema do recurso.
description:x	Corresponde 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 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 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 do tipo. Requer o qualificador =.
projectid:bar	Corresponde a recursos em projetos Google Cloud que correspondem abarcomo 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 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 oferecem suporte a esse qualificador usando o nome do local do BigQuery Omni. Por exemplo, location=aws-us-east-1 corresponde a recursos do BigQuery Omni no norte da Virgínia.
createtime	Encontra recursos criados em, antes ou depois de uma determinada data, carimbo de data/hora ou período relativo em dias. Para conferir os formatos e operadores aceitos, consulte Filtros de tempo.
updatetime	Encontra recursos que foram atualizados em, antes ou depois de uma determinada data, carimbo de data/hora ou período 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) aceitam apenas o qualificador de correspondência exata (=), não o 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 são compatíveis com a correspondência de substrings com o qualificador de dois pontos (:):

• name:transactions corresponde a recursos cujo ID ou nome de exibição contém 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 cujo ID contém prod. Por exemplo, finance-prod-2026.

Filtros de tempo

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

Operadores e formatos compatíveis

• Operadores compatíveis: :, =, <, >, <=, >=, =>, =<
• Dias relativos (-Nd): filtre por um número relativo de dias no passado (por exemplo, -30d, -7d, -1d).
• Datas do calendário (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. Timestamps 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 período:

Categoria de formato	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 tempo relativo. Unidades mais curtas (horas h, minutos m) e mais longas (semanas w, meses m) não são aceitas. Offsets positivos sem um sinal de subtração inicial (-) 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 são GMT (como -08:00 ou +05:30) e abreviações de fuso horário (como EST ou PST) não são compatíveis.
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 período 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 aceitas nos 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, independente do valor.
labels:KEY_SUBSTRING	labels:tier	Corresponde a recursos com uma chave de rótulo que contém tier como 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 do rótulo owner em que o valor contém analytics como uma substring (como analytics-team ou data-analytics).
Vários rótulos (E)	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 a 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.
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 aspectos 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 proporção personalizada: 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, da seguinte forma: String: = (correspondência exata) Todos os tipos de números: =, :, <, >, <=, >=, =>, =< Enum: = Data e hora: igual aos números, mas os valores a serem comparados são tratados como datas e horas em vez de números. Booleano: = Somente campos de nível superior do aspecto podem ser pesquisados.

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 AND lógico será implícito, o que significa que não é necessário 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 em conjuntos de dados de marketing ou finanças

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

Operador NOT

É possível negar um predicado usando um prefixo 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 sandbox

  • Usar o operador NOT

  type=table NOT projectid:sandbox-project
  

  • Usar hífen

  type=table -projectid:sandbox-project
  

• Encontre todos os recursos do BigQuery que não contêm test no nome

  system=bigquery -name:test
  

Sintaxe abreviada

Se 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 correspondem a vários nomes de colunas (AND)

  column:(customer_id,transaction_date,amount)
  

• Pesquisar entradas que correspondam a qualquer um dos vários nomes de colunas (OR)

  column:(customer_id|user_id|client_id)
  

Política de curinga

A sintaxe de pesquisa do Knowledge Catalog não é compatível com caracteres curinga, como * ou ?, em strings de consulta ou predicados.

Se você incluir um asterisco (*) ou ponto de interrogação (?) em uma consulta, eles serão tratados como caracteres literais, e não como curingas de correspondência de padrões.

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

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

Parênteses

Os parênteses em 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 reduzir a qualidade dos resultados.

Linguagem natural simples

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

Find customer orders containing email addresses

Sintaxe abreviada de predicado

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 em qualquer um dos projetos listados usando (|)

    projectid:(finance-prod|finance-test|analytics-raw)
    

  • Pesquise entradas 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, o que leva 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 de lógica 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 eles 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.