Syntaxe $filter OData ve službě Azure AI Search
Ve službě Azure AI Search parametr $filter určuje kritéria zahrnutí nebo vyloučení pro vrácení shody ve výsledcích hledání. Tento článek popisuje syntaxi OData $filter a poskytuje příklady.
Konstrukce a konstanty cesty pole jsou popsány v přehledu jazyka OData ve službě Azure AI Search. Další informace o scénářích filtru najdete v tématu Filtry ve službě Azure AI Search.
Syntaxe
Filtr v jazyce OData je logický výraz, který může být zase jedním z několika typů výrazů, jak je znázorněno v následujícím formátu EBNF (Extended Backus-Naur Form):
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
K dispozici je také interaktivní diagram syntaxe:
Poznámka:
Úplný soubor EBNF najdete v referenčních informacích k syntaxi výrazů OData pro Azure AI Search .
Mezi typy logických výrazů patří:
- Výrazy filtru kolekce používající
anyneboall. Na pole kolekce se použijí kritéria filtru. Další informace najdete v tématu Operátory kolekce OData ve službě Azure AI Search. - Logické výrazy, které kombinují jiné logické výrazy pomocí operátorů
and,oranot. Další informace najdete v tématu Logické operátory OData ve službě Azure AI Search. - Porovnávací výrazy, které porovnávají pole nebo proměnné rozsahu s konstantními hodnotami pomocí operátorů
eq, , ,negt,lt,geale. Další informace najdete v tématu Operátory porovnání OData ve službě Azure AI Search. Porovnávací výrazy se používají také k porovnání vzdáleností mezi geograficky prostorovými souřadnicemi pomocígeo.distancefunkce. Další informace najdete v tématu OData geoprostorové funkce ve službě Azure AI Search. - Logické literály
trueafalse. Tyto konstanty můžou být užitečné někdy při programovém generování filtrů, ale jinak se v praxi nedají používat. - Volání logických funkcí, včetně:
geo.intersects, který testuje, zda daný bod je uvnitř daného mnohoúhelníku. Další informace najdete v tématu OData geoprostorové funkce ve službě Azure AI Search.search.in, která porovnává pole nebo proměnnou oblasti s každou hodnotou v seznamu hodnot. Další informace najdete v tématu Funkce ODatasearch.inve službě Azure AI Search.search.ismatchasearch.ismatchscoring, které provádějí operace fulltextového vyhledávání v kontextu filtru. Další informace najdete v tématu Funkce fulltextového vyhledávání OData ve službě Azure AI Search.
- Cesty pole nebo proměnné rozsahu typu
Edm.Boolean. Pokud má například index volanéIsEnabledlogické pole a chcete vrátit všechny dokumenty, ve kterých jetruetoto pole, může být výraz filtru pouze názvemIsEnabled. - Logické výrazy v závorkách Použití závorek může pomoct explicitně určit pořadí operací ve filtru. Další informace o výchozí prioritě operátorů OData najdete v další části.
Priorita operátorů ve filtrech
Pokud napíšete výraz filtru bez závorek kolem jeho dílčích výrazů, Azure AI Search ho vyhodnotí podle sady pravidel priority operátorů. Tato pravidla jsou založena na tom, které operátory se používají ke kombinování dílčích výrazů. Následující tabulka uvádí skupiny operátorů v pořadí od nejvyšších po nejnižší prioritu:
| Seskupit | Operátory |
|---|---|
| Logické operátory | not |
| Operátory porovnání | eq, ne, gt, lt, , gele |
| Logické operátory | and |
| Logické operátory | or |
Operátor, který je vyšší v tabulce výše, "vytvoří vazbu těsněji" s operandy než jiné operátory. Například and má vyšší prioritu než ora operátory porovnání mají vyšší prioritu než některý z nich, takže následující dva výrazy jsou ekvivalentní:
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))
Operátor not má nejvyšší prioritu všech – ještě vyšší než relační operátory. To je důvod, proč když se pokusíte napsat filtr podobný tomuto:
not Rating gt 5
Zobrazí se tato chybová zpráva:
Invalid expression: A unary operator with an incompatible type was detected. Found operand type 'Edm.Int32' for operator kind 'Not'.
K této chybě dochází, protože operátor je přidružen pouze k Rating poli, které je typu Edm.Int32, a ne s celým porovnávaným výrazem. Oprava spočívá v operandu not v závorkách:
not (Rating gt 5)
Omezení velikosti filtru
Existují omezení velikosti a složitosti výrazů filtru, které můžete odesílat do služby Azure AI Search. Omezení jsou založená přibližně na počtu klauzulí ve výrazu filtru. Dobrým vodítkem je, že pokud máte stovky klauzulí, riskujete překročení limitu. Doporučujeme navrhnout aplikaci takovým způsobem, aby negenerovala filtry nevázané velikosti.
Tip
search.in Použití funkce místo dlouhých disjunkcí porovnání rovnosti může pomoct vyhnout limitu klauzule filtru, protože volání funkce se počítá jako jedna klauzule.
Příklady
Najděte všechny hotely s alespoň jedním pokojem se základní sazbou nižší než 200 USD, které jsou hodnocené na nebo vyšších 4 pokojích:
$filter=Rooms/any(room: room/BaseRate lt 200.0) and Rating ge 4
Najděte všechny jiné hotely než "Sea View Motel", které byly renovovány od roku 2010:
$filter=HotelName ne 'Sea View Motel' and LastRenovationDate ge 2010-01-01T00:00:00Z
Najděte všechny hotely, které byly renovovány v roce 2010 nebo novějším. Literál datetime obsahuje informace o časovém pásmu pro Pacific Standard Time:
$filter=LastRenovationDate ge 2010-01-01T00:00:00-08:00
Najděte všechny hotely s parkováním a všechny pokoje jsou nekuřácké:
$filter=ParkingIncluded and Rooms/all(room: not room/SmokingAllowed)
- NEBO -
$filter=ParkingIncluded eq true and Rooms/all(room: room/SmokingAllowed eq false)
Vyhledejte všechny hotely, které jsou Luxury nebo včetně parkování, a mají hodnocení 5:
$filter=(Category eq 'Luxury' or ParkingIncluded eq true) and Rating eq 5
Najděte všechny hotely se značkou "wifi" v alespoň jedné místnosti (kde každý pokoj má značky uložené v Collection(Edm.String) poli):
$filter=Rooms/any(room: room/Tags/any(tag: tag eq 'wifi'))
Najděte všechny hotely s libovolnými pokoji:
$filter=Rooms/any()
Najděte všechny hotely, které nemají pokoje:
$filter=not Rooms/any()
Najděte všechny hotely v okruhu 10 kilometrů od daného referenčního bodu (kde Location je pole typu Edm.GeographyPoint):
$filter=geo.distance(Location, geography'POINT(-122.131577 47.678581)') le 10
Najděte všechny hotely v daném oblasti zobrazení popsané jako mnohoúhelník (kde Location je pole typu Edm.GeographyPoint). Mnohoúhelník musí být uzavřen, což znamená, že první a poslední množiny bodů musí být stejné. Body musí být také uvedeny v pořadí proti směru hodinových ručiček.
$filter=geo.intersects(Location, geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))')
Vyhledejte všechny hotely, ve kterých je pole Popis null. Pole bude mít hodnotu null, pokud nebyla nastavena, nebo pokud byla explicitně nastavena na hodnotu null:
$filter=Description eq null
Vyhledejte všechny hotely s názvem rovno 'Sea View motel' nebo 'Budget hotel'). Tyto fráze obsahují mezery a mezera je výchozím oddělovačem. Alternativní oddělovač můžete zadat v jednoduchých uvozovkách jako třetí řetězcový parametr:
$filter=search.in(HotelName, 'Sea View motel,Budget hotel', ',')
Vyhledejte všechny hotely s názvem, které se rovnají 'Sea View motel' nebo 'Budget hotel' oddělené '|'):
$filter=search.in(HotelName, 'Sea View motel|Budget hotel', '|')
Najděte všechny hotely, ve kterých mají všechny pokoje značku "wifi" nebo "tub":
$filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'wifi, tub')))
Najděte shodu u frází v kolekci, například "vytápěné ručníky" nebo "fén" ve značkách.
$filter=Rooms/any(room: room/Tags/any(tag: search.in(tag, 'heated towel racks,hairdryer included', ','))
Najděte dokumenty se slovem "waterfront". Tento filtrovací dotaz je shodný s požadavkem vyhledávání s search=waterfront.
$filter=search.ismatchscoring('waterfront')
Najděte dokumenty se slovem "hostel" a hodnocením větší nebo rovnou 4 nebo dokumenty se slovem "motel" a hodnocením rovnajícím se 5. Tento požadavek nelze vyjádřit bez search.ismatchscoring funkce, protože kombinuje fulltextové vyhledávání s operacemi filtru pomocí or.
$filter=search.ismatchscoring('hostel') and rating ge 4 or search.ismatchscoring('motel') and rating eq 5
Najděte dokumenty bez slova "luxury".
$filter=not search.ismatch('luxury')
Najděte dokumenty s frází "zobrazení oceánu" nebo hodnocením rovnajícím se 5. Dotaz search.ismatchscoring bude proveden pouze pro pole HotelName a Description. Dokumenty, které odpovídaly pouze druhé klauzuli disjunkce, se vrátí také – hotely s Rating hodnotou 5. Tyto dokumenty budou vráceny se skóre rovnajícím se nule, aby bylo jasné, že se neshodovaly s žádnou z hodnotových částí výrazu.
$filter=search.ismatchscoring('"ocean view"', 'Description,HotelName') or Rating eq 5
Najděte hotely, kde termíny "hotel" a "airport" nejsou v popisu delší než pět slov a kde jsou všechny pokoje nekuřácké. Tento dotaz používá úplný dotazovací jazyk Lucene.
$filter=search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and not Rooms/any(room: room/SmokingAllowed)
Vyhledejte dokumenty, které mají slovo začínající písmeny "lux" v poli Popis. Tento dotaz používá vyhledávání předpon v kombinaci s search.ismatch.
$filter=search.ismatch('lux*', 'Description')