Sintaxis de búsqueda de Knowledge Catalog

Las búsquedas en Knowledge Catalog te permiten encontrar recursos de datos específicos en tu catálogo con la concordancia semántica y de palabras clave. Si combinas el lenguaje natural, los filtros de metadatos y los operadores lógicos, puedes ubicar entradas relevantes para descubrir, administrar y comprender los datos de tu organización.

Knowledge Catalog también admite un modo de búsqueda solo por palabras clave para la retrocompatibilidad. Para obtener más información sobre este modo, sus filtros y cómo usarlo, consulta Búsqueda solo por palabras clave.

Descripción general de la sintaxis de las consultas

Puedes construir consultas de búsqueda de Knowledge Catalog con los siguientes componentes:

  • Búsqueda simple: Encuentra recursos de datos con un solo término de búsqueda.
  • Búsqueda de texto libre: Encuentra recursos de datos con frases o palabras clave en lenguaje natural.
  • Predicados calificados: Define mejor tu búsqueda con campos de metadatos específicos, como nombre, ubicación, sistema o tipo.
  • Búsqueda por aspectos: Busca entradas en función de los metadatos técnicos y empresariales adjuntos.
  • Operadores lógicos: Combina varios criterios de búsqueda con los operadores AND, OR o NOT para crear consultas complejas.

Predicados calificados

Usa un predicado calificado para acotar los resultados de la búsqueda indicándole de forma explícita a la búsqueda que evalúe un campo de metadatos específico, como el nombre, el tipo o el sistema de un recurso.

Puedes calificar un predicado agregándole un prefijo con una clave que restrinja la coincidencia a un fragmento específico de metadatos:

  • Un signo igual (=) para restringir la búsqueda a una coincidencia exacta
  • Dos puntos (:) después de la clave para que el predicado coincida con una subcadena o un token dentro del valor en los resultados de la búsqueda.

La asignación de token divide el flujo de texto en una serie de tokens, y cada token suele corresponder a una sola palabra.

Por ejemplo:

  • name:foo selecciona recursos con nombres que contienen la subcadena foo, como foo1 y barfoo.
  • description:foo selecciona recursos con el token foo en la descripción, como bar y foo.
  • location=foo hace coincidir los recursos en una ubicación especificada con foo como el nombre de la ubicación.

Calificadores compatibles

La búsqueda de Knowledge Catalog admite los siguientes calificadores:

Calificador Descripción
name:x Coincide con x como una subcadena del ID del recurso o el nombre visible del recurso.
displayname:x Coincide con x como una subcadena del nombre visible del recurso.
column:x Coincide con x como una subcadena del nombre de la columna (o el nombre de la columna anidada) en el esquema del recurso.
description:x Coincide con x como un token en la descripción del recurso. Por ejemplo:
  • description:"products" muestra todos los recursos que tienen el token products en la descripción. Por ejemplo, "lista de productos en el inventario".
  • description:"prod" no muestra los recursos que tienen el token products en la descripción. En cambio, muestra todos los recursos que tienen el token prod en la descripción. Por ejemplo, "entorno de producción".
labels:bar Coincide con los recursos que tienen una etiqueta (con algún valor) y la clave de etiqueta tiene bar como una subcadena.
labels=bar Coincide con los recursos que tienen una etiqueta (con algún valor) y la clave de etiqueta es igual a bar como una cadena.
labels.bar:x Coincide con x como una subcadena en el valor de una etiqueta con la clave bar adjunta a un recurso.
labels.foo=bar Coincide con los recursos en los que la clave es igual a foo y el valor de la clave es igual a bar.
type=TYPE Coincide con los recursos de un tipo de entrada específico o su alias de tipo. Requiere el calificador =.
projectid:bar Coincide con los recursos dentro de los proyectos de Google Cloud que coinciden con bar como una subcadena en el ID.
parent:x Coincide con x como una subcadena de la ruta de acceso jerárquica de un recurso.
system=SYSTEM Coincide con los recursos de un sistema especificado. Requiere el calificador =.
location=LOCATION

Coincide con los recursos de una ubicación especificada con un nombre exacto. Requiere el calificador =. Por ejemplo, location=us-central1 coincide con los recursos alojados en Iowa.

Los recursos de BigQuery Omni admiten este calificador con el nombre de la ubicación de BigQuery Omni. Por ejemplo, location=aws-us-east-1 coincide con los recursos de BigQuery Omni en Virginia del Norte.

createtime

Busca recursos que se crearon dentro, antes o después de una fecha, marca de tiempo o tiempo relativo en días determinados. Para conocer los formatos y operadores compatibles, consulta Filtros de tiempo.
updatetime

