Panoramica del linguaggio OData per $filter , $orderby e $select in Azure ricerca cognitivaOData language overview for $filter, $orderby, and $select in Azure Cognitive Search

Azure ricerca cognitiva supporta un subset della sintassi delle espressioni OData per le espressioni $Filter, $OrderBye $Select .Azure Cognitive Search supports a subset of the OData expression syntax for $filter, $orderby, and $select expressions. Le espressioni filtro vengono valutate durante l'analisi della query, vincolando la ricerca a campi specifici o aggiungendo criteri di corrispondenza durante le analisi dell'indice.Filter expressions are evaluated during query parsing, constraining search to specific fields or adding match criteria used during index scans. Le espressioni order-by vengono applicate come passaggio di post-elaborazione su un set di risultati per ordinare i documenti restituiti.Order-by expressions are applied as a post-processing step over a result set to sort the documents that are returned. Le espressioni Select determinano i campi del documento inclusi nel set di risultati.Select expressions determine which document fields are included in the result set. La sintassi di queste espressioni è diversa dalla sintassi di query semplice o completa utilizzata nel parametro di ricerca , anche se c'è una sovrapposizione nella sintassi per i campi di riferimento.The syntax of these expressions is distinct from the simple or full query syntax that is used in the search parameter, although there's some overlap in the syntax for referencing fields.

In questo articolo viene fornita una panoramica del linguaggio delle espressioni OData utilizzato nei filtri, in order-by e nelle espressioni Select.This article provides an overview of the OData expression language used in filters, order-by, and select expressions. Il linguaggio viene presentato "dal basso verso l'alto", iniziando dagli elementi più semplici e creandoli.The language is presented "bottom-up", starting with the most basic elements and building on them. La sintassi di primo livello per ogni parametro è descritta in un articolo separato:The top-level syntax for each parameter is described in a separate article:

Le espressioni OData variano da semplice a estremamente complesso, ma condividono tutti elementi comuni.OData expressions range from simple to highly complex, but they all share common elements. Le parti più semplici di un'espressione OData in Azure ricerca cognitiva sono:The most basic parts of an OData expression in Azure Cognitive Search are:

  • Percorsi dei campi, che fanno riferimento a campi specifici dell'indice.Field paths, which refer to specific fields of your index.
  • Costanti, che sono valori letterali di un determinato tipo di dati.Constants, which are literal values of a certain data type.

Nota

La terminologia in Azure ricerca cognitiva differisce dallo standard OData in diversi modi.Terminology in Azure Cognitive Search differs from the OData standard in a few ways. Ciò che chiamiamo un campo in Azure ricerca cognitiva è denominato Proprietà in OData e in modo analogo per il percorso del campo rispetto al percorso della proprietà.What we call a field in Azure Cognitive Search is called a property in OData, and similarly for field path versus property path. Un Indice contenente documenti in Azure ricerca cognitiva viene definito più in generale in OData come set di entità che contiene le entità.An index containing documents in Azure Cognitive Search is referred to more generally in OData as an entity set containing entities. La terminologia del ricerca cognitiva di Azure viene usata in tutto questo riferimento.The Azure Cognitive Search terminology is used throughout this reference.

Percorsi dei campiField paths

Il seguente EBNF (extended Backus-Naur form) definisce la grammatica dei percorsi dei campi.The following EBNF (Extended Backus-Naur Form) defines the grammar of field paths.

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

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

È disponibile anche un diagramma della sintassi interattiva:An interactive syntax diagram is also available:

