Corrispondenza dei pattern

Nelle applicazioni di ricerca agentica, la ricerca vettoriale e la corrispondenza dei pattern in stile grep spesso si integrano a vicenda. La ricerca vettoriale recupera le entità semanticamente rilevanti, mentre la corrispondenza dei pattern restringe tali risultati in base a strutture di stringhe esatte, quali codici di errore, prefissi di log, domini e-mail, percorsi URL o identificatori.

In Milvus, è possibile esprimere questi vincoli di pattern nei filtri scalari utilizzando LIKE per la semplice corrispondenza con caratteri jolly e =~ o !~ per le espressioni regolari RE2. È possibile combinare questi filtri con query, search o la ricerca ibrida.

Le espressioni di corrispondenza dei pattern vengono scritte nel parametro filter. Ad esempio, la seguente query individua i messaggi di log che contengono un codice di errore come E1001:

from pymilvus import MilvusClient

client = MilvusClient(uri="http://localhost:19530")

res = client.query(
    collection_name="log_events",
    filter='message =~ "E[0-9]{4}"',
    output_fields=["message", "severity"],
)

Gli esempi in questa pagina si concentrano sull’espressione assegnata a ` filter`. È possibile utilizzare la stessa sintassi dell’espressione di filtro nelle operazioni di Milvus che accettano un filtro scalare, come ` query`, ` search` e la ricerca ibrida.

Tipi di campo supportati

La corrispondenza dei pattern è disponibile per i valori stringa.

Destinazione	LIKE	Regex =~ / !~	Note
VARCHAR campo	Sì	Sì	Destinazione tipica per la corrispondenza di pattern nei campi stringa.
JSON percorso con tipo di conversione " VARCHAR "	Sì	Sì	Il valore del percorso JSON deve essere una stringa per ottenere corrispondenze positive. Se si crea un indice sul percorso JSON per l'accelerazione, impostare json_cast_type="varchar".
ARRAY<VARCHAR> elemento	Sì	Sì	Corrisponde a un elemento specifico in base all'indice, ad esempio tags[0]. La corrispondenza del pattern non esegue la scansione di tutti gli elementi; si applica solo all'elemento all'indice specificato.
Destinazioni numeriche, booleane, vettoriali, TEXT o altre destinazioni nonVARCHAR	No	No	La corrispondenza con il pattern è disponibile solo per i valori di tipo " VARCHAR ", i percorsi JSON che si risolvono in stringhe o gli elementi " ARRAY<VARCHAR> " indicizzati.

Scegliere LIKE o regex

Scegli l’operatore più semplice che esprima il modello di cui hai bisogno.

Se hai bisogno di una corrispondenza esatta della stringa, ti consigliamo di utilizzare == invece del pattern matching. Usa LIKE o regex solo quando il filtro deve corrispondere a un pattern.

Requisiti	Operatore consigliato	Esempio	Descrizione
Uguaglianza esatta della stringa	==	status == "active"	Corrispondenza esatta della stringa active.
Corrispondenza semplice del prefisso	LIKE	name LIKE "Prod%"	Corrisponde alle stringhe che iniziano con Prod.
Corrispondenza semplice del suffisso	LIKE	filename LIKE "%.json"	Corrisponde alle stringhe che terminano con .json.
Corrispondenza semplice "contiene"	LIKE	description LIKE "%vector database%"	Trova i valori che contengono vector database in qualsiasi punto della stringa.
Corrispondenza di un codice strutturato o di un modello a lunghezza fissa	=~	code =~ "E[0-9]{4}"	Trova stringhe che, distinguendo tra maiuscole e minuscole, contengono E seguito da quattro cifre, ad esempio E1001.
Corrispondenza di pattern senza distinzione tra maiuscole e minuscole	=~ con (?i)	message =~ "(?i)error"	Trova error, ERROR o altre varianti con maiuscole e minuscole.
Escludi i valori che corrispondono a un modello regex	!~	message !~ "^DEBUG"	Esclude le stringhe che iniziano con DEBUG.

Utilizza LIKE per una semplice corrispondenza con caratteri jolly. Utilizza regex quando il modello richiede classi di caratteri, ripetizioni, alternanze come error|failed, ancore o corrispondenze senza distinzione tra maiuscole e minuscole.

Utilizzare LIKE

L'operatore LIKE serve per semplici corrispondenze con caratteri jolly su valori di stringa. Supporta solo i seguenti caratteri jolly:

Carattere jolly	Descrizione
%	Corrisponde a zero o più caratteri.
_	Corrisponde esattamente a un carattere.

