Azure 'da $filter, $orderbyve $select için OData diline genel bakış Bilişsel AramaOData language overview for $filter, $orderby, and $select in Azure Cognitive Search

Azure Bilişsel Arama, $Filter, $OrderByve $Select ifadelerine yönelik OData ifade sözdiziminin bir alt kümesini destekler.Azure Cognitive Search supports a subset of the OData expression syntax for $filter, $orderby, and $select expressions. Filtre ifadeleri sorgu ayrıştırma sırasında değerlendirilir, aramayı belirli alanlara kısıtlama veya dizin taramaları sırasında kullanılan eşleşme ölçütlerini ekleme.Filter expressions are evaluated during query parsing, constraining search to specific fields or adding match criteria used during index scans. Sıra ifadeleri, döndürülen belgeleri sıralamak için bir sonuç kümesi üzerinde bir işleme sonrası adımı olarak uygulanır.Order-by expressions are applied as a post-processing step over a result set to sort the documents that are returned. Sonuç kümesinde hangi belge alanlarının ekleneceğini belirleyen ifadeleri seçin.Select expressions determine which document fields are included in the result set. Bu ifadelerin sözdizimi, arama parametresinde kullanılan basit veya tam sorgu sözdiziminden farklıdır, ancak başvuru alanlarına yönelik sözdiziminde bir çakışma olabilir.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.

Bu makalede, filtrelerde, sıralamada ve Select ifadelerinde kullanılan OData ifade diline ilişkin bir genel bakış sunulmaktadır.This article provides an overview of the OData expression language used in filters, order-by, and select expressions. Dil, en temel öğelerle başlayarak ve üzerinde oluşturma için "aşağıdan yukarıya" sunulmuştur.The language is presented "bottom-up", starting with the most basic elements and building on them. Her parametre için en üst düzey sözdizimi ayrı bir makalede açıklanmıştır:The top-level syntax for each parameter is described in a separate article:

OData ifadeleri basit ve çok karmaşık olarak değişir, ancak bunların hepsi ortak öğeleri paylaşır.OData expressions range from simple to highly complex, but they all share common elements. Azure Bilişsel Arama 'de bir OData ifadesinin en temel kısımları şunlardır:The most basic parts of an OData expression in Azure Cognitive Search are:

  • Dizininizdeki belirli alanlara başvuran alan yolları.Field paths, which refer to specific fields of your index.
  • Belirli bir veri türünün değişmez değeri olan sabitler.Constants, which are literal values of a certain data type.

Not

Azure Bilişsel Arama terminoloji, OData standbundan birkaç yolla farklıdır.Terminology in Azure Cognitive Search differs from the OData standard in a few ways. Azure Bilişsel Arama bir alanı çağırdığımız OData içinde özellik olarak adlandırılır ve benzer şekilde alan yolu ve özellik yoluiçin.What we call a field in Azure Cognitive Search is called a property in OData, and similarly for field path versus property path. Azure Bilişsel Arama 'de belge içeren bir Dizin , OData içinde varlıklarıiçeren bir varlık kümesi olarak daha genel olarak adlandırılır.An index containing documents in Azure Cognitive Search is referred to more generally in OData as an entity set containing entities. Azure Bilişsel Arama terimleri bu başvuru boyunca kullanılır.The Azure Cognitive Search terminology is used throughout this reference.

Alan yollarıField paths

Aşağıdaki EBNF (Genişletilmiş Backus-Naur formu) alan yollarının dilbilgisini tanımlar.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]*

Etkileşimli bir sözdizimi diyagramı da kullanılabilir:An interactive syntax diagram is also available:

Alan yolu, eğik çizgi ile ayrılmış bir veya daha fazla tanımlayıcıdan oluşur.A field path is composed of one or more identifiers separated by slashes. Her tanımlayıcı, ASCII harf veya alt çizgi ile başlaması gereken bir karakter dizisidir ve yalnızca ASCII harfleri, rakamları veya alt çizgileri içermelidir.Each identifier is a sequence of characters that must start with an ASCII letter or underscore, and contain only ASCII letters, digits, or underscores. Harfler büyük veya küçük harf olabilir.The letters can be upper- or lower-case.

Bir tanımlayıcı, bir alanın adına veya bir filtre içindeki bir koleksiyon ifadesinin (any ya da all) bağlamındaki bir Aralık değişkenine başvurabilir.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. Aralık değişkeni, koleksiyonun geçerli öğesini temsil eden bir döngü değişkeni gibidir.A range variable is like a loop variable that represents the current element of the collection. Karmaşık koleksiyonlar için, bu değişken, değişkenin alt alanlarına başvurmak için alan yollarını kullanmanın neden olduğu bir nesneyi temsil eder.For complex collections, that variable represents an object, which is why you can use field paths to refer to sub-fields of the variable. Bu, birçok programlama dilinde nokta gösterimine benzerdir.This is analogous to dot notation in many programming languages.

Alan yollarının örnekleri aşağıdaki tabloda gösterilmiştir:Examples of field paths are shown in the following table:

Alan yoluField path AçıklamaDescription
HotelName Dizinin en üst düzey alanını ifade ederRefers to a top-level field of the index
Address/City Dizindeki bir karmaşık alanın City alt alanına başvurur; Bu örnekte Edm.ComplexType türü AddressRefers to the City sub-field of a complex field in the index; Address is of type Edm.ComplexType in this example
Rooms/Type Dizindeki bir karmaşık koleksiyon alanının Type alt alanına başvurur; Bu örnekte Collection(Edm.ComplexType) türü RoomsRefers 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 Dizindeki bir karmaşık koleksiyon alanının Address alt alanının Country alt alanına başvurur; Stores türü Collection(Edm.ComplexType) ve Address bu örnekteki Edm.ComplexType türündedirRefers 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 room Range değişkeninin Type alt alanına, örneğin, filtre ifadesinde başvurur 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 store Range değişkeninin Address alt alanının Country alt alanına başvurur; Örneğin, filtre ifadesi 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')

Bir alan yolunun anlamı, bağlama göre farklılık gösterir.The meaning of a field path differs depending on the context. Filtrelerdeki bir alan yolu, geçerli belgedeki bir alanın tek bir örneğinin değerini ifade eder.In filters, a field path refers to the value of a single instance of a field in the current document. $OrderBy, $Selectgibi diğer bağlamlarda veya tam Lucene sözdiziminde araalanları, alan yolu alanın kendisini ifade eder.In other contexts, such as $orderby, $select, or in fielded search in the full Lucene syntax, a field path refers to the field itself. Bu fark, filtrelerdeki alan yollarını nasıl kullandığınız hakkında bazı sonuçlar içerir.This difference has some consequences for how you use field paths in filters.

Alan yolunu Address/Citygöz önünde bulundurun.Consider the field path Address/City. Filtre içinde, bu, "San Francisco" gibi geçerli belge için tek bir şehir anlamına gelir.In a filter, this refers to a single city for the current document, like "San Francisco". Buna karşılık Rooms/Type, birçok Oda için Type alt alanı anlamına gelir (ilk odadaki "standart", ikinci Oda için "Deluxe" gibi).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). Rooms/Type alt alan Typetek bir örneğine başvurmadığından, bu, doğrudan bir filtrede kullanılamaz.Since Rooms/Type doesn't refer to a single instance of the sub-field Type, it can't be used directly in a filter. Bunun yerine, Oda türünü filtrelemek için, bir Aralık değişkeni ile bir lambda ifadesi kullanırsınız, örneğin: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')

Bu örnekte, Aralık değişkeni room room/Type alan yolunda görüntülenir.In this example, the range variable room appears in the room/Type field path. Bu şekilde, room/Type geçerli belgedeki geçerli odanın türü anlamına gelir.That way, room/Type refers to the type of the current room in the current document. Bu, Type alt alanının tek bir örneğidir, bu nedenle doğrudan filtrede kullanılabilir.This is a single instance of the Type sub-field, so it can be used directly in the filter.

Alan yollarını kullanmaUsing field paths

Alan yolları Azure BILIŞSEL arama REST API'lerinin birçok parametresi için kullanılır.Field paths are used in many parameters of the Azure Cognitive Search REST APIs. Aşağıdaki tabloda, kullanılabilecekleri tüm konumlar ve kullanımları üzerinde kısıtlamalar listelenmiştir:The following table lists all the places where they can be used, plus any restrictions on their usage:

eklentisiAPI Parametre adıParameter name KısıtlamalarRestrictions
Dizin Oluştur veya GüncelleştirCreate or Update Index suggesters/sourceFields HiçbiriNone
Dizin Oluştur veya GüncelleştirCreate or Update Index scoringProfiles/text/weights Yalnızca aranabilir alanlara başvurabilirCan only refer to searchable fields
Dizin Oluştur veya GüncelleştirCreate or Update Index scoringProfiles/functions/fieldName Yalnızca filtrelenebilir alanlara başvurabilirCan only refer to filterable fields
SearchSearch queryType ne zaman search fullsearch when queryType is full Yalnızca aranabilir alanlara başvurabilirCan only refer to searchable fields
SearchSearch facet Yalnızca çok yönlü tablo alanlarına başvurabilirCan only refer to facetable fields
SearchSearch highlight Yalnızca aranabilir alanlara başvurabilirCan only refer to searchable fields
SearchSearch searchFields Yalnızca aranabilir alanlara başvurabilirCan only refer to searchable fields
Öner ve AutoCompleteSuggest and Autocomplete searchFields Yalnızca bir öneri aracı parçası olan alanlara başvurabilirCan only refer to fields that are part of a suggester
Arama, önermeve otomatik tamamlamaSearch, Suggest, and Autocomplete $filter Yalnızca filtrelenebilir alanlara başvurabilirCan only refer to filterable fields
Arama ve önermeSearch and Suggest $orderby Yalnızca sıralanabilir alanlara başvurabilirCan only refer to sortable fields
Arama, önermeve aramaSearch, Suggest, and Lookup $select Yalnızca alınabilir alanlara başvurabilirCan only refer to retrievable fields

LerdeConstants

OData içindeki sabitler, belirli bir varlık veri modeli (EDM) türünün sabit değerlerdir.Constants in OData are literal values of a given Entity Data Model (EDM) type. Azure Bilişsel Arama desteklenen türlerin listesi için bkz. desteklenen veri türleri .See Supported data types for a list of supported types in Azure Cognitive Search. Koleksiyon türü sabitleri desteklenmez.Constants of collection types aren't supported.

Aşağıdaki tabloda, Azure Bilişsel Arama tarafından desteklenen her bir veri türü için sabitler örnekleri gösterilmektedir:The following table shows examples of constants for each of the data types supported by Azure Cognitive Search:

Veri türüData type Örnek sabitlerExample 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'

Aşağıdaki EBNF (Genişletilmiş Backus-Naur formu), yukarıdaki tabloda gösterilen sabitler için dilbilgisini tanımlar.The following EBNF (Extended Backus-Naur Form) defines the grammar for most of the constants shown in the above table. Coğrafi uzamsal türler için dilbilgisi, Azure bilişsel arama 'Da OData coğrafi uzamsal işlevlerdebulunabilir.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'

Etkileşimli bir sözdizimi diyagramı da kullanılabilir:An interactive syntax diagram is also available:

Alan yollarından ve sabitlerden ifadeler oluşturmaBuilding expressions from field paths and constants

Alan yolları ve sabitler, bir OData ifadesinin en temel kısmıdır, ancak bunlar zaten tam ifadelerdir.Field paths and constants are the most basic part of an OData expression, but they're already full expressions themselves. Aslında, Azure Bilişsel Arama $Select parametresi Nothing, ancak alan yollarının virgülle ayrılmış bir listesidir ve $OrderBy $Selectkıyasla daha karmaşık değildir.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. Dizininizdeki Edm.Boolean türünde bir alanınız varsa, bu alanın yolu ancak hiçbir şey olmayan bir filtre de yazabilirsiniz.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. true ve false sabitleri aynı şekilde geçerli filtrelerdir.The constants true and false are likewise valid filters.

Ancak, çoğu zaman birden fazla alana ve sabitine başvuran daha karmaşık deyimler gerekecektir.However, most of the time you'll need more complex expressions that refer to more than one field and constant. Bu ifadeler parametreye bağlı olarak farklı şekillerde oluşturulmuştur.These expressions are built in different ways depending on the parameter.

Aşağıdaki EBNF (Genişletilmiş Backus-Naur formu) $Filter, $OrderByve $Select parametreleri için dilbilgisini tanımlar.The following EBNF (Extended Backus-Naur Form) defines the grammar for the $filter, $orderby, and $select parameters. Bunlar alan yollarına ve sabitlere başvuran daha basit ifadelerden oluşturulmuştur: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)*

Etkileşimli bir sözdizimi diyagramı da kullanılabilir:An interactive syntax diagram is also available:

$OrderBy ve $Select parametreleri, daha basit ifadelerin virgülle ayrılmış listeleridir.The $orderby and $select parameters are both comma-separated lists of simpler expressions. $Filter parametresi, daha basit alt ifadelerden oluşan bir Boolean ifadedir.The $filter parameter is a Boolean expression that is composed of simpler sub-expressions. Bu alt ifadeler and, orve notgibi mantıksal işleçler, eq, lt, gt, vb. gibi karşılaştırma işleçleri ve any ve @no__t_10 gibi koleksiyon işleçleri kullanılarak birleştirilir _ .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.

$Filter, $OrderByve $Select parametreleri aşağıdaki makalelerde daha ayrıntılı bir şekilde araştırılabilir:The $filter, $orderby, and $select parameters are explored in more detail in the following articles:

Ayrıca bkz.See also