Funzione OData search.in in Ricerca cognitiva 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 trimming di 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 search.in di offre 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 cognitiva di Azure. Ricerca cognitiva di Azure non supporta tuttavia 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:

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 di campo stringa (o variabile di intervallo su un campo della raccolta di stringhe nel caso in cui search.in venga 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 indica ' ,' 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 per il 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.

Esempio

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

Trova tutti gli hotel con nome uguale a 'Sea View motel' o 'Budget hotel' separato da '|'):

    search.in(HotelName, 'Sea View motel|Budget hotel', '|')

Trova tutti gli hotel con camere con il tag 'wifi' o 'tub':

    Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))

Trova una corrispondenza sulle frasi all'interno di una raccolta, ad esempio "rack asciugamani riscaldati" o "incluso" in tag.

    Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))

Trova tutti gli hotel senza il tag 'motel' o 'cabin':

    Tags/all(tag: not search.in(tag, 'motel, cabin'))

Passaggi successivi