Azure AI Search'te OData $filter söz dizimi

Azure AI Search'te $filter parametresi, arama sonuçlarında eşleşmeleri döndürmek için ekleme veya dışlama ölçütlerini belirtir. Bu makalede, $filter OData söz dizimi açıklanır ve örnekler sağlanır.

Alan yolu oluşturma ve sabitler, Azure AI Search'teki OData diline genel bakış bölümünde açıklanmıştır. Filtre senaryoları hakkında daha fazla bilgi için bkz . Azure AI Search'te filtreler.

Sözdizimi

OData dilindeki bir filtre, aşağıdaki EBNF (Genişletilmiş Backus-Naur Formu) tarafından gösterildiği gibi çeşitli ifade türlerinden biri olabilecek bir Boole ifadesidir:

boolean_expression ::=
    collection_filter_expression
    | logical_expression
    | comparison_expression
    | boolean_literal
    | boolean_function_call
    | '(' boolean_expression ')'
    | variable

/* This can be a range variable in the case of a lambda, or a field path. */
variable ::= identifier | field_path

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

Boole ifadelerinin türleri şunlardır:

• veya allkullanarak any koleksiyon filtresi ifadeleri. Bunlar koleksiyon alanlarına filtre ölçütleri uygular. Daha fazla bilgi için bkz . Azure AI Search'te OData koleksiyon işleçleri.
• , orve notişleçlerini andkullanarak diğer Boole ifadelerini birleştiren mantıksal ifadeler. Daha fazla bilgi için bkz . Azure AI Search'te OData mantıksal işleçleri.
• , ve işleçlerini kullanarak alanları veya aralık değişkenlerini sabit değerlerle karşılaştıran karşılaştırma ifadelerieqgenegtlt.le Daha fazla bilgi için bkz . Azure AI Search'te OData karşılaştırma işleçleri. Karşılaştırma ifadeleri, işlevini kullanarak geo.distance jeo-uzamsal koordinatlar arasındaki mesafeleri karşılaştırmak için de kullanılır. Daha fazla bilgi için bkz . Azure AI Search'te OData coğrafi uzamsal işlevleri.
• Boole değişmez değerleri true ve false. Bu sabitler bazen program aracılığıyla filtre oluştururken yararlı olabilir, ancak aksi takdirde uygulamada kullanılma eğilimindedir.
• Aşağıdakiler dahil olmak üzere Boole işlevlerine çağrılar:
  • geo.intersects, belirli bir noktanın belirli bir çokgen içinde olup olmadığını sınar. Daha fazla bilgi için bkz . Azure AI Search'te OData coğrafi uzamsal işlevleri.
  • search.in, bir alan veya aralık değişkenini bir değer listesindeki her değerle karşılaştırır. Daha fazla bilgi için bkz. Azure AI Search'te OData search.in işlevi.
  • search.ismatch ve search.ismatchscoringfiltre bağlamında tam metin arama işlemlerini yürütür. Daha fazla bilgi için bkz . Azure AI Search'te OData tam metin arama işlevleri.
• alan yolları veya türünde Edm.Booleanaralık değişkenleri. Örneğin, dizininizde adlı IsEnabled bir Boole alanı varsa ve bu alanın truebulunduğu tüm belgeleri döndürmek istiyorsanız, filtre ifadeniz yalnızca adı IsEnabledolabilir.
• Parantez içinde Boole ifadeleri. Parantezlerin kullanılması, filtredeki işlemlerin sırasını açıkça belirlemeye yardımcı olabilir. OData işleçlerinin varsayılan önceliği hakkında daha fazla bilgi için sonraki bölüme bakın.

Filtrelerde işleç önceliği

Alt ifadelerine parantez içermeyen bir filtre ifadesi yazarsanız, Azure AI Search bunu bir dizi işleç önceliği kuralına göre değerlendirir. Bu kurallar, alt ifadeleri birleştirmek için kullanılan işleçleri temel alır. Aşağıdaki tabloda işleç grupları en yüksekten en düşük önceliğe sırasıyla listelenmiştir:

Yukarıdaki tabloda daha yüksek olan bir işleç, işlenenlerine diğer işleçlere göre "daha sıkı bağlanır". Örneğin, and değerinden daha yüksek önceliklidir orve karşılaştırma işleçleri bunlardan herhangi birinden daha yüksek önceliklidir, bu nedenle aşağıdaki iki ifade eşdeğerdir:

    Rating gt 0 and Rating lt 3 or Rating gt 7 and Rating lt 10
    ((Rating gt 0) and (Rating lt 3)) or ((Rating gt 7) and (Rating lt 10))

işleç not , karşılaştırma işleçlerinden bile daha yüksek olan en yüksek önceliğe sahiptir. Bu nedenle, aşağıdaki gibi bir filtre yazmaya çalışırsanız:

    not Rating gt 5

Şu hata iletisini alırsınız:

    Invalid expression: A unary operator with an incompatible type was detected. Found operand type 'Edm.Int32' for operator kind 'Not'.

Bu hatanın nedeni işlecinin karşılaştırma ifadesinin Rating tamamıyla değil türünde olan Edm.Int32alanla ilişkilendirildiğidir. Düzeltme, işlenenini not parantez içine almaktır:

    not (Rating gt 5)

Filtre boyutu sınırlamaları

Azure AI Search'e gönderebileceğiniz filtre ifadelerinin boyutu ve karmaşıklığıyla ilgili sınırlar vardır. Sınırlar kabaca filtre ifadenizdeki yan tümce sayısına bağlıdır. İyi bir kılavuz, yüzlerce yan tümceniz varsa sınırı aşma riskiniz olmasıdır. Uygulamanızı, ilişkisiz boyutta filtreler oluşturmeyecek şekilde tasarlamanızı öneririz.

