Sintassi di $filter OData in Azure AI Search
In Ricerca di intelligenza artificiale di Azure il parametro $filter specifica criteri di inclusione o esclusione per la restituzione delle corrispondenze nei risultati della ricerca. Questo articolo descrive la sintassi OData di $filter e fornisce esempi.
La costruzione e le costanti dei percorsi di campo sono descritte nella panoramica del linguaggio OData in Ricerca di intelligenza artificiale di Azure. Per altre informazioni sugli scenari di filtro, vedere Filtri in Ricerca di intelligenza artificiale di Azure.
Sintassi
Un filtro nel linguaggio OData è un'espressione booleana, che a sua volta può essere uno dei diversi tipi di espressione, come illustrato dal seguente modulo EBNF (Extended Backus-Naur):
boolean_expression ::=
collection_filter_expression
| logical_expression
| comparison_expression
| boolean_literal
| boolean_function_call
| '(' boolean_expression ')'
| variable
/* This can be a range variable in the case of a lambda, or a field path. */
variable ::= identifier | field_path
È disponibile anche un diagramma di sintassi interattivo:
Nota
Vedere Informazioni di riferimento sulla sintassi delle espressioni OData per Azure AI Search per l'EBNF completo.
I tipi di espressioni booleane includono:
- Espressioni di filtro della raccolta che usano
anyoall. Questi criteri applicano criteri di filtro ai campi della raccolta. Per altre informazioni, vedere Operatori di raccolta OData in Ricerca di intelligenza artificiale di Azure. - Espressioni logiche che combinano altre espressioni booleane usando gli operatori
and,orenot. Per altre informazioni, vedere Operatori logici OData in Ricerca di intelligenza artificiale di Azure. - Espressioni di confronto, che confrontano campi o variabili di intervallo con valori costanti usando gli operatori
eq,ltgenegte .lePer altre informazioni, vedere Operatori di confronto OData in Ricerca di intelligenza artificiale di Azure. Le espressioni di confronto vengono usate anche per confrontare le distanze tra coordinate geografiche spaziali usando lageo.distancefunzione . Per altre informazioni, vedere Funzioni geografiche OData in Ricerca di intelligenza artificiale di Azure. - Valori letterali booleani
trueefalse. Queste costanti possono essere utili a volte quando si generano filtri a livello di codice, ma in caso contrario non tendono a essere usate in pratica. - Chiamate a funzioni booleane, tra cui:
geo.intersects, che verifica se un determinato punto si trova all'interno di un determinato poligono. Per altre informazioni, vedere Funzioni geografiche OData in Ricerca di intelligenza artificiale di Azure.search.in, che confronta un campo o una variabile di intervallo con ogni valore in un elenco di valori. Per altre informazioni, vedere Funzione ODatasearch.inin Ricerca di intelligenza artificiale di Azure.search.ismatchesearch.ismatchscoring, che eseguono operazioni di ricerca full-text in un contesto di filtro. Per altre informazioni, vedere Funzioni di ricerca full-text OData in Ricerca di intelligenza artificiale di Azure.
- Percorsi di campo o variabili di intervallo di tipo
Edm.Boolean. Ad esempio, se l'indice ha un campo booleano denominatoIsEnablede si desidera restituire tutti i documenti in cui questo campo ètrue, l'espressione di filtro può essere solo il nomeIsEnabled. - Espressioni booleane tra parentesi. L'uso delle parentesi consente di determinare in modo esplicito l'ordine delle operazioni in un filtro. Per altre informazioni sulla precedenza predefinita degli operatori OData, vedere la sezione successiva.
Precedenza dell'operatore nei filtri
Se si scrive un'espressione di filtro senza parentesi intorno alle relative espressioni secondarie, Ricerca intelligenza artificiale di Azure la valuterà in base a un set di regole di precedenza dell'operatore. Queste regole si basano su quali operatori vengono usati per combinare le sottoespressione. Nella tabella seguente sono elencati i gruppi di operatori in ordine dalla precedenza più alta alla più bassa:
| Raggruppa | Operatore/i |
|---|---|
| Operatori logici | not |
| Operatori di confronto | eq, ne, gt, lt, gele |
| Operatori logici | and |
| Operatori logici | or |
Un operatore superiore nella tabella precedente verrà "associato più strettamente" ai relativi operandi rispetto ad altri operatori. Ad esempio, and è di precedenza maggiore rispetto ora e gli operatori di confronto hanno una precedenza maggiore rispetto a uno di essi, quindi le due espressioni seguenti sono equivalenti:
Rating gt 0 and Rating lt 3 or Rating gt 7 and Rating lt 10
((Rating gt 0) and (Rating lt 3)) or ((Rating gt 7) and (Rating lt 10))
L'operatore not ha la precedenza più alta di tutti, anche superiore agli operatori di confronto. Ecco perché se si prova a scrivere un filtro simile al seguente:
not Rating gt 5
Verrà visualizzato questo messaggio di errore:
Invalid expression: A unary operator with an incompatible type was detected. Found operand type 'Edm.Int32' for operator kind 'Not'.
Questo errore si verifica perché l'operatore è associato solo al Rating campo , che è di tipo Edm.Int32e non all'intera espressione di confronto. La correzione consiste nell'inserire l'operando tra not parentesi:
not (Rating gt 5)
Limitazioni relative alle dimensioni dei filtri
Esistono limiti alle dimensioni e alla complessità delle espressioni di filtro che è possibile inviare a Ricerca di intelligenza artificiale di Azure. I limiti si basano approssimativamente sul numero di clausole nell'espressione filtro. Una buona linea guida è che, se si dispone di centinaia di clausole, si rischia di superare il limite. È consigliabile progettare l'applicazione in modo che non generi filtri con dimensioni non vincolate.
Suggerimento
L'uso della search.in funzione invece di lunghe disgiunzioni di confronti di uguaglianza può aiutare a evitare il limite della clausola di filtro, poiché una chiamata di funzione conta come una singola clausola.
Esempi
Trova tutti gli alberghi con almeno una camera con una tariffa di base inferiore a $ 200 che sono valutati a o superiore a 4:
$filter=Rooms/any(room: room/BaseRate lt 200.0) and Rating ge 4
Trova tutti gli hotel diversi da "Sea View Motel" che sono stati rinnovati dal 2010:
$filter=HotelName ne 'Sea View Motel' and LastRenovationDate ge 2010-01-01T00:00:00Z
Trova tutti gli hotel ristrutturati nel 2010 o versioni successive. Il valore letterale datetime include informazioni sul fuso orario per l'ora solare del Pacifico:
$filter=LastRenovationDate ge 2010-01-01T00:00:00-08:00
Trova tutti gli hotel che hanno parcheggio incluso e dove tutte le camere sono non fumabili:
$filter=ParkingIncluded and Rooms/all(room: not room/SmokingAllowed)
OPPURE
$filter=ParkingIncluded eq true and Rooms/all(room: room/SmokingAllowed eq false)
Trovare tutti gli alberghi di lusso o con parcheggio incluso e di categoria 5 o superiore:
$filter=(Category eq 'Luxury' or ParkingIncluded eq true) and Rating eq 5
Trovare tutti gli alberghi con il tag "wifi" in almeno una camera (dove ogni camera ha tag archiviati in un Collection(Edm.String) campo):
$filter=Rooms/any(room: room/Tags/any(tag: tag eq 'wifi'))
Trova tutti gli hotel con qualsiasi camera:
$filter=Rooms/any()
Trova tutti gli hotel che non hanno camere:
$filter=not Rooms/any()
Trovare tutti gli hotel entro 10 chilometri da un punto di riferimento specificato (dove Location è un campo di tipo Edm.GeographyPoint):
$filter=geo.distance(Location, geography'POINT(-122.131577 47.678581)') le 10
Trovare tutti gli hotel all'interno di un determinato viewport descritto come poligono (dove Location è un campo di tipo Edm.GeographyPoint). Il poligono deve essere chiuso, ovvero il primo e l'ultimo set di punti devono essere uguali. Inoltre, i punti devono essere elencati in ordine antiorario.
$filter=geo.intersects(Location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')
Trovare tutti gli hotel in cui il campo "Descrizione" è null. Il campo sarà Null se non è mai stato impostato o se è stato impostato in modo esplicito su Null:
$filter=Description eq null
Trova tutti gli hotel con nome uguale a "Sea View motel" o "Budget hotel". Queste frasi contengono spazi e lo spazio è un delimitatore predefinito. È possibile specificare un delimitatore alternativo tra virgolette singole come terzo parametro stringa:
$filter=search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Trovare tutti gli alberghi con nome uguale a "Sea View motel" o "Budget hotel" separati da '|':
$filter=search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Trova tutti gli alberghi in cui tutte le camere hanno il tag 'wifi' o 'tub':
$filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))
Trovare una corrispondenza sulle frasi all'interno di una raccolta, ad esempio "asciugamani riscaldati" o "asciugamani riscaldati" inclusi nei tag.
$filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Trovare documenti con la parola "waterfront". Questa query di filtro è identica a una richiesta di ricerca con search=waterfront.
$filter=search.ismatchscoring('waterfront')
Trovare i documenti con la parola "hostel" e classificazione 4 o superiore oppure i documenti con la parola "motel" e classificazione 5. Questa richiesta non può essere espressa senza la search.ismatchscoring funzione perché combina la ricerca full-text con operazioni di filtro tramite or.
$filter=search.ismatchscoring('hostel') and rating ge 4 or search.ismatchscoring('motel') and rating eq 5
Trovare i documenti senza la parola "luxury".
$filter=not search.ismatch('luxury')
Trovare i documenti con la frase "ocean view" o classificazione 5. La query search.ismatchscoring verrà eseguita solo sui campi HotelName e Description. I documenti che corrispondono solo alla seconda clausola della disgiunzione verranno restituiti anche - hotel con Rating uguale a 5. Tali documenti verranno restituiti con un punteggio uguale a zero per chiarire che non corrispondono ad alcuna delle parti con punteggio dell'espressione.
$filter=search.ismatchscoring('"ocean view"', 'Description,HotelName') or Rating eq 5
Trova hotel dove i termini "hotel" e "aeroporto" non sono più di cinque parole a parte nella descrizione, e dove tutte le camere sono non fumate. Questa query usa il linguaggio di query Lucene completo.
$filter=search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and not Rooms/any(room: room/SmokingAllowed)
Trovare documenti con una parola che inizia con le lettere "lux" nel campo Descrizione. Questa query usa la ricerca del prefisso in combinazione con search.ismatch.
$filter=search.ismatch('lux*', 'Description')