Modelli LIKE comuni

Utilizza la posizione di % e _ per controllare dove appare il testo fisso nella stringa corrispondente.

Requisiti	Modello	Esempio di filtro
Inizia con un prefisso	Prod%	filter = 'name LIKE "Prod%"'
Termina con un suffisso	%.json	filter = 'filename LIKE "%.json"'
Contiene una sottostringa	%vector%	filter = 'description LIKE "%vector%"'
Corrisponde a un carattere in una posizione fissa	AB_%	filter = 'code LIKE "AB_%"'

Comportamento di corrispondenza LIKE

Utilizzare LIKE per le corrispondenze di prefisso, suffisso, contenuto e singolo carattere in posizione fissa. LIKE non supporta classi di caratteri come [0-9], alternanze come error|failed, conteggi di ripetizioni come {4}, ancore come ^ o $, né flag di ignoranza maiuscole/minuscole come (?i). Per tali pattern, utilizzare le espressioni regolari.

Utilizza == per l'uguaglianza esatta dell'intera stringa. Utilizza LIKE solo quando il filtro richiede la corrispondenza con caratteri jolly.

Escape dei caratteri jolly in un modello LIKE

Nei modelli LIKE, % corrisponde a zero o più caratteri e _ corrisponde esattamente a un carattere. Per trovare una corrispondenza letterale con %, _ o \, si deve eseguire l'escape del carattere con una barra rovesciata (\):

• name LIKE r"\%" corrisponde al valore letterale %.
• name LIKE r"\_%" corrisponde ai valori che iniziano con il carattere letterale _.
• name LIKE r"\\%" corrisponde ai valori che iniziano con una barra rovesciata letterale.

I letterali di stringa grezzi, scritti come r"..." o r'...', mantengono le barre rovesciate tali e quali nelle espressioni dei filtri di Milvus. Sono consigliati per LIKE e per i pattern regex che contengono barre rovesciate. Senza una stringa grezza, i normali letterali di stringa elaborano comunque le sequenze di escape prima che il pattern venga valutato, quindi potrebbero essere necessarie più barre rovesciate.

Utilizzare le espressioni regolariCompatible with Milvus 3.0.x

Utilizzate i filtri regex quando il pattern richiede funzionalità delle espressioni regolari quali classi di caratteri, ripetizioni, alternanze, ancore o corrispondenze che non distinguono tra maiuscole e minuscole. Milvus applica un'espressione regolare RE2 a un valore stringa.

Il lato destro di =~ o !~ deve essere un letterale stringa.

Operatore	Significato	Esempio
=~	Corrisponde ai valori che soddisfano il modello regex.	filter = 'message =~ "E[0-9]{4}"'
!~	Esclude i valori che soddisfano il modello regex.	filter = 'message !~ "^DEBUG"'

Utilizzare stringhe letterali "raw"

I letterali stringa grezzi sono consigliati per i modelli regex che contengono barre rovesciate. In una stringa grezza, scritta come r"..." o r'...', le barre rovesciate vengono passate al motore regex alla lettera. Ciò evita l'escape aggiuntivo richiesto dai normali letterali stringa.

Ad esempio:

filter = 'message =~ r"\d{4}-\d{2}-\d{2}"'

Questo corrisponde a stringhe che contengono un valore simile a una data, come 2026-07-01.

Senza una stringa raw, le stringhe letterali ordinarie elaborano le sequenze di escape prima che il pattern regex venga valutato, quindi pattern come \d, \s o caratteri letterali con escape potrebbero richiedere barre rovesciate aggiuntive.

Modelli di espressioni regolari comuni

Gli esempi seguenti utilizzano la sintassi RE2 comune nelle espressioni dei filtri di Milvus. Per la sintassi completa delle espressioni regolari, consultare il riferimento alla sintassi RE2.

Requisito	Modello	Esempio di filtro
Contiene testo letterale	error	filter = 'message =~ "error"'
Inizia con un prefisso	^ERR	filter = 'code =~ "^ERR"'
Termina con un suffisso	\.json$	filter = 'filename =~ "\\.json$"'
Corrisponde a una sequenza di cifre	[0-9]+	filter = 'message =~ "[0-9]+"'
Corrisponde a un numero fisso di cifre	[0-9]{4}	filter = 'code =~ "[0-9]{4}"'
Corrisponde a un dominio e-mail	@example\.com$	filter = 'email =~ "@example\\.com$"'
Corrisponde senza distinzione tra maiuscole e minuscole	(?i)error	filter = 'message =~ "(?i)error"'
Corrisponde alla stringa completa	^prod-[0-9]+$	filter = 'name =~ "^prod-[0-9]+$"'

Per trovare una delle diverse parole, usa l'alternanza con |:

filter = 'message =~ "error|failed|timeout"'

Quando si effettuano corrispondenze letterali con i metacaratteri delle espressioni regolari, è necessario eseguire l'escape all'interno del pattern. Ad esempio, per trovare un punto letterale (\. nell'espressione regolare), scrivere \\. in una stringa di filtro Python:

filter = 'email =~ "@gmail\\.com$"'

Nota: i filtri regex di Milvus seguono la sintassi RE2. Se un modello regex utilizza una sintassi non supportata da RE2 o è altrimenti non valido, Milvus rifiuta l’espressione del filtro. Per i dettagli sui metacaratteri regex, i flag e il comportamento di corrispondenza, consultare il riferimento alla sintassi RE2.

Comportamento di corrispondenza

Corrispondenza di sottostringhe

La corrispondenza delle espressioni regolari di Milvus utilizza la semantica delle sottostringhe. Il modello non deve necessariamente corrispondere all’intero valore del campo. Ad esempio, il seguente filtro corrisponde sia a E1001 che a failed with E1001 after retry:

filter = 'message =~ "E[0-9]{4}"'

Per trovare corrispondenze con l’intero valore del campo, utilizzare gli ancoraggi ^ e $:

# Match only values that are exactly E followed by four digits
filter = 'code =~ "^E[0-9]{4}$"'

Campi VARCHAR nullabili

I filtri Regex non individuano i valori nulli. Ciò vale sia per =~ che per !~. Se si desidera escludere un pattern Regex ma mantenere i valori nulli, aggiungere esplicitamente OR field IS NULL:

filter = 'message !~ "^DEBUG" OR message IS NULL'

Percorsi JSON

Per i percorsi JSON, i filtri regex si comportano in modo diverso quando il percorso è mancante, nullo o si risolve in un valore non stringa:

Filtro	Include valori mancanti/null/non stringa?	Note
json_field["path"] =~ "pattern"	No	Corrisponde solo ai valori stringa che soddisfano il modello regex.
json_field["path"] !~ "pattern"	Sì	Restituisce le entità in cui il percorso è mancante, nullo, non di tipo stringa o una stringa che non corrisponde al modello regex.

Accelerare la corrispondenza dei pattern con gli indici

Milvus supporta diversi tipi di indici sui campi stringa che possono essere utilizzati insieme a filtri " LIKE " e filtri regex su campi " VARCHAR " o percorsi stringa JSON, come NGRAM, STL_SORT, INVERTED e BITMAP. La corrispondenza dei pattern può funzionare senza un indice, ma un indice può migliorare le prestazioni su set di dati di grandi dimensioni.

L'efficacia dell'indice dipende dall'espressione del pattern, dalla capacità di Milvus di estrarre sottostringhe letterali fisse, nonché dalla cardinalità e dalla distribuzione del campo di destinazione. I pattern di tipo prefisso, come name LIKE "Prod%", possono trarre vantaggio da strategie di indicizzazione diverse rispetto ai pattern di tipo infisso o suffisso, come description LIKE "%vector%" o filename LIKE "%.json".

Utilizzate la tabella seguente come punto di partenza, quindi effettuate un benchmark con il vostro carico di lavoro:

Modello o caratteristica dei dati	Indice da prendere in considerazione	Note
Contiene sottostringhe letterali fisse, come message =~ "error.*timeout" o message LIKE "%database%"	NGRAM	Utile quando Milvus è in grado di estrarre sottostringhe letterali significative dal modello. Per ulteriori dettagli, consultare NGRAM.
Filtri di stringa prefissati, esatti o simili all’uguaglianza, specialmente su campi con cardinalità da bassa a moderata	STL_SORT, INVERTED o BITMAP	Possono risultare più efficaci quando il campo presenta valori ripetuti o quando il filtro si avvicina alla corrispondenza esatta. Per i dettagli, fare riferimento a STL_SORT, INVERTED e BITMAP.
Modelli Regex senza letterali fissi, o modelli dominati da classi di caratteri, token brevi o caratteri jolly	Eseguire un benchmark prima di fare affidamento sull’accelerazione tramite indice	Questi modelli potrebbero fornire una selettività dell’indice limitata e ricorrere a scansioni più ampie.