Un percorso di campo è composto da uno o più identificatori separati da barre.A field path is composed of one or more identifiers separated by slashes. Ogni identificatore è una sequenza di caratteri che deve iniziare con una lettera ASCII o un carattere di sottolineatura e contenere solo lettere, cifre o caratteri di sottolineatura ASCII.Each identifier is a sequence of characters that must start with an ASCII letter or underscore, and contain only ASCII letters, digits, or underscores. Le lettere possono essere maiuscole o minuscole.The letters can be upper- or lower-case.

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.An identifier can refer either to the name of a field, or to a range variable in the context of a collection expression (any or all) in a filter. Una variabile di intervallo è analoga a una variabile di ciclo che rappresenta l'elemento corrente della raccolta.A range variable is like a loop variable that represents the current element of the collection. Per le raccolte complesse, tale variabile rappresenta un oggetto, motivo per cui è possibile utilizzare i percorsi dei campi per fare riferimento a sottocampi della variabile.For complex collections, that variable represents an object, which is why you can use field paths to refer to sub-fields of the variable. Questo è analogo alla notazione del punto in molti linguaggi di programmazione.This is analogous to dot notation in many programming languages.

Nella tabella seguente sono riportati alcuni esempi di percorsi dei campi:Examples of field paths are shown in the following table:

Percorso campoField path DescrizioneDescription
HotelName Fa riferimento a un campo di primo livello dell'indiceRefers to a top-level field of the index
Address/City Si riferisce al campo City secondario di un campo complesso nell'indice. Address è di tipo Edm.ComplexType in questo esempioRefers to the City sub-field of a complex field in the index; Address is of type Edm.ComplexType in this example
Rooms/Type Si riferisce al campo Type secondario di un campo di raccolta complesso nell'indice. Rooms è di tipo Collection(Edm.ComplexType) in questo esempioRefers to the Type sub-field of a complex collection field in the index; Rooms is of type Collection(Edm.ComplexType) in this example
Stores/Address/Country Fa riferimento al campo Country secondario del Address sottocampo di un campo di raccolta complesso nell'indice. Stores è di tipo Collection(Edm.ComplexType) e Address è di tipo Edm.ComplexType in questo esempioRefers to the Country sub-field of the Address sub-field of a complex collection field in the index; Stores is of type Collection(Edm.ComplexType) and Address is of type Edm.ComplexType in this example
room/Type Fa riferimento al Type sottocampo della variabile di room intervallo, ad esempio nell'espressione di filtro Rooms/any(room: room/Type eq 'deluxe')Refers to the Type sub-field of the room range variable, for example in the filter expression Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Si riferisce al Country campo secondario del Address sottocampo della variabile di store intervallo, ad esempio nell'espressione di filtro. Stores/any(store: store/Address/Country eq 'Canada')Refers to the Country sub-field of the Address sub-field of the store range variable, for example in the filter expression Stores/any(store: store/Address/Country eq 'Canada')

Il significato di un percorso di campo varia a seconda del contesto.The meaning of a field path differs depending on the context. Nei filtri, il percorso di un campo fa riferimento al valore di una singola istanza di un campo nel documento corrente.In filters, a field path refers to the value of a single instance of a field in the current document. In altri contesti, ad esempio $OrderBy, $SELECTo nella ricerca sul campo nella sintassi Lucene completa, un percorso di campo fa riferimento al campo stesso.In other contexts, such as $orderby, $select, or in fielded search in the full Lucene syntax, a field path refers to the field itself. Questa differenza ha alcune conseguenze sull'uso dei percorsi dei campi nei filtri.This difference has some consequences for how you use field paths in filters.

Si consideri il percorso del campo Address/City .Consider the field path Address/City. In un filtro si fa riferimento a una singola città per il documento corrente, ad esempio "San Francisco".In a filter, this refers to a single city for the current document, like "San Francisco". Al contrario, Rooms/Type si riferisce al Type campo secondario per molte stanze, ad esempio "standard" per la prima stanza, "Deluxe" per la seconda stanza e così via.In contrast, Rooms/Type refers to the Type sub-field for many rooms (like "standard" for the first room, "deluxe" for the second room, and so on). Poiché Rooms/Type non fa riferimento a una singola istanza del sottocampo Type , non può essere utilizzato direttamente in un filtro.Since Rooms/Type doesn't refer to a single instance of the sub-field Type, it can't be used directly in a filter. Per filtrare il tipo di stanza, usare invece un' espressione lambda con una variabile di intervallo, come indicato di seguito:Instead, to filter on room type, you would use a lambda expression with a range variable, like this:

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

