Panoramica del linguaggio OData per $filter, $orderby e $select in Azure AI Search

Questo articolo offre una panoramica del linguaggio di espressione OData usato nelle espressioni $filter, $order-by e $select per la ricerca di parole chiave in Azure AI Search sui campi numerici e stringa (non vettoriali).

Il linguaggio viene presentato dal basso in alto, a partire dagli elementi più basici. Le espressioni OData che è possibile costruire in una query richiedono un intervallo da semplice ad alta complessità, ma condividono tutti elementi comuni. Gli elementi condivisi includono:

• Percorsi dei campi, che fanno riferimento a campi specifici dell'indice.
• Costanti, che sono valori letterali di un determinato tipo di dati.

Dopo aver compreso questi concetti comuni, è possibile continuare con la sintassi di primo livello per ogni espressione:

• Le espressioni $filter vengono valutate durante l'analisi della query, vincolando la ricerca a campi specifici o aggiungendo criteri di corrispondenza durante le analisi dell'indice.
• Le espressioni $orderby vengono applicate come passaggio di post-elaborazione su un set di risultati per ordinare i documenti restituiti.
• Le espressioni $select determinano i campi del documento inclusi nel set di risultati.

La sintassi di queste espressioni è distinta dalla sintassi di query semplice o completa usata nel parametro di ricerca, anche se nella sintassi per fare riferimento ai campi è presente una certa sovrapposizione.

Per esempi in altri linguaggi, ad esempio Python o C#, vedere gli esempi nel repository azure-search-vector-samples.

Percorsi dei campi

Il seguente EBNF (Extended Backus-Naur Form) definisce la grammatica dei percorsi dei campi.

field_path ::= identifier('/'identifier)*

identifier ::= [a-zA-Z_][a-zA-Z_0-9]*

È disponibile anche un diagramma di sintassi interattivo:

Un percorso di campo è composto da uno o più identificatori separati da barre. Ogni identificatore è una sequenza di caratteri che deve iniziare con una lettera o un carattere di sottolineatura ASCII e contenere solo lettere, cifre o caratteri di sottolineatura ASCII. Le lettere possono essere maiuscole o minuscole.

Un identificatore può fare riferimento al nome di un campo o a una variabile di intervallo nel contesto di un'espressione di raccolta (any o all) in un filtro. Una variabile di intervallo è simile a una variabile di ciclo che rappresenta l'elemento corrente della raccolta. Per le raccolte complesse, tale variabile rappresenta un oggetto, motivo per cui è possibile usare i percorsi dei campi per fare riferimento ai sottocampi della variabile. La situazione è analoga alla notazione con il punto di molti linguaggi di programmazione.

Nella tabella seguente sono riportati alcuni esempi di percorsi di campi:

Il significato di un percorso di campo varia a seconda del contesto. Nei filtri, un percorso di campo fa riferimento al valore di una singola istanza di un campo nel documento corrente. In altri contesti, ad esempio $orderby, $select o nella ricerca con campi nella sintassi Lucene completa, un percorso di campo fa riferimento al campo stesso. Questa differenza ha alcune conseguenze nell'uso dei percorsi dei campi nei filtri.

Si consideri il percorso di campo Address/City. In un filtro, si riferisce a una sola città per il documento corrente, ad esempio "San Francisco". Al contrario, Rooms/Type si riferisce al sottocampo Type per molte camere (come "standard" per la prima camera, "deluxe" per la seconda camera e così via). Poiché Rooms/Type non fa riferimento a una istanza singola del sottocampo Type, non può essere usata direttamente in un filtro. Per filtrare in base al tipo di camera, è invece necessario usare un'espressione lambda con una variabile di intervallo, come illustrato di seguito:

Rooms/any(room: room/Type eq 'deluxe')

In questo esempio la variabile di intervallo room viene visualizzata nel percorso di campo room/Type. In questo modo, room/Type fa riferimento al tipo di camera corrente nel documento corrente. Si tratta di una singola istanza del sottocampo Type, quindi può essere usata direttamente nel filtro.

Uso dei percorsi di campo

I percorsi di campo vengono usati in molti parametri delle API REST di Azure AI Search. Nella tabella seguente sono elencate tutte le posizioni in cui possono essere usati, oltre a eventuali restrizioni relative all'utilizzo:

