Syntaxe $filter OData ve službě Azure AI Vyhledávač

Ve službě Azure AI Vyhledávač 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 Vyhledávač. Další informace o scénářích filtru najdete v tématu Filtry ve službě Azure AI Vyhledávač.

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:

Mezi typy logických výrazů patří:

• Výrazy filtru kolekce používající any nebo all. Tato kritéria filtru se použijí na pole kolekce. Další informace najdete v tématu Operátory kolekce OData ve službě Azure AI Vyhledávač.
• Logické výrazy, které kombinují jiné logické výrazy pomocí operátorů and, or a not. Další informace najdete v tématu Logické operátory OData ve službě Azure AI Vyhledávač.
• Porovnávací výrazy, které porovnávají pole nebo proměnné rozsahu s konstantními hodnotami pomocí operátorů eq, , , negt, lt, gea le. Další informace najdete v tématu Operátory porovnání OData ve službě Azure AI Vyhledávač. Porovnávací výrazy se používají také k porovnání vzdáleností mezi geograficky prostorovými souřadnicemi pomocí geo.distance funkce. Další informace najdete v tématu OData geoprostorové funkce ve službě Azure AI Vyhledávač.
• Logické literály true a false. 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í Booleovský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 Vyhledávač.
  • search.in, která porovnává pole nebo proměnnou oblasti s každou hodnotou v seznamu hodnot. Další informace najdete v tématu Funkce OData search.in ve službě Azure AI Vyhledávač.
  • search.ismatch a search.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 Vyhledávač.
• Cesty pole a proměnné rozsahu typu Edm.Boolean. Pokud má například váš index logické pole s názvem IsEnabled a chcete vrátit všechny dokumenty, ve kterých je toto pole true, může být výrazem filtru samotný název IsEnabled.
• Booleovské 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 Vyhledávač 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:

Operátor, který má vyšší prioritu v uvedené tabulce, "pevněji se váže" ke svým operandům 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á ve vložení operandu not do závorek.

    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 Vyhledávač. 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.

Příklady

Najděte všechny hotely s alespoň jedním pokojem se základní sazbou nižší než $200, které jsou hodnocené na nebo vyšších 4 hvězdičká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é seřazeny 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', ',')

Najděte všechny hotely s názvem buď 'Sea View motel' nebo 'Budget hotel', oddělené znakem '|'.

    $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é držáky na ručníky" nebo "obsahuje 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 „pobřeží“. Tento filtrovací dotaz je shodný s vyhledávacím dotazemsearch=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 s hodnocením rovnajícím se nule, aby bylo jasné, že se neshodovaly s žádnou z hodnocený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')

Další kroky

• Filtry ve službě Azure AI Vyhledávač
• Přehled jazyka výrazů OData pro Azure AI Vyhledávač
• Referenční informace o syntaxi výrazů OData pro Azure AI Vyhledávač
• Prohledat dokumenty (rozhraní REST API služby Azure AI Vyhledávač)