Busca recursos que se actualizaron dentro, antes o después de una fecha, marca de tiempo o tiempo relativo en días determinados. Para conocer los formatos y operadores compatibles, consulta Filtros de tiempo.

Calificadores de concordancia exacta

Las claves de predicado type, system, location y la búsqueda por aspectos (excepto has) solo admiten el calificador de coincidencia exacta (=), no el calificador de subcadena (:).

Usa la siguiente sintaxis de concordancia exacta para estos predicados:

Clave de predicado Sintaxis correcta Sintaxis incorrecta
type type=table (o type=view, type=dataset) type:table o type:tab
system system=bigquery (o system=spanner) system:bigquery o system:big
location location=us-central1 (o location=europe-west1) location:us-central1 o location:us

Calificadores de substring

Los predicados, como name, displayname, column, projectid y parent, admiten la coincidencia de subcadenas con el calificador de dos puntos (:):

  • name:transactions coincide con los recursos cuyo ID o nombre visible contiene transactions. Por ejemplo, daily_transactions_raw y transactions_v2.
  • column:customer_id coincide con los recursos que tienen un nombre de columna que contiene customer_id.
  • projectid:prod coincide con los recursos de los proyectos cuyo ID contiene prod. Por ejemplo, finance-prod-2026.

Filtros de tiempo

Puedes filtrar los recursos por hora de creación (createtime) o por hora de última actualización (updatetime).

Operadores y formatos admitidos

  • Operadores admitidos: :, =, <, >, <=, >=, =>, =<
  • Días relativos (-Nd): Filtra por una cantidad relativa de días en el pasado (por ejemplo, -30d, -7d, -1d).
  • Fechas del calendario (YYYY-MM-DD o YYYY/MM/DD): Filtra por una fecha específica en GMT/UTC.
  • Marcas de tiempo completas (YYYY-MM-DDTHH:MM:SS o YYYY-MM-DDTHH:MM:SSZ): Filtra por una marca de tiempo precisa en GMT/UTC. También se admiten marcas de tiempo parciales, como YYYY-MM-DDTHH:MM o YYYY-MM-DDTHH.

Sintaxis del filtro de tiempo

En la siguiente tabla, se explica la sintaxis del filtro de tiempo:

Categoría de formato Sintaxis válida Sintaxis no válida Descripción
Unidades de tiempo relativas
  • createtime>-30d (últimos 30 días)
  • createtime<=-7d (hace 7 días o más)
  • updatetime=-1d (día anterior)
  • updatetime>=-90d
  • createtime>-24h
  • createtime>-60m
  • createtime>-2w
  • createtime>30d
  • Solo se admiten unidades de días negativas (-Nd) para el tiempo relativo.
  • No se admiten unidades más cortas (horas h, minutos m) ni más largas (semanas w, meses m).
  • Los desplazamientos positivos sin un signo menos inicial (-) no son válidos.
Fechas del calendario
  • 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
  • Las fechas deben tener el formato YYYY-MM-DD o YYYY/MM/DD.
  • Los formatos con un orden de componentes no estándar (como DD-MM-YYYY o MM/DD/YYYY) o nombres de meses no son válidos.
Marcas de tiempo y zonas horarias
  • 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
  • Todas las marcas de tiempo se evalúan en GMT/UTC.
  • No se admiten las compensaciones de zona horaria que no sean GMT (como -08:00 o +05:30) ni las abreviaturas de zona horaria (como EST o PST).
Intervalos de hora del día
  • createtime>=2025-01-15T09:00:00 createtime<=2025-01-15T17:00:00
  • createtime:09:00:00..17:00:00
  • createtime:09:00-17:00
  • No se admite la sintaxis de rango de hora del día.
  • En su lugar, usa comparaciones de límites inferior y superior independientes con cadenas de fecha y hora completas.
Fechas en lenguaje natural
  • createtime=-1d
  • createtime>-30d
  • createtime:yesterday
  • createtime:"last week"
  • createtime:today
  • No se admiten las frases de fecha en lenguaje natural dentro de los calificadores createtime o updatetime.
  • Usa la sintaxis de día relativo (-1d, -7d) o fechas explícitas.

Filtros de etiquetas

Usa el predicado labels para filtrar los recursos por etiquetas adjuntas. Puedes filtrar por clave de etiqueta, valor de etiqueta o ambos:

Patrón de consulta Ejemplo Descripción
labels=KEY labels=environment Coincide con los recursos que tienen una etiqueta con la clave exacta environment, independientemente de su valor.
labels:KEY_SUBSTRING labels:tier Coincide con los recursos que tienen una clave de etiqueta que contiene tier como una subcadena (como service_tier o storage_tier).
labels.KEY=VALUE labels.env=prod Coincide con los recursos en los que la clave de etiqueta es env y su valor es exactamente prod.
labels.KEY:VALUE_SUBSTRING labels.owner:analytics Coincide con los recursos que tienen la clave de etiqueta owner, en la que el valor contiene analytics como una subcadena (como analytics-team o data-analytics).
Varias etiquetas (AND) labels.env=prod labels.data_tier=tier1 Coincide con los recursos que tienen adjuntas las etiquetas env=prod y data_tier=tier1.
Combinado con el sistema y el tipo system=bigquery type=table labels.env=prod labels.confidentiality=high Coincide con las tablas de BigQuery etiquetadas con env=prod y confidentiality=high.

Puedes usar la sintaxis de consulta para buscar entradas según sus aspectos adjuntos.

La coincidencia de subcadena intenta coincidir con una cantidad limitada de aspectos. Si no puedes encontrar la entrada con un fragmento de la ruta de acceso, usa la ruta de acceso completa para acotar la búsqueda y aumentar la recuperación.

Calificador Descripción
aspect:x
o
has:x		 Coincide con x como una subcadena de la ruta de acceso completa al tipo de aspecto de un aspecto que se adjunta a la entrada, en el formato projectid.location.ASPECT_TYPE_ID
aspect=x
o
has=x		 Coincide con x como la ruta de acceso completa al tipo de aspecto de un aspecto que se adjunta a la entrada, en el formato projectid.location.ASPECT_TYPE_ID
x
OPERATOR
value

Busca valores de campos de aspecto. Coincide con x como una subcadena de la ruta de acceso completa al tipo de aspecto y el nombre del campo de un aspecto que se adjunta a la entrada, en los siguientes formatos:

  • Sintaxis para los tipos de aspectos del sistema:

    • ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.ASPECT_TYPE_ID.FIELD_NAME
    • dataplex-types.LOCATION.ASPECT_TYPE_ID.FIELD_NAME

    Por ejemplo, las siguientes consultas coinciden con las entradas en las que el valor del campo type en el aspecto bigquery-dataset es default:

    • bigquery-dataset.type=default
    • dataplex-types.bigquery-dataset.type=default
    • dataplex-types.global.bigquery-dataset.type=default

  • Sintaxis para los tipos de aspectos personalizados:

    • Si el aspecto se crea en la región global: PROJECT_ID.ASPECT_TYPE_ID.FIELD_NAME
    • Si el aspecto se crea en una región específica: PROJECT_ID.REGION.ASPECT_TYPE_ID.FIELD_NAME

    Por ejemplo, las siguientes consultas coinciden con las entradas en las que el valor del campo is-enrolled en el aspecto employee-info es true.

    • example-project.us-central1.employee-info.is-enrolled=true
    • example-project.employee-info.is-enrolled=true

    La lista de operadores admitidos depende del tipo de campo en el aspecto, como se indica a continuación:

    • Cadena: = (coincidencia exacta)
    • Todos los tipos de números: =, :, <, >, <=, >=, =>, =<
    • Enum: =
    • Fecha y hora: Es igual que para los números, pero los valores que se compararán se tratan como fechas y horas en lugar de números.
    • Booleano: =

Solo se pueden buscar los campos de nivel superior del aspecto.

Operadores lógicos

Una consulta puede combinar varios predicados con operadores lógicos. Nota: Los operadores lógicos AND, OR y NOT distinguen mayúsculas de minúsculas y deben estar en letras mayúsculas.

Operador AND

Si separas varios términos de búsqueda o predicados con un espacio, se implica el operador lógico AND, lo que significa que no tienes que escribirlo de forma explícita.

En los siguientes ejemplos, se muestra cómo construir consultas con el operador AND.

  • Busca tablas de BigQuery

    system=bigquery type=table

  • Busca recursos en el proyecto banking-prod con una columna llamada customer_id

    projectid:banking-prod column:customer_id

  • Si es necesario, puedes usar el operador AND explícito:

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

Operador OR

Usa el operador OR para que coincida con cualquiera de las múltiples condiciones. Cuando combines OR con otros criterios, usa paréntesis ( ) para agrupar las expresiones y definir la prioridad.

En los siguientes ejemplos, se muestra cómo construir consultas con el operador OR.

  • Busca tablas y vistas de BigQuery

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

  • Busca tablas en varios sistemas

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

  • Busca entradas en los conjuntos de datos de marketing o finanzas.

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

Operador NOT

Puedes negar un predicado si le agregas el prefijo NOT en mayúscula o un - (guion).

En los siguientes ejemplos, se muestra cómo construir consultas con el operador NOT.

  • Busca todas las tablas, excepto las que se encuentran en un proyecto de zona de pruebas

    • Usa el operador NOT
    type=table NOT projectid:sandbox-project
    • Usar guion
    type=table -projectid:sandbox-project

  • Busca todos los recursos de BigQuery que no contengan test en su nombre

    system=bigquery -name:test

Sintaxis abreviada

Si quieres usar la sintaxis abreviada, usa | (barra vertical) para los operadores OR y , (coma) para los operadores AND entre paréntesis. Esta sintaxis abreviada funciona para los predicados calificados.

  • Busca en varios IDs de proyecto

    • Usa el operador OR:
    projectid:(finance-prod|sales-prod|analytics-prod)
    • Usa paréntesis:
    projectid:finance-prod OR projectid:sales-prod OR projectid:analytics-prod

  • Busca entradas que coincidan con varios nombres de columnas (AND)

    column:(customer_id,transaction_date,amount)

  • Busca entradas que coincidan con cualquiera de los nombres de varias columnas (OR)

    column:(customer_id|user_id|client_id)

Política de comodín

La sintaxis de búsqueda de Knowledge Catalog no admite comodines, como * o ?, en cadenas de consulta ni predicados.

Si incluyes un asterisco (*) o un signo de interrogación (?) en una consulta, se trata como un carácter literal, en lugar de un comodín de coincidencia de patrones.

Por ejemplo, para buscar tablas cuyos nombres terminen con _masked, haz lo siguiente:

  • Admitido: name:_masked : Usa el calificador de coincidencia de subcadena : para encontrar todos los recursos cuyo nombre contenga _masked, como customer_records_masked o transactions_masked.
  • No compatible: name:*_masked: El * se trata como un carácter literal, no como un comodín de patrón.

Paréntesis

Los paréntesis en las búsquedas tienen funciones técnicas específicas. Si usas paréntesis en exceso o los aplicas a consultas de lenguaje natural, puedes confundir al analizador de búsqueda y disminuir la calidad de los resultados.

Lenguaje natural sencillo

Cuando hagas una pregunta empresarial, pasa la consulta en texto sin formato. No lo encierres entre paréntesis. Por ejemplo, escribe lo siguiente:

Find customer orders containing email addresses

Sintaxis de predicado abreviada

Los paréntesis son muy eficaces cuando se usan con claves de predicado para enumerar varias condiciones OR y AND en un formato compacto.

  • Agrupa las claves de predicado con OR (|)

    • Busca entradas que residan en cualquiera de los proyectos de la lista con (|)

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

    • Busca entradas que residan en cualquiera de los proyectos de la lista con (OR)

    projectid:finance-prod OR projectid:finance-test OR projectid:finance-raw

  • Agrupa las claves de predicado con AND (,)

    • Busca entradas que contengan todas las columnas especificadas con (,).
    column:(customer_id, order_date, total_amount)
    • Busca entradas que contengan todas las columnas especificadas con (AND).
    column:customer_id AND column:order_date AND column:total_amount

Puedes combinar una consulta en lenguaje natural con filtros compactos.

Por ejemplo, para encontrar tablas que especifiquen usuarios activos por mes, pero restringir la búsqueda a los proyectos especificados, usa la siguiente consulta:

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

Prácticas recomendadas para usar paréntesis

  • No encierres toda la pregunta entre paréntesis, ya que el motor semántico podría tratar los paréntesis como caracteres literales, lo que generaría resultados de baja relevancia.

    • Incorrecto: (Show me datasets about US population by state)
    • Correcto: Show me datasets about US population by state

  • Evita mezclar árboles booleanos complejos y anidados con paréntesis dentro del campo de lenguaje natural. La Búsqueda está optimizada para la intención del lenguaje natural. Complicar demasiado la consulta con paréntesis y bloques lógicos explícitos confunde al analizador.

    • Incorrecto: (revenue data) AND system=BIGQUERY AND projectid:(data-warehouse | analytical-tier)
    • Correcto: revenue data system=bigquery projectid:(data-warehouse|analytical-tier)

  • No agregues espacios de forma arbitraria, a menos que formen parte del valor.

    • Incorrecto: column:( email | id )
    • Correcto: column:(email|id).

¿Qué sigue?