Costanti

Le costanti in OData sono valori letterali di un tipo Entity Data Model (EDM) specificato. Vedere Tipi di dati supportati per trovare un elenco dei tipi supportati in Azure AI Search. Le costanti dei tipi di raccolte non sono supportate.

La tabella seguente mostra esempi di costanti per ognuno dei tipi di dati non vettoriali che supportano le espressioni OData:

Escape di caratteri speciali nelle costanti stringa

Le costanti stringa in OData sono delimitate da virgolette singole. Se è necessario costruire una query con una costante stringa che può contenere virgolette singole, è possibile evitare le virgolette incorporate raddoppiandole.

Ad esempio, una frase con un apostrofo non formattato come "L'auto di Alice" verrebbe rappresentata in OData come costante stringa 'Alice''s car'.

Sintassi delle costanti

Il seguente EBNF (Extended Backus-Naur Form) definisce la grammatica per la maggior parte delle costanti illustrate nella tabella precedente. La grammatica per i tipi geo-spaziali è reperibile in Funzioni geo-spaziali OData in Azure AI Search.

constant ::=
    string_literal
    | date_time_offset_literal
    | integer_literal
    | float_literal
    | boolean_literal
    | 'null'

string_literal ::= "'"([^'] | "''")*"'"

date_time_offset_literal ::= date_part'T'time_part time_zone

date_part ::= year'-'month'-'day

time_part ::= hour':'minute(':'second('.'fractional_seconds)?)?

zero_to_fifty_nine ::= [0-5]digit

digit ::= [0-9]

year ::= digit digit digit digit

month ::= '0'[1-9] | '1'[0-2]

day ::= '0'[1-9] | [1-2]digit | '3'[0-1]

hour ::= [0-1]digit | '2'[0-3]

minute ::= zero_to_fifty_nine

second ::= zero_to_fifty_nine

fractional_seconds ::= integer_literal

time_zone ::= 'Z' | sign hour':'minute

sign ::= '+' | '-'

/* In practice integer literals are limited in length to the precision of
the corresponding EDM data type. */
integer_literal ::= digit+

float_literal ::=
    sign? whole_part fractional_part? exponent?
    | 'NaN'
    | '-INF'
    | 'INF'

whole_part ::= integer_literal

fractional_part ::= '.'integer_literal

exponent ::= 'e' sign? integer_literal

boolean_literal ::= 'true' | 'false'

È disponibile anche un diagramma di sintassi interattivo:

Compilazione di espressioni da percorsi di campo e costanti

I percorsi di campo e le costanti sono la parte più semplice di un'espressione OData, ma sono già espressioni complete. In effetti, il parametro $select in Azure AI Search non è altro che un elenco delimitato da virgole di percorsi di campo e $orderby non è molto più complicato di $select. Se si dispone di un campo di tipo Edm.Boolean nell'indice, è anche possibile scrivere un filtro che non sia altro che il percorso di tale campo. Anche le costanti true e false sono filtri validi.

Tuttavia, è più comune avere espressioni complesse che fanno riferimento a più campi e costanti. Queste espressioni vengono compilate in modi diversi a seconda del parametro.

Il seguente EBNF (Extended Backus-Naur Form) definisce la grammatica per i parametri $filter, $orderby e $select. Si tratta di espressioni più semplici che fanno riferimento a percorsi di campo e costanti:

filter_expression ::= boolean_expression

order_by_expression ::= order_by_clause(',' order_by_clause)*

select_expression ::= '*' | field_path(',' field_path)*

È disponibile anche un diagramma di sintassi interattivo:

Passaggi successivi

I parametri $orderby e $select sono entrambi elenchi delimitati da virgole di espressioni più semplici. Il parametro $filter è un'espressione booleana composta da sottoespressioni più semplici. Queste sottoespressioni vengono combinate usando operatori logici come and, or e not, operatori di confronto come eq, lt, gt e così via e operatori di raccolta come any e all.

I parametri $filter, $orderbye $select vengono esaminati in modo più dettagliato negli articoli seguenti:

• Sintassi di $filter OData in Azure AI Search
• Sintassi di $orderby OData in Azure AI Search
• Sintassi di $select OData in Azure AI Search