Operatori StructArray

Gli operatori StructArray filtrano le entità valutando i predicati sui sottocampi scalari all'interno di un campo StructArray. Utilizzare questa pagina come riferimento sintattico per l'operatore " element_filter " e la famiglia di operatori " MATCH_* ".

Il filtraggio StructArray prevede due famiglie di operatori:

Famiglia di operatori	Scopo principale	Comportamento del risultato
element_filter	Corrispondenza Elementi Struct che soddisfano un predicato scalare.	Nella ricerca a livello di elemento, i risultati corrispondenti possono includere gli offset degli elementi. Nelle query a livello di riga o nella ricerca filtrata, la struttura dei risultati dipende dall’API e dai campi di output.
MATCH_*	Seleziona le entità in base al numero di elementi Struct che soddisfano un predicato scalare.	Filtraggio a livello di riga. Questi operatori non restituiscono di per sé gli offset degli elementi.

Utilizzare i sottocampi scalari negli operatori StructArray. I sottocampi vettoriali sono utilizzati dai percorsi di ricerca vettoriali e non costituiscono input per i predicati scalari.

Quando utilizzare quale operatore

Obiettivo	Uso
Limitare la ricerca vettoriale a livello di elemento agli elementi che soddisfano condizioni scalari.	element_filter
Soddisfare più condizioni scalari all'interno dello stesso elemento Struct.	element_filter
Restituire solo le entità in cui almeno un elemento Struct soddisfa un predicato.	MATCH_ANY
Restituire solo le entità in cui tutti gli elementi Struct soddisfano un predicato.	MATCH_ALL
Restituisce solo le entità in cui almeno, al massimo o esattamente N elementi Struct soddisfano un predicato.	MATCH_LEAST, MATCH_MOST o MATCH_EXACT

Filtro per elemento

Utilizzare ` element_filter(structArrayField, predicate) ` per trovare corrispondenze con gli elementi Struct in un campo StructArray.

All’interno del predicato, utilizzare $[subfield] per fare riferimento a un sottocampo scalare dell’elemento Struct corrente.

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

Quando all’interno del predicato vengono utilizzate più condizioni, tutti i riferimenti a ` $[subfield] ` si applicano allo stesso elemento Struct:

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

Quando si combina un predicato a livello di entità con ` element_filter`, posizionare ` element_filter ` alla fine dell'espressione:

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

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

element_filter può comparire una sola volta in un’espressione di filtro. Non annidare ` element_filter ` o ` MATCH_* ` all’interno di un altro ` element_filter`.

Operatori di corrispondenza per famiglie

Utilizzare gli operatori MATCH_* quando un'entità deve essere selezionata in base al numero di elementi Struct che soddisfano un predicato.

Operatore	Significato
MATCH_ANY(field, predicate)	Almeno un elemento Struct soddisfa il predicato.
MATCH_ALL(field, predicate)	Tutti gli elementi Struct soddisfano il predicato.
MATCH_LEAST(field, predicate, threshold=N)	Almeno N elementi Struct soddisfano il predicato.
MATCH_MOST(field, predicate, threshold=N)	Al massimo N elementi della struttura soddisfano il predicato.
MATCH_EXACT(field, predicate, threshold=N)	Esattament N i elementi Struct soddisfano il predicato.

MATCH_ANY sia " element_filter " che " " possono entrambi indicare che almeno un elemento Struct soddisfa un predicato. Utilizza " MATCH_ANY " quando è necessario solo un filtro a livello di riga. Utilizza " element_filter " quando sono necessari vincoli a livello di elemento, come il filtraggio degli elementi Struct che partecipano alla ricerca vettoriale a livello di elemento.

MATCH_ANY

MATCH_ANY restituisce " true " se almeno un elemento dello StructArray soddisfa il predicato.

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

Per uno StructArray vuoto, MATCH_ANY restituisce false.

MATCH_ALL

MATCH_ALL restituisce true se ogni elemento di StructArray soddisfa il predicato.

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

Per uno StructArray vuoto, MATCH_ALL restituisce true.

MATCH_LEAST

MATCH_LEAST restituisce true se il numero di elementi che soddisfano il predicato è maggiore o uguale a threshold.

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

Per MATCH_LEAST, threshold deve essere un numero intero positivo.

MATCH_MOST

MATCH_MOST restituisce il valore true se il numero di elementi che soddisfano il predicato è minore o uguale a threshold.

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

Per MATCH_MOST, threshold può essere zero o un numero intero positivo.

MATCH_EXACT

MATCH_EXACT restituisce il valore true se il numero di elementi che soddisfano il predicato è esattamente uguale a threshold.

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

Per MATCH_EXACT, threshold può essere zero o un numero intero positivo.

Predicati supportati

La sintassi $[...] rappresenta il valore scalare dell’elemento Struct corrente. Il supporto dei predicati dipende dal tipo di sottocampo scalare.

Tipo di sottocampo	Supporto dei predicati a livello di elemento
BOOL	Predicati scalari quali $[has_code] == true o !($[has_code] == true). Evitare espressioni booleane nude quali $[has_code].
INT8, INT16, INT32, INT64	confronto, intervallo concatenato, in, not in, espressioni aritmetiche con +, -, *, / o % seguite da un confronto, e combinazioni logiche.
FLOAT, DOUBLE	Confronto, intervallo concatenato, in, not in, espressioni aritmetiche con +, -, * o / seguite da un confronto e combinazioni logiche. L’operatore % non è supportato per i sottocampi in virgola mobile.
VARCHAR	Confronto di stringhe, intervallo concatenato, in, not in, like, =~, !~ e combinazioni logiche.
Sottocampi vettoriali	Non supportati come input per i predicati scalari di tipo $[...]. Utilizzare invece i sottocampi vettoriali tramite la ricerca EmbeddingList o la ricerca vettoriale a livello di elemento.

Gli operatori logici quali &&, \|\| e ! si applicano alle espressioni dei predicati. Ad esempio, scrivere !($[has_code] == true) anziché !$[has_code].

Predicati non supportati

I predicati a livello di elemento $[...] non supportano:

• Funzioni di corrispondenza testuale, come text_match(field, "...") o phrase_match(field, "...").

• La sintassi dei percorsi JSON, exists sui percorsi JSON o funzioni JSON quali json_contains, json_contains_all o json_contains_any.

• Funzioni relative ai contenitori array come array_contains, array_contains_all, array_contains_any o array_length.

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

• Funzioni di geometria / GIS.

• Espressioni timestamptz.

• random_sample(...).

• Predicati vettoriali a livello di campo.

• Chiamate a funzioni di filtro generiche, a meno che la firma specifica della funzione e il percorso di esecuzione non supportino esplicitamente i predicati a livello di elemento StructArray.

Regole sintattiche

• MATCH_* I nomi degli operatori non distinguono tra maiuscole e minuscole.

• Utilizzare $[subfield] solo all’interno di predicati element_filter o MATCH_*.

• Non utilizzare $[subfield] come percorso JSON, contenitore di array o riferimento a un campo vettoriale.

• Non annidare element_filter o MATCH_* all’interno di un altro operatore StructArray.

• Utilizzare threshold=N con nome per MATCH_LEAST, MATCH_MOST e MATCH_EXACT.

• MATCH_ANY su uno StructArray vuoto restituisce false.

• MATCH_ALL su uno StructArray vuoto restituisce true.

Vedi anche

• Ricerca filtrata con StructArray

• Ricerca vettoriale di base con StructArray

• Indice dei campi di StructArray

• Limiti di StructArray