OData $filter szintaxis az Azure AI Searchben
Az Azure AI Searchben a $filter paraméter az egyezések keresési eredményekben való visszaadására vonatkozó befogadási vagy kizárási feltételeket határozza meg. Ez a cikk a $filter OData szintaxisát ismerteti, és példákat tartalmaz.
A mezőút felépítését és állandóit az Azure AI Search OData nyelvének áttekintésében ismertetjük. A szűrési forgatókönyvekről további információt az Azure AI Search szűrők című témakörében talál.
Syntax
Az OData nyelv szűrője egy logikai kifejezés, amely több típusú kifejezés egyike lehet, ahogyan az alábbi EBNF (Extended Backus-Naur form) is mutatja:
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
Interaktív szintaxisdiagram is elérhető:
Feljegyzés
A teljes EBNF-hez tekintse meg az Azure AI Search OData-kifejezésszintaxis-hivatkozását.
A logikai kifejezések típusai a következők:
- Gyűjteményszűrési kifejezések használata
anyvagyall. Ezek szűrőfeltételeket alkalmaznak a gyűjteménymezőkre. További információ: OData-gyűjtemény operátorok az Azure AI Searchben. - Logikai kifejezések, amelyek más logikai kifejezéseket kombinálnak az operátorok
andésornota . További információ: OData logikai operátorok az Azure AI Searchben. - Összehasonlító kifejezések, amelyek a mezőket vagy tartományváltozókat az állandó értékekkel hasonlítják össze az operátorok
eq,ne,gt, ,ltgeésle. További információ: OData összehasonlító operátorok az Azure AI Searchben. Az összehasonlító kifejezések a geo-térbeli koordináták közötti távolságok összehasonlítására is használhatók ageo.distancefüggvény használatával. További információ: OData geo-térbeli függvények az Azure AI Searchben. - A logikai literálok és
falseatrue. Ezek az állandók néha hasznosak lehetnek, ha programozott módon hoznak létre szűrőket, de máskülönben nem használják a gyakorlatban. - Logikai függvények hívása, beleértve a következőket:
geo.intersects, amely azt vizsgálja, hogy egy adott pont egy adott sokszögön belül van-e. További információ: OData geo-térbeli függvények az Azure AI Searchben.search.in, amely egy mező- vagy tartományváltozót hasonlít össze az értékek listájának minden értékével. További információ: ODatasearch.infüggvény az Azure AI Searchben.search.ismatchéssearch.ismatchscoring, amelyek teljes szöveges keresési műveleteket hajtanak végre egy szűrőkörnyezetben. További információ: OData teljes szöveges keresési függvények az Azure AI Searchben.
- Mezőútvonalak vagy típusú tartományváltozók
Edm.Boolean. Ha például az indexben logikai mező van meghívvaIsEnabled, és minden olyan dokumentumot vissza szeretne adni, ahol ez a mező szerepeltrue, akkor a szűrőkifejezés csak a névIsEnabledlehet. - Logikai kifejezések zárójelben. A zárójelek használatával explicit módon meghatározhatja a szűrők műveleteinek sorrendjét. Az OData-operátorok alapértelmezett elsőbbségével kapcsolatos további információkért lásd a következő szakaszt.
Operátorok elsőbbsége a szűrőkben
Ha zárójelek nélkül ír egy szűrőkifejezést az alkifejezései köré, az Azure AI Search az operátorok elsőbbséget élvező szabályai szerint értékeli ki. Ezek a szabályok azon alapulnak, hogy mely operátorok használhatók az alkifejezések kombinálására. Az alábbi táblázat az operátorok csoportjait sorolja fel a legmagasabbtól a legalacsonyabbig tartó sorrendben:
| Csoport | Operátor(ok) |
|---|---|
| Logikai operátorok | not |
| Összehasonlító operátorok | eq, ne, gt, ltgele |
| Logikai operátorok | and |
| Logikai operátorok | or |
A fenti táblázatban magasabb operátorok "szorosabban kötődnek" az operandusokhoz, mint más operátorok. Az összehasonlítási operátorok például and nagyobb előnkkel járnak, mint orbármelyikük, ezért a következő két kifejezés egyenértékű:
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))
Az not operátor az összes közül a legmagasabb prioritást élvezi – még magasabb, mint az összehasonlító operátorok. Ezért, ha a következőhöz hasonló szűrőt próbál meg írni:
not Rating gt 5
A következő hibaüzenet jelenik meg:
Invalid expression: A unary operator with an incompatible type was detected. Found operand type 'Edm.Int32' for operator kind 'Not'.
Ez a hiba azért fordul elő, mert az operátor csak a Rating mezőhöz van társítva, amely típus Edm.Int32, és nem a teljes összehasonlító kifejezéshez. A javítás az operandus not zárójelbe helyezését ismerteti:
not (Rating gt 5)
Szűrőméret korlátozásai
Az Azure AI Searchbe küldhető szűrőkifejezések mérete és összetettsége korlátozott. A korlátok nagyjából a szűrőkifejezés záradékainak számán alapulnak. Jó iránymutatás, hogy ha több száz záradékot, akkor fennáll a veszélye, hogy túllépi a korlátot. Javasoljuk, hogy úgy tervezzen meg egy alkalmazást, hogy ne hozzon létre kötetlen méretű szűrőket.
Tipp.
Az egyenlőségi összehasonlítások hosszú tiltása helyett a search.in függvény használata segíthet elkerülni a szűrő záradékkorlátját, mivel a függvényhívások egyetlen záradékként számítanak.
Példák
Keresse meg az összes olyan szállodát, amelynek legalább egy szobája 200 USD-nél alacsonyabb alapkamattal rendelkezik, és amelyek besorolása 4 vagy annál magasabb:
$filter=Rooms/any(room: room/BaseRate lt 200.0) and Rating ge 4
Keresse meg a 2010 óta felújított "Sea View Motel" kivételével minden szállodát:
$filter=HotelName ne 'Sea View Motel' and LastRenovationDate ge 2010-01-01T00:00:00Z
Keresse meg az összes szállodát, amelyet 2010-ben vagy később felújítottak. A datetime literál a csendes-óceáni téli idő időzónájának adatait tartalmazza:
$filter=LastRenovationDate ge 2010-01-01T00:00:00-08:00
Keresse meg az összes olyan szállodát, amely rendelkezik parkolóval, és ahol minden szoba nemdohányzó:
$filter=ParkingIncluded and Rooms/all(room: not room/SmokingAllowed)
-VAGY-
$filter=ParkingIncluded eq true and Rooms/all(room: room/SmokingAllowed eq false)
Keresse meg az összes luxus szállodát, vagy foglalja magában a parkolást, és 5-ös minősítéssel rendelkezik:
$filter=(Category eq 'Luxury' or ParkingIncluded eq true) and Rating eq 5
Keresse meg a "wifi" címkével rendelkező összes szállodát legalább egy szobában (ahol minden szoba címkéi egy Collection(Edm.String) mezőben vannak tárolva):
$filter=Rooms/any(room: room/Tags/any(tag: tag eq 'wifi'))
Keresse meg az összes szobát tartalmazó szállodát:
$filter=Rooms/any()
Keresse meg az összes olyan szállodát, amely nem rendelkezik szobákkal:
$filter=not Rooms/any()
Keresse meg az összes szállodát egy adott referenciaponttól számított 10 kilométeren belül (ahol Location egy típusmező Edm.GeographyPointtalálható):
$filter=geo.distance(Location, geography'POINT(-122.131577 47.678581)') le 10
Keresse meg az összes szállodát egy adott nézetportban, amely sokszögként van leírva (ahol Location egy Edm.GeographyPoint típusú mező található). A sokszögnek zártnak kell lennie, ami azt jelenti, hogy az első és az utolsó ponthalmaznak azonosnak kell lennie. Emellett a pontokat az óramutató járásával ellentétes sorrendben kell felsorolni.
$filter=geo.intersects(Location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')
Keresse meg az összes olyan szállodát, ahol a "Leírás" mező null értékű. A mező null értékű lesz, ha soha nem lett beállítva, vagy ha explicit módon null értékre van állítva:
$filter=Description eq null
Keresse meg az összes olyan szállodát, amelynek neve megegyezik a "Sea View motel" vagy a "Budget hotel" névvel). Ezek a kifejezések szóközöket tartalmaznak, a szóköz pedig az alapértelmezett elválasztójel. A harmadik sztringparaméterként megadhat egy alternatív elválasztójelet egyetlen idézőjelben:
$filter=search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Keresse meg az összes olyan szállodát, amelynek neve "Sea View motel" vagy "Budget hotel" (|) által elválasztva van):
$filter=search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Keresse meg az összes szállodát, ahol minden szoba rendelkezik a "wifi" vagy a "tub" címkével:
$filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))
Keressen egyezést a gyűjteményen belüli kifejezésekkel, például a címkékben található "fűtött törülközőtartókkal" vagy a "hajszárítóval együtt" kifejezésekkel.
$filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Keresse meg a "waterfront" szót tartalmazó dokumentumokat. Ez a szűrő lekérdezés megegyezik a keresési kéréssel a következővel search=waterfront: .
$filter=search.ismatchscoring('waterfront')
Keresse meg a "hostel" szót és a 4-es vagy annál nagyobb minősítésű dokumentumokat, vagy a "motel" és az 5-ös minősítésű dokumentumokat. Ez a kérés nem fejezhető ki a függvény nélkül, mivel a search.ismatchscoring teljes szöveges keresést a szűrőműveletekkel orkombinálja.
$filter=search.ismatchscoring('hostel') and rating ge 4 or search.ismatchscoring('motel') and rating eq 5
Keresse meg a "luxus" szó nélküli dokumentumokat.
$filter=not search.ismatch('luxury')
Keresse meg az "óceánnézet" vagy az 5-nek megfelelő minősítésű dokumentumokat. A search.ismatchscoring lekérdezés csak a mezőkön HotelName és Descriptiona . Azokat a dokumentumokat is visszaadjuk, amelyek csak a tiltás második záradékának megfelelőek – 5-nek Rating megfelelő szállodák. Ezek a dokumentumok nullával egyenlő pontszámmal lesznek visszaadva, így egyértelművé válik, hogy nem egyeztek meg a kifejezés egyik pontozott részével sem.
$filter=search.ismatchscoring('"ocean view"', 'Description,HotelName') or Rating eq 5
Keresse meg a hoteleket, ahol a "hotel" és a "repülőtér" kifejezés nem több, mint öt szó a leírásban, és ahol minden szoba nemdohányzó. Ez a lekérdezés a teljes Lucene lekérdezési nyelvet használja.
$filter=search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and not Rooms/any(room: room/SmokingAllowed)
Keresse meg a Leírás mezőben a "lux" betűvel kezdődő szavakat tartalmazó dokumentumokat. Ez a lekérdezés az előtagkeresést és search.ismatcha .
$filter=search.ismatch('lux*', 'Description')