Panoramica del linguaggio OData per $filter, $orderbye $select in Ricerca di intelligenza artificiale di Azure
Questo articolo offre una panoramica del linguaggio delle espressioni OData usato in $filter, $order e $select espressioni in Ricerca di intelligenza artificiale di Azure. Il linguaggio viene presentato "bottom-up" a partire dagli elementi più di base. Le espressioni OData che è possibile costruire in un intervallo di richieste di query da semplice a 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:
- $filter le espressioni vengono valutate durante l'analisi delle query, vincolando la ricerca a campi specifici o aggiungendo criteri di corrispondenza usati durante le analisi dell'indice.
- $orderby espressioni vengono applicate come passaggio di post-elaborazione su un set di risultati per ordinare i documenti restituiti.
- $select espressioni 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.
Nota
La terminologia in Ricerca di intelligenza artificiale di Azure differisce dallo standard OData in alcuni modi. Quello che chiamiamo un campo in Ricerca di intelligenza artificiale di Azure è una proprietà in OData e analogamente per il percorso del campo rispetto al percorso della proprietà. Un indice contenente documenti in Ricerca di intelligenza artificiale di Azure viene in genere indicato in OData come set di entità contenente entità. La terminologia di Ricerca intelligenza artificiale di Azure viene usata in questo riferimento.
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:
Nota
Vedere Informazioni di riferimento sulla sintassi delle espressioni OData per Ricerca di intelligenza artificiale di Azure per l'EBNF completo.
Un percorso di campo è composto da uno o più identificatori separati da barre. Ogni identificatore è una sequenza di caratteri che devono 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'espressionedi 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 raccolte complesse, tale variabile rappresenta un oggetto, motivo per cui è possibile usare i percorsi dei campi per fare riferimento ai sottocampi della variabile. Questo è analogo alla notazione con punti in molti linguaggi di programmazione.
Nella tabella seguente sono riportati alcuni esempi di percorsi di campo:
| Percorso campo | Descrizione |
|---|---|
HotelName |
Fa riferimento a un campo di primo livello dell'indice |
Address/City |
Fa riferimento al City sottocampo di un campo complesso nell'indice; Address è di tipo Edm.ComplexType in questo esempio |
Rooms/Type |
Fa riferimento al Type sottocampo di un campo di raccolta complesso nell'indice; Rooms è di tipo Collection(Edm.ComplexType) in questo esempio |
Stores/Address/Country |
Fa riferimento al Country sottocampo del Address sottocampo di un campo di raccolta complesso nell'indice; Stores è di tipo ed Address è di tipo Collection(Edm.ComplexType)Edm.ComplexType in questo esempio |
room/Type |
Fa riferimento al Type sottocampo della room variabile di intervallo, ad esempio nell'espressione di filtro Rooms/any(room: room/Type eq 'deluxe') |
store/Address/Country |
Fa riferimento al Country sottocampo del Address sottocampo della store variabile di intervallo, ad esempio nell'espressione di filtro Stores/any(store: store/Address/Country eq 'Canada') |
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 campiata nella sintassi Lucene completa, un percorso di campo fa riferimento al campo stesso. Questa differenza ha alcune conseguenze per l'uso dei percorsi dei campi nei filtri.
Si consideri il percorso Address/Citydel campo . In un filtro si riferisce a una singola città per il documento corrente, ad esempio "San Francisco". Al contrario, Rooms/Type si riferisce al Type sottocampo per molte camere (come "standard" per la prima stanza, "deluxe" per la seconda camera e così via). Poiché Rooms/Type non fa riferimento a una singola istanza del sottocampo Type, non può essere usata direttamente in un filtro. Per filtrare in base al tipo di stanza, è 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 room di intervallo viene visualizzata nel percorso del room/Type campo. In questo modo, room/Type fa riferimento al tipo della sala corrente nel documento corrente. Si tratta di una singola istanza del Type sottocampo, quindi può essere usata direttamente nel filtro.
Uso dei percorsi dei campi
I percorsi dei campi vengono usati in molti parametri delle API REST di Ricerca di intelligenza artificiale di Azure. Nella tabella seguente sono elencate tutte le posizioni in cui possono essere usate, oltre a eventuali restrizioni relative all'utilizzo:
| API | Nome parametro | Limitazioni |
|---|---|---|
| Creare o aggiornare l'indice | suggesters/sourceFields |
None |
| Creare o aggiornare l'indice | scoringProfiles/text/weights |
Può fare riferimento solo ai campi ricercabili |
| Creare o aggiornare l'indice | scoringProfiles/functions/fieldName |
Può fare riferimento solo a campi filtrabili |
| Ricerca | search quando queryType è full |
Può fare riferimento solo ai campi ricercabili |
| Ricerca | facet |
Può fare riferimento solo a campi con tabella visibile |
| Ricerca | highlight |
Può fare riferimento solo ai campi ricercabili |
| Ricerca | searchFields |
Può fare riferimento solo ai campi ricercabili |
| Suggerire e completare automaticamente | searchFields |
Può fare riferimento solo ai campi che fanno parte di un suggerimento |
| Ricerca, suggerimento e completamento automatico | $filter |
Può fare riferimento solo a campi filtrabili |
| Cerca e suggerisci | $orderby |
Può fare riferimento solo a campi ordinabili |
| Ricerca, suggerimento e ricerca | $select |
Può fare riferimento solo ai campi recuperabili |
Costanti
Le costanti in OData sono valori letterali di un tipo ENTITY Data Model (EDM) specificato. Vedere Tipi di dati supportati per un elenco dei tipi supportati in Ricerca di intelligenza artificiale di Azure. Le costanti dei tipi di raccolta non sono supportate.
La tabella seguente mostra esempi di costanti per ognuno dei tipi di dati supportati da Ricerca di intelligenza artificiale di Azure:
| Tipo di dati | Costanti di esempio |
|---|---|
Edm.Boolean |
true, false |
Edm.DateTimeOffset |
2019-05-06T12:30:05.451Z |
Edm.Double |
3.14159, -1.2e7, NaN, INF-INF |
Edm.GeographyPoint |
geography'POINT(-122.131577 47.678581)' |
Edm.GeographyPolygon |
geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))' |
Edm.Int32 |
123, -456 |
Edm.Int64 |
283032927235 |
Edm.String |
'hello' |
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 potrebbe contenere virgolette singole, è possibile evitare le virgolette incorporate raddoppiandole.
Ad esempio, una frase con un apostrofo non formattato come "Auto di Alice" verrebbe rappresentata in OData come costante stringa 'Alice''s car'.
Importante
Quando si creano filtri a livello di codice, è importante ricordare di usare costanti stringa di escape provenienti dall'input dell'utente. Ciò consente di attenuare la possibilità di attacchi injection, soprattutto quando si usano filtri per implementare il taglio della sicurezza.
Sintassi 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 Ricerca di intelligenza artificiale di Azure.
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:
Nota
Vedere Informazioni di riferimento sulla sintassi delle espressioni OData per Ricerca di intelligenza artificiale di Azure per l'EBNF completo.
Compilazione di espressioni da percorsi di campo e costanti
I percorsi dei campi e le costanti sono la parte più semplice di un'espressione OData, ma sono già espressioni complete. In effetti, il parametro $select in Ricerca di intelligenza artificiale di Azure 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. Le costanti true e false sono anche filtri validi.
Tuttavia, nella maggior parte dei casi sono necessarie espressioni più 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:
Nota
Vedere Informazioni di riferimento sulla sintassi delle espressioni OData per Ricerca di intelligenza artificiale di Azure per l'EBNF completo.
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, ore not, operatori di confronto comeeq , gtlt, e così via e operatori any di raccolta come e .all
I parametri $filter, $orderby e $select vengono esaminati in modo più dettagliato negli articoli seguenti: