Azure Yapay Zeka Arama'te $filter, $orderby ve $select için OData diline genel bakış

Bu makale, Azure Yapay Zeka Arama'te sayısal ve metin (vektör olmayan) alanlar üzerinden anahtar sözcük araması için $filter, $order-by ve $select ifadelerinde kullanılan OData ifade diline genel bir bakış sağlar.

Dil, en temel öğelerden başlayarak "aşağıdan yukarıya" sunulur. Sorgu isteğinde oluşturabileceğiniz OData ifadeleri basitten yüksek karmaşıklığa kadar değişir, ancak bunların tümü ortak öğeleri paylaşır. Paylaşılan öğeler şunlardır:

  • Dizininizin belirli alanlarına atıfta bulunan alan yolları.
  • Sabitler, belirli bir veri türünün değişmez değerleridir.

Bu yaygın kavramları anladıktan sonra, her ifade için en üst düzey söz dizimiyle devam edebilirsiniz:

  • $filter ifadeleri sorgu ayrıştırma, aramayı belirli alanlarla sınırlama veya dizin taramaları sırasında kullanılan eşleşme ölçütleri ekleme sırasında değerlendirilir.
  • $orderby ifadeler, döndürülen belgeleri sıralamak için bir sonuç kümesi üzerinde işlem sonrası adım olarak uygulanır.
  • $select ifadeleri, sonuç kümesine hangi belge alanlarının dahil olduğunu belirler.

Bu ifadelerin söz dizimi, arama parametresinde kullanılan basit veya tam sorgu söz diziminden farklıdır, ancak başvuru alanları için söz diziminde bazı çakışmalar vardır.

Python veya C# gibi diğer dillerdeki örnekler için azure-search-vector-samples deposundaki örneklere bakın.

Not

Azure Yapay Zeka Arama'teki terminoloji, OData standardından birkaç şekilde farklıdır. Azure Yapay Zeka Arama'te alan olarak adlandırdığımız bir şey, OData'da özellik olarak adlandırılır ve aynı şekilde alan yolu özellik yolu için de geçerlidir. Azure Yapay Zeka Arama'te belgeler içeren bir dizin, OData'da varlıklar içeren bir varlık kümesi olarak daha genel olarak adlandırılır. Bu başvuru boyunca Azure AI Arama terminolojisi kullanılır.

Alan yolları

Aşağıdaki EBNF (Genişletilmiş Backus-Naur Formu), alan yollarının dil bilgisini tanımlar.

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

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

Etkileşimli söz dizimi diyagramı da kullanılabilir:

Azure Yapay Zeka Arama için OData söz dizimi diyagramı

Not

Tam EBNF için Azure Yapay Zeka Arama için OData ifade söz dizimi başvurusu kısmına bakın.

Dizin yolu, eğik çizgilerle ayrılmış bir veya daha fazla tanımlayıcıdan oluşur. Her tanımlayıcı, ASCII harfi veya alt çizgiyle başlaması gereken ve yalnızca ASCII harfleri, basamakları veya alt çizgilerini içeren bir karakter dizisidir. Harfler büyük veya küçük olabilir.

Tanımlayıcı, bir alanın adı veya bir filtredeki koleksiyon ifadesi ( veya any) bağlamında bir all anlamına gelebilir. Aralık değişkeni, koleksiyonun geçerli öğesini temsil eden bir döngü değişkeni gibidir. Karmaşık koleksiyonlar için bu değişken bir nesneyi temsil eder ve bu nedenle değişkenin alt alanlarına başvurmak için alan yollarını kullanabilirsiniz. Bu, birçok programlama dilinde nokta gösterimine benzer.

Alan yolu örnekleri aşağıdaki tabloda gösterilmiştir:

Alan yolu Açıklama
HotelName Dizinin üst düzey alanına başvurur
Address/City Dizindeki City karmaşık bir alanın alt alanını ifade eder; Address bu örnekteki türdür Edm.ComplexType
Rooms/Type Dizindeki Type karmaşık bir koleksiyon alanının alt alanını ifade eder; Rooms bu örnekteki türdür Collection(Edm.ComplexType)
Stores/Address/Country Dizindeki karmaşık bir koleksiyon alanının Country alt alanının Address alt alanını ifade eder; bu örnekte Stores türü Collection(Edm.ComplexType) ve Address türü Edm.ComplexType şeklindedir.
room/Type Aralık değişkeninin Typeroom alt alanına başvurur, örneğin filtre ifadesinde Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Country aralık değişkeninin Address alt alanındaki store alt alanına atıfta bulunur, örneğin filtre ifadesinde Stores/any(store: store/Address/Country eq 'Canada').

Alan yolunun anlamı bağlama bağlı olarak değişir. Filtrelerde, alan yolu geçerli belgedeki bir alanın tek bir örneğinin değerine başvurur. $orderby, $select gibi diğer bağlamlarda veya tam Lucene söz dizimindeki alanlı aramada, bir alan yolu alanın kendisine atıfta bulunur. Bu farkın, filtrelerde alan yollarını nasıl kullandığınıza ilişkin bazı sonuçları vardır.

alan yolunu Address/Citygöz önünde bulundurun. Filtrede bu, geçerli belge için "San Francisco" gibi tek bir şehir anlamına gelir. Buna karşılık, Rooms/Type birçok odanın alt alanını ifade eder Type (birinci oda için "standart", ikinci oda için "deluxe" vb.). Rooms/Type bir alt alanın tek bir örneği ne başvurmadığından, doğrudan bir filtrede kullanılamaz. Bunun yerine, oda türüne göre filtrelemek için aşağıdaki gibi bir aralık değişkenine sahip bir lambda ifadesi kullanırsınız:

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

Bu örnekte, aralık değişkeni room alan yolunda görüntülenir room/Type . Bu sayede, room/Type geçerli belgedeki mevcut odanın türüne başvurur. Bu alt alanı tek bir örneğidir Type , bu nedenle doğrudan filtrede kullanılabilir.

Alan yollarını kullanma

Alan yolları, Azure Yapay Zeka Arama REST API'lerinin birçok parametresinde kullanılır. Aşağıdaki tabloda, kullanabilecekleri tüm yerler ve kullanımlarıyla ilgili kısıtlamalar listelenecektir:

Uygulama Programlama Arayüzü (API) Parametre adı Kısıtlamalar
Dizin Oluşturma veya Güncelleştirme suggesters/sourceFields Hiçbiri
Dizin Oluşturma veya Güncelleştirme scoringProfiles/text/weights Yalnızca aranabilir alanlara başvurabilir
Dizin Oluşturma veya Güncelleştirme scoringProfiles/functions/fieldName Yalnızca filtrelenebilir alanlara başvurabilir
Arama yap search ne queryTypefull Yalnızca aranabilir alanlara başvurabilir
Arama yap facet Yalnızca yüzlenebilir alanlara başvurabilir
Arama yap highlight Yalnızca aranabilir alanlara başvurabilir
Arama yap searchFields Yalnızca aranabilir alanlara başvurabilir
Öneri veOtomatik Tamamlama searchFields Yalnızca bir öneri oluşturucunun parçası olan alanlara başvurabilir
Arama, Öneri ve Otomatik Tamamlama $filter Yalnızca filtrelenebilir alanlara başvurabilir
Arama ve Önerme $orderby Yalnızca sıralanabilir alanlara başvurabilir
Arama, Öneri ve Arama $select Yalnızca erişilebilir alanlara başvurabilir.

Sabitler

OData'daki sabitler, belirli bir Varlık Veri Modeli (EDM) türünün değişmez değerleridir. Azure Yapay Zeka Arama'te desteklenen türlerin listesi için bkz . Desteklenen veri türleri . Koleksiyon türlerinin sabitleri desteklenmez.

Aşağıdaki tabloda, OData ifadelerini destekleyen her bir seçici olmayan veri türü için sabit örnekleri gösterilmektedir:

Veri türü Örnek sabitler
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'

Dize sabitlerindeki özel karakterlerden kaçış

OData'daki dize sabitleri tek tırnak işaretleri ile sınırlandırılır. Tek tırnak işareti içerebilen bir dize sabiti içeren bir sorgu oluşturmanız gerekiyorsa, katıştırılmış tırnakları ikiye katlayarak kaçabilirsiniz.

Örneğin, "Alice'in arabası" gibi biçimlendirilmemiş kesme işaretine sahip bir tümcecik, OData'da dize sabiti 'Alice''s car'olarak temsil edilir.

Önemli

Filtreleri program aracılığıyla oluştururken, kullanıcı girişinden gelen dize sabitlerinden kaçışı anımsamak önemlidir. Bu, özellikle ekleme saldırısı olasılığını azaltmak için güvenlik kırpması uygularken filtreleri kullanırken içindir.

Sabitler söz dizimi

Aşağıdaki EBNF (Genişletilmiş Backus-Naur Formu), yukarıdaki tabloda gösterilen sabitlerin çoğu için dil bilgisini tanımlar. Coğrafi uzamsal türler için dil bilgisi, Azure Yapay Zeka Arama'teki OData coğrafi uzamsal işlevlerinde bulunabilir.

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 söz dizimi diyagramı da kullanılabilir:

Azure Yapay Zeka Arama için OData söz dizimi diyagramı

Not

Tam EBNF için Azure Yapay Zeka Arama için OData ifade söz dizimi başvurusu kısmına bakın.

Alan yollarından ve sabitlerden ifade oluşturma

Alan yolları ve sabitleri, OData ifadesinin en temel parçasıdır, ancak bunlar zaten tam ifadelerdir. Aslında Azure Yapay Zeka Arama'teki $select parametresi, alan yollarının virgülle ayrılmış bir listesinden başka bir şey değildir ve $orderby $select kadar karmaşık değildir. Dizininizde türünde Edm.Boolean bir alan varsa, o alanın yolundan başka bir şey olmayan bir filtre bile yazabilirsiniz. sabitleri true ve false benzer şekilde geçerli filtrelerdir.

Ancak, birden çok alana ve sabite başvuran karmaşık ifadelerin olması daha yaygındır. Bu ifadeler, parametresine bağlı olarak farklı şekillerde oluşturulur.

Aşağıdaki EBNF (Genişletilmiş Backus-Naur Formu), $filter, $orderby ve $select parametreleri için dil bilgisini tanımlar. Bunlar, alan yollarına ve sabitlerine başvuran daha basit ifadelerden oluşturulur:

filter_expression ::= boolean_expression

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

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

Etkileşimli söz dizimi diyagramı da kullanılabilir:

Azure Yapay Zeka Arama için OData söz dizimi diyagramı

Not

Tam EBNF için Azure Yapay Zeka Arama için OData ifade söz dizimi başvurusu kısmına bakın.

Sonraki adımlar

$orderby ve $select parametreleri, daha basit ifadelerin virgülle ayrılmış listeleridir. $filter parametresi, daha basit alt ifadelerden oluşan bir Boole ifadesidir. Bu alt ifadeler, , ve gibi mantıksal işleçler, , , vb. gibi karşılaştırma işleçleri ve ve gibi koleksiyon işleçleri kullanılarak birleştirilir.

$filter, $orderby ve $select parametreleri aşağıdaki makalelerde daha ayrıntılı olarak incelenir:

  • Last updated on