In questo esempio, la variabile room di intervallo viene visualizzata nel room/Type percorso del campo.In this example, the range variable room appears in the room/Type field path. In questo modo, room/Type si riferisce al tipo di spazio corrente nel documento corrente.That way, room/Type refers to the type of the current room in the current document. Si tratta di una singola istanza del Type sottocampo, che può quindi essere utilizzata direttamente nel filtro.This is a single instance of the Type sub-field, so it can be used directly in the filter.

Uso dei percorsi dei campiUsing field paths

I percorsi dei campi vengono usati in molti parametri delle API REST di Azure ricerca cognitiva.Field paths are used in many parameters of the Azure Cognitive Search REST APIs. Nella tabella seguente sono elencate tutte le posizioni in cui è possibile utilizzare, oltre a eventuali restrizioni relative all'utilizzo:The following table lists all the places where they can be used, plus any restrictions on their usage:

APIAPI Nome parametroParameter name RestrizioniRestrictions
Crea o Aggiorna indiceCreate or Update Index suggesters/sourceFields NessunoNone
Crea o Aggiorna indiceCreate or Update Index scoringProfiles/text/weights Può fare riferimento solo a campi ricercabiliCan only refer to searchable fields
Crea o Aggiorna indiceCreate or Update Index scoringProfiles/functions/fieldName Può fare riferimento solo a campi filtrabiliCan only refer to filterable fields
RicercaSearch search Quando queryType è fullsearch when queryType is full Può fare riferimento solo a campi ricercabiliCan only refer to searchable fields
RicercaSearch facet Può fare riferimento solo a campi facetCan only refer to facetable fields
RicercaSearch highlight Può fare riferimento solo a campi ricercabiliCan only refer to searchable fields
RicercaSearch searchFields Può fare riferimento solo a campi ricercabiliCan only refer to searchable fields
Suggerisci e completamento automaticoSuggest and Autocomplete searchFields Può fare riferimento solo a campi che fanno parte di un componente di SuggerimentoCan only refer to fields that are part of a suggester
Ricerca, suggerimentie completamento automaticoSearch, Suggest, and Autocomplete $filter Può fare riferimento solo a campi filtrabiliCan only refer to filterable fields
Cerca e SuggerisciSearch and Suggest $orderby Può fare riferimento solo a campi ordinabiliCan only refer to sortable fields
Ricerca, suggerimentie ricercaSearch, Suggest, and Lookup $select Può fare riferimento solo a campi recuperabiliCan only refer to retrievable fields

CostantiConstants

Le costanti in OData sono valori letterali di un determinato tipo di Entity Data Model (EDM).Constants in OData are literal values of a given Entity Data Model (EDM) type. Per un elenco dei tipi supportati in Azure ricerca cognitiva, vedere tipi di dati supportati .See Supported data types for a list of supported types in Azure Cognitive Search. Le costanti dei tipi di raccolta non sono supportate.Constants of collection types aren't supported.

La tabella seguente illustra esempi di costanti per ognuno dei tipi di dati supportati da Azure ricerca cognitiva:The following table shows examples of constants for each of the data types supported by Azure Cognitive Search:

Tipo di datiData type Costanti di esempioExample constants
Edm.Boolean true, falsetrue, false
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double 3.14159, -1.2e7, NaN, INF, -INF3.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, -456123, -456
Edm.Int64 283032927235
Edm.String 'hello'

Escape di caratteri speciali nelle costanti stringaEscaping special characters in string constants

Le costanti di stringa in OData sono delimitate da virgolette singole.String constants in OData are delimited by single quotes. Se è necessario creare una query con una costante di stringa che può contenere virgolette singole, è possibile eseguire il escape delle virgolette incorporate tramite il raddoppio.If you need to construct a query with a string constant that might itself contain single quotes, you can escape the embedded quotes by doubling them.

