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'))