Funzione OData search.in
in Ricerca di intelligenza artificiale di Azure
Uno scenario comune nelle espressioni di filtro OData consiste nel verificare se un singolo campo in ogni documento è uguale a uno dei molti valori possibili. Ad esempio, questo è il modo in cui alcune applicazioni implementano il taglio della sicurezza, controllando un campo contenente uno o più ID entità rispetto a un elenco di ID entità che rappresentano l'utente che esegue la query. Un modo per scrivere una query simile alla seguente consiste nell'usare gli eq
operatori e or
:
group_ids/any(g: g eq '123' or g eq '456' or g eq '789')
Tuttavia, esiste un modo più breve per scrivere questa operazione, usando la search.in
funzione :
group_ids/any(g: search.in(g, '123, 456, 789'))
Importante
Oltre a essere più breve e più facile da leggere, l'uso offre search.in
anche vantaggi in termini di prestazioni ed evita alcune limitazioni di dimensioni dei filtri quando sono presenti centinaia o persino migliaia di valori da includere nel filtro. Per questo motivo, è consigliabile usare search.in
anziché una disgiunzione più complessa delle espressioni di uguaglianza.
Nota
La versione 4.01 dello standard OData ha recentemente introdotto l'operatorein
, che ha un comportamento simile alla search.in
funzione in Ricerca di intelligenza artificiale di Azure. Tuttavia, Ricerca intelligenza artificiale di Azure non supporta questo operatore, pertanto è necessario usare la search.in
funzione .
Sintassi
Il seguente EBNF (Extended Backus-Naur Form) definisce la grammatica della search.in
funzione:
search_in_call ::=
'search.in(' variable ',' string_literal(',' string_literal)? ')'
È 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.
La search.in
funzione verifica se un determinato campo stringa o variabile di intervallo è uguale a uno di un determinato elenco di valori. L'uguaglianza tra la variabile e ogni valore nell'elenco viene determinata in modo con distinzione tra maiuscole e minuscole, come per l'operatore eq
. Un'espressione come search.in(myfield, 'a, b, c')
equivale quindi a myfield eq 'a' or myfield eq 'b' or myfield eq 'c'
, tranne per il fatto che search.in
garantisce prestazioni di gran lunga migliori.
Esistono due overload della search.in
funzione:
search.in(variable, valueList)
search.in(variable, valueList, delimiters)
I parametri sono definiti nella tabella seguente:
Nome parametro | Tipo | Descrizione |
---|---|---|
variable |
Edm.String |
Riferimento a un campo stringa (o una variabile di intervallo su un campo della raccolta di stringhe nel caso in cui search.in viene usato all'interno di un'espressione any o all ). |
valueList |
Edm.String |
Stringa contenente un elenco delimitato di valori da trovare con il variable parametro . Se il delimiters parametro non viene specificato, i delimitatori predefiniti sono spazi e virgole. |
delimiters |
Edm.String |
Stringa in cui ogni carattere viene considerato come separatore durante l'analisi del valueList parametro. Il valore predefinito di questo parametro è ' ,' il che significa che tutti i valori con spazi e/o virgole tra di essi verranno separati. Se è necessario usare separatori diversi da spazi e virgole perché i valori includono tali caratteri, è possibile specificare delimitatori alternativi, '|' ad esempio in questo parametro. |
Prestazioni di search.in
Se si usa search.in
, è previsto un tempo di risposta inferiore al secondo quando il secondo parametro contiene un elenco di centinaia o migliaia di valori. Non esiste alcun limite esplicito al numero di elementi che è possibile passare a search.in
, anche se le dimensioni massime della richiesta sono ancora limitate. Tuttavia, la latenza aumenterà man mano che aumenta il numero di valori.
Esempi
Trova tutti gli hotel con nome uguale a "Sea View motel" o "Budget hotel". Le frasi contengono spazi, ovvero un delimitatore predefinito. È possibile specificare un delimitatore alternativo tra virgolette singole come terzo parametro stringa:
search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Trovare tutti gli alberghi con nome uguale a "Sea View motel" o "Budget hotel" separati da '|':
search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Trova tutti gli alberghi con camere con il tag 'wifi' o 'tub':
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.
Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Trova tutti gli alberghi senza il tag 'motel' o 'cabin':
Tags/all(tag: not search.in(tag, 'motel, cabin'))