Ad esempio, una frase con un apostrofo non formattato come "Alice ' s Car" verrebbe rappresentata in OData come costante di stringa 'Alice''s car' .For example, a phrase with an unformatted apostrophe like "Alice's car" would be represented in OData as the string constant 'Alice''s car'.

Importante

Quando si creano i filtri a livello di codice, è importante ricordare che le costanti di stringa di escape provengono dall'input dell'utente.When constructing filters programmatically, it's important to remember to escape string constants that come from user input. Questo consente di ridurre la possibilità di attacchi injection, soprattutto quando si usano i filtri per implementare la rimozione della sicurezza.This is to mitigate the possibility of injection attacks, especially when using filters to implement security trimming.

Sintassi delle costantiConstants syntax

Il seguente EBNF (extended Backus-Naur form) definisce la grammatica per la maggior parte delle costanti mostrate nella tabella precedente.The following EBNF (Extended Backus-Naur Form) defines the grammar for most of the constants shown in the above table. La grammatica per i tipi geospaziali si trova in funzioni geospaziali OData in Azure ricerca cognitiva.The grammar for geo-spatial types can be found in OData geo-spatial functions in Azure Cognitive 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 della sintassi interattiva:An interactive syntax diagram is also available:

Compilazione di espressioni da percorsi e costanti dei campiBuilding expressions from field paths and constants

Le costanti e i percorsi dei campi rappresentano la parte fondamentale di un'espressione OData, ma sono già espressioni complete.Field paths and constants are the most basic part of an OData expression, but they're already full expressions themselves. Infatti, il $Select parametro in Azure ricerca cognitiva non è altro che un elenco delimitato da virgole di percorsi di campo e $OrderBy non è molto più complicato di $Select.In fact, the $select parameter in Azure Cognitive Search is nothing but a comma-separated list of field paths, and $orderby isn't much more complicated than $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.If you happen to have a field of type Edm.Boolean in your index, you can even write a filter that is nothing but the path of that field. Le costanti true e false sono anche filtri validi.The constants true and false are likewise valid filters.

Tuttavia, nella maggior parte dei casi sono necessarie espressioni più complesse che fanno riferimento a più di un campo e una costante.However, most of the time you'll need more complex expressions that refer to more than one field and constant. Queste espressioni sono compilate in modi diversi a seconda del parametro.These expressions are built in different ways depending on the parameter.

Il seguente EBNF (extended Backus-Naur form) definisce la grammatica per i parametri $Filter, $OrderBye $Select .The following EBNF (Extended Backus-Naur Form) defines the grammar for the $filter, $orderby, and $select parameters. Queste sono costituite da espressioni più semplici che fanno riferimento a percorsi e costanti dei campi:These are built up from simpler expressions that refer to field paths and constants:

filter_expression ::= boolean_expression

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

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

È disponibile anche un diagramma della sintassi interattiva:An interactive syntax diagram is also available:

I parametri $OrderBy e $SELECT sono elenchi delimitati da virgole di espressioni più semplici.The $orderby and $select parameters are both comma-separated lists of simpler expressions. Il parametro $Filter è un'espressione booleana composta da sottoespressioni più semplici.The $filter parameter is a Boolean expression that is composed of simpler sub-expressions. Queste sottoespressioni vengono combinate utilizzando operatori logici, ad esempio, and or e not , operatori di confronto come eq ,, lt gt e così via, e operatori di raccolta quali any e all .These sub-expressions are combined using logical operators such as and, or, and not, comparison operators such as eq, lt, gt, and so on, and collection operators such as any and all.

I parametri $Filter, $OrderBye $Select vengono esaminati in modo più dettagliato negli articoli seguenti:The $filter, $orderby, and $select parameters are explored in more detail in the following articles:

Vedere ancheSee also