Örnekler

Taban fiyatı 200 TL'den az olan ve 4'ten yüksek olan en az bir odalı tüm otelleri bulun:

    $filter=Rooms/any(room: room/BaseRate lt 200.0) and Rating ge 4

2010 yılından beri yenilenen "Sea View Motel" dışındaki tüm otelleri bulun:

    $filter=HotelName ne 'Sea View Motel' and LastRenovationDate ge 2010-01-01T00:00:00Z

2010 veya sonraki bir tarihte yenilenen tüm otelleri bulun. Tarih saat değişmez değeri, Pasifik Standart Saati için saat dilimi bilgilerini içerir:

    $filter=LastRenovationDate ge 2010-01-01T00:00:00-08:00

Park yeri bulunan ve tüm odalarda sigara içilmeyen tüm otelleri bulun:

    $filter=ParkingIncluded and Rooms/all(room: not room/SmokingAllowed)

- VEYA -

    $filter=ParkingIncluded eq true and Rooms/all(room: room/SmokingAllowed eq false)

Lüks olan veya otopark içeren ve 5 derecelendirmesine sahip tüm otelleri bulun:

    $filter=(Category eq 'Luxury' or ParkingIncluded eq true) and Rating eq 5

En az bir odada "wifi" etiketine sahip tüm otelleri bulun (her odada bir Collection(Edm.String) alanda depolanan etiketler bulunur):

    $filter=Rooms/any(room: room/Tags/any(tag: tag eq 'wifi'))

Herhangi bir oda içeren tüm otelleri bulun:

    $filter=Rooms/any()

Odası olmayan tüm otelleri bulun:

    $filter=not Rooms/any()

Belirli bir referans noktasına 10 kilometre mesafedeki tüm otelleri bulun (burada Location bir tür Edm.GeographyPointalanıdır):

    $filter=geo.distance(Location, geography'POINT(-122.131577 47.678581)') le 10

Çokgen olarak tanımlanan belirli bir görünüm penceresindeki tüm otelleri bulun (burada Location Edm.GeographyPoint türünde bir alandır). Çokgen kapatılmalıdır, yani ilk ve son nokta kümeleri aynı olmalıdır. Ayrıca, noktaların saat yönünün tersine sıralanması gerekir.

    $filter=geo.intersects(Location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')

"Description" alanının null olduğu tüm otelleri bulun. Alan hiçbir zaman ayarlanmadıysa veya açıkça null olarak ayarlandıysa null olur:

    $filter=Description eq null

Adı 'Sea View motel' veya 'Budget hotel' olan tüm otelleri bulun. Bu ifadeler boşluk içerir ve boşluk varsayılan sınırlayıcıdır. Üçüncü dize parametresi olarak tek tırnak içinde alternatif sınırlayıcı belirtebilirsiniz:

    $filter=search.in(HotelName, 'Sea View motel,Budget hotel', ',')

Adı 'Sea View motel' veya 'Budget hotel' olan ve '|' ile ayrılmış tüm otelleri bulun:

    $filter=search.in(HotelName, 'Sea View motel|Budget hotel', '|')

Tüm odaların 'wifi' veya 'tub' etiketine sahip olduğu tüm otelleri bulun:

    $filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))

Etiketlerde 'ısıtmalı havlu rafları' veya 'saç kurutma makinesi dahil' gibi koleksiyon içindeki tümceciklerde eşleşme bulun.

    $filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))

"Waterfront" sözcüğünü içeren belgeleri bulun. Bu filtre sorgusu ile bir arama isteği aynıdır search=waterfront.

    $filter=search.ismatchscoring('waterfront')

"Hostel" sözcüğü ve derecelendirmesi 4'e eşit veya daha büyük olan belgeleri veya "motel" sözcüğü ve derecelendirme değeri 5'e eşit olan belgeleri bulun. Kullanarak filtre işlemleriyle ortam metin aramasını search.ismatchscoring birleştirdiğinden bu istek işlevi olmadan ifade edilemedi.

    $filter=search.ismatchscoring('hostel') and rating ge 4 or search.ismatchscoring('motel') and rating eq 5

"Lüks" sözcüğü olmadan belgeleri bulun.

    $filter=not search.ismatch('luxury')

"Okyanus görünümü" veya derecelendirme değeri 5'e eşit olan belgeleri bulun. Sorgu search.ismatchscoring yalnızca ve Descriptionalanlarına HotelName göre yürütülür. Ayrıştırma işleminin yalnızca ikinci yan tümcesiyle eşleşen belgeler de döndürülür; 5'e eşit oteller Rating . Bu belgeler sıfıra eşit puanla döndürülür ve ifadenin puanlanan bölümlerinin hiçbiriyle eşleşmediğini açıkça gösterir.

    $filter=search.ismatchscoring('"ocean view"', 'Description,HotelName') or Rating eq 5

Açıklamada "otel" ve "havaalanı" terimlerinin beş sözcükten fazla olmadığı ve tüm odalarda sigara içilmeyen otelleri bulun. Bu sorgu tam Lucene sorgu dilini kullanır.

    $filter=search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and not Rooms/any(room: room/SmokingAllowed)

Açıklama alanında "lüks" harfleriyle başlayan sözcük içeren belgeleri bulun. Bu sorgu ile search.ismatchbirlikte ön ek araması kullanır.

    $filter=search.ismatch('lux*', 'Description')

Sonraki adımlar

• Azure AI Arama'daki filtreler
• Azure AI Search için OData ifade diline genel bakış
• Azure AI Search için OData ifade söz dizimi başvurusu
• Belgeleri Ara (Azure AI Arama REST API'si)