Panoramica del linguaggio OData per $filter, $orderby e $select in Foundry IQ (Azure AI Search)

Nota

Foundry IQ (Azure AI Search) fornisce API dirette di indicizzazione e query, oltre ad API di livello superiore per origini dati di conoscenza e knowledge base per il recupero gestito. Usare il portale di Azure, le API REST o Azure SDK per configurare queste funzionalità o connettere gli agenti alle knowledge base nel portale di Microsoft Foundry.

Questo articolo offre una panoramica del linguaggio delle espressioni OData usato nelle $filterespressioni , $order-bye $select per la ricerca di parole chiave in Foundry IQ (Azure AI Search) su campi numerici e stringa (non operatore).

Il linguaggio viene presentato dal basso in alto, a partire dagli elementi più basici. Le espressioni OData che si possono costruire in una query possono spaziare da semplici ad altamente complesse, ma condividono tutti alcuni 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 della query, limitando la ricerca a campi specifici o aggiungendo criteri di corrispondenza utilizzati durante le scansioni 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 quali campi del documento sono 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.

Nota

La terminologia di Foundry IQ differisce dallo standard OData per alcuni aspetti. Ciò che chiamiamo campo in Foundry IQ viene chiamato una proprietà in OData e analogamente per il percorso del campo rispetto al percorso della proprietà. Un index contenente documenti in Foundry IQ viene in genere definito in OData come un set di entità contenente entità. La terminologia di Foundry IQ 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:

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:

Percorso di campo Descrizione
HotelName Fa riferimento a un campo di primo livello dell'indice
Address/City Fa riferimento al sottocampo City di un campo complesso nell'indice; Address è di tipo Edm.ComplexType in questo esempio
Rooms/Type Fa riferimento al sottocampo Type di un campo di raccolta complesso nell'indice; Rooms è di tipo Collection(Edm.ComplexType) in questo esempio
Stores/Address/Country Fa riferimento al sottocampo Country del sottocampo Address di un campo di raccolta complesso nell'indice; Stores è di tipo Collection(Edm.ComplexType) e Address è di tipo Edm.ComplexType in questo esempio
room/Type Fa riferimento al sottocampo Type della variabile di intervallo room, ad esempio nell'espressione di filtro Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Fa riferimento al sottocampo Country del sottocampo Address della variabile di intervallo store, 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 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 room 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 dei campi vengono usati in molti parametri delle API REST di Foundry IQ. Nella tabella seguente sono elencate tutte le posizioni in cui possono essere usati, oltre a eventuali restrizioni relative all'utilizzo:

API (Interfaccia di Programmazione delle Applicazioni) Nome parametro Restrizioni
Creare o aggiornare l'indice suggesters/sourceFields Nessuno
Crea o Aggiorna l'indice scoringProfiles/text/weights Può fare riferimento solo a campi ricercabili
Crea o aggiorna l'indice scoringProfiles/functions/fieldName Può fare riferimento solo a campi filtrabili
Cerca search quando queryType è full Può fare riferimento solo a campi ricercabili
Cerca facet Può fare riferimento solo a campi facettabili
Cerca highlight Può fare riferimento solo a campi ricercabili
Cerca searchFields Può fare riferimento solo a campi ricercabili
Suggerimenti e Completamento automatico searchFields Può fare riferimento solo ai campi che fanno parte di un suggeritore
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, Suggerisci e ricerca puntuale $select Può fare riferimento solo a campi recuperabili

Costanti

Le costanti in OData sono valori letterali di un tipo Entity Data Model (EDM) specificato. Per un elenco dei tipi supportati in Foundry IQ, vedere Tipi di dati supportati . Le costanti dei tipi di raccolta non sono supportate.

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

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

Importante

Quando si creano filtri a livello di codice, è importante ricordare di eseguire l'escape di costanti stringa provenienti dall'input dell'utente. Questo consente di mitigare la possibilità di attacchi di injection, soprattutto quando si usano filtri per implementare la limitazione per motivi di sicurezza.

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 geospaziali si trova in funzioni geospaziali OData in Foundry IQ.

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 Foundry IQ 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: