Operadores de StructArray

Los operadores de StructArray filtran entidades evaluando predicados en subcampos escalares dentro de un campo StructArray. Utiliza esta página como referencia sintáctica para « element_filter » y la familia de operadores « MATCH_* ».

El filtrado de StructArray cuenta con dos familias de operadores:

Familia de operadores	Finalidad principal	Comportamiento del resultado
element_filter	Coincide con los elementos de Struct que satisfacen un predicado escalar.	En la búsqueda a nivel de elemento, los resultados coincidentes pueden incluir desplazamientos de elementos. En la consulta a nivel de fila o en la búsqueda filtrada, la forma del resultado depende de la API y de los campos de salida.
MATCH_*	Selecciona entidades en función del número de elementos de Struct que satisfacen un predicado escalar.	Filtrado a nivel de fila. Estos operadores no devuelven por sí mismos las posiciones de los elementos.

Utiliza subcampos escalares en los operadores StructArray. Los subcampos vectoriales se utilizan en las rutas de búsqueda vectorial y no son entradas de predicados escalares.

Cuándo utilizar cada operador

Objetivo	Uso
Limitar la búsqueda vectorial a nivel de elemento a aquellos elementos que cumplan condiciones escalares.	element_filter
Cumplir varias condiciones escalares dentro del mismo elemento Struct.	element_filter
Devolver únicamente las entidades en las que al menos un elemento Struct cumpla un predicado.	MATCH_ANY
Devolver únicamente las entidades en las que todos los elementos Struct cumplan un predicado.	MATCH_ALL
Devuelve únicamente las entidades en las que al menos, como máximo o exactamente N elementos Struct cumplan un predicado.	MATCH_LEAST, MATCH_MOST o MATCH_EXACT

Filtro de elementos

Utilice « element_filter(structArrayField, predicate) » para buscar coincidencias con elementos de Struct en un campo StructArray.

Dentro del predicado, utilice « $[subfield] » para hacer referencia a un subcampo escalar del elemento Struct actual.

element_filter(chunks, $[section] == "index")

Cuando se utilizan varias condiciones dentro del predicado, todas las referencias a ` $[subfield] ` se aplican al mismo elemento de la estructura:

element_filter(chunks, $[section] == "index" && $[quality_score] > 0.9)

Cuando se combine un predicado a nivel de entidad con ` element_filter`, coloque ` element_filter ` al final de la expresión:

# Correct
category == "index" && element_filter(chunks, $[quality_score] > 0.9)

# Incorrect
element_filter(chunks, $[quality_score] > 0.9) && category == "index"

element_filter solo puede aparecer una vez en una expresión de filtro. No anides element_filter ni MATCH_* dentro de otro element_filter.

Operadores de coincidencia de familias

Utiliza los operadores « MATCH_* » cuando se deba seleccionar una entidad en función del número de elementos «Struct» que satisfagan un predicado.

Operador	Significado
MATCH_ANY(field, predicate)	Al menos un elemento Struct cumple el predicado.
MATCH_ALL(field, predicate)	Todos los elementos Struct satisfacen el predicado.
MATCH_LEAST(field, predicate, threshold=N)	Al menos N elementos Struct cumplen el predicado.
MATCH_MOST(field, predicate, threshold=N)	Como máximo, un N es elementos de la estructura cumplen el predicado.
MATCH_EXACT(field, predicate, threshold=N)	Exactamente N elementos de Struct satisfacen el predicado.

MATCH_ANY Tanto « element_filter » como « » pueden expresar que al menos un elemento de Struct cumple un predicado. Utiliza « MATCH_ANY » cuando solo necesites filtrado a nivel de fila. Utiliza « element_filter » cuando necesites restricciones a nivel de elemento, como filtrar qué elementos de Struct participan en una búsqueda vectorial a nivel de elemento.

MATCH_ANY

MATCH_ANY se evalúa como « true » si al menos un elemento de StructArray cumple el predicado.

MATCH_ANY(chunks, $[section] == "index")

Para un StructArray vacío, ` MATCH_ANY ` devuelve ` false`.

MATCH_ALL

MATCH_ALL devuelve « true » si todos los elementos de StructArray satisfacen el predicado.

MATCH_ALL(chunks, $[has_code] == true)

Para un StructArray vacío, ` MATCH_ALL ` devuelve ` true`.

MATCH_LEAST

MATCH_LEAST devuelve true si el número de elementos que satisfacen el predicado es mayor o igual que threshold.

MATCH_LEAST(chunks, $[quality_score] > 0.9, threshold=2)

Para MATCH_LEAST, threshold debe ser un entero positivo.

MATCH_MOST

MATCH_MOST devuelve el valor « true » si el número de elementos que satisfacen el predicado es menor o igual que « threshold ».

MATCH_MOST(chunks, $[has_code] == true, threshold=1)

Para MATCH_MOST, threshold puede ser cero o un entero positivo.

MATCH_EXACT

MATCH_EXACT devuelve el valor « true » si el número de elementos que satisfacen el predicado es exactamente igual a « threshold ».

MATCH_EXACT(chunks, $[section] == "filter", threshold=1)

Para MATCH_EXACT, threshold puede ser cero o un entero positivo.

Predicados admitidos

La sintaxis « $[...] » representa el valor escalar del elemento Struct actual. La compatibilidad con los predicados depende del tipo de subcampo escalar.

Tipo de subcampo	Compatibilidad con predicados a nivel de elemento
BOOL	Predicados escalares como $[has_code] == true o !($[has_code] == true). Evita expresiones booleanas sin calificaciones, como $[has_code].
INT8, INT16, INT32, INT64	comparaciones, rangos encadenados, in, not in, expresiones aritméticas con +, -, *, / o % seguidas de una comparación, y combinaciones lógicas.
FLOAT, DOUBLE	Comparación, rango encadenado, in, not in, expresiones aritméticas con +, -, * o / seguidas de una comparación, y combinaciones lógicas. El operador % no es compatible con subcampos de punto flotante.
VARCHAR	Comparación de cadenas, rango encadenado, in, not in, like, =~, !~ y combinaciones lógicas.
Subcampos vectoriales	No son compatibles como entradas de predicados escalares de $[...]. En su lugar, utiliza subcampos vectoriales mediante la búsqueda con EmbeddingList o la búsqueda vectorial a nivel de elemento.

Los operadores lógicos como « && », « \|\| » y « ! » se aplican a las expresiones de predicado. Por ejemplo, escriba « !($[has_code] == true) » en lugar de « !$[has_code] ».

Predicados no admitidos

Los predicados de nivel de elemento de $[...] no admiten:

• Funciones de coincidencia de texto, como text_match(field, "...") o phrase_match(field, "...").

• La sintaxis de rutas JSON, exists sobre rutas JSON, o funciones JSON como json_contains, json_contains_all o json_contains_any.

• Funciones de contenedores de matrices como array_contains, array_contains_all, array_contains_any o array_length.

• $[subfield] is null o $[subfield] is not null.

• Funciones de geometría/SIG.

• Expresiones de Timestamptz.

• random_sample(...).

• Predicados vectoriales a nivel de campo.

• Llamadas a funciones de filtro genéricas, a menos que la firma específica de la función y la ruta de ejecución admitan explícitamente predicados a nivel de elemento de StructArray.

Reglas sintácticas

• MATCH_* Los nombres de los operadores no distinguen entre mayúsculas y minúsculas.

• Utilice « $[subfield] » únicamente dentro de los predicados « element_filter » o « MATCH_* ».

• No utilices « $[subfield] » como ruta JSON, contenedor de matriz o referencia a un campo vectorial.

• No anides « element_filter » o « MATCH_* » dentro de otro operador «StructArray».

• Utilice threshold=N con nombre para MATCH_LEAST, MATCH_MOST y MATCH_EXACT.

• MATCH_ANY En un StructArray vacío devuelve false.

• MATCH_ALL sobre un StructArray vacío devuelve true.

Véase también

• Búsqueda filtrada con StructArray

• Búsqueda vectorial básica con StructArray

• Indexar campos de StructArray

• Límites de StructArray