Přehled jazyka OData pro $filter, $orderbya $select ve službě Azure AI Vyhledávač

Tento článek poskytuje přehled jazyka výrazů OData, který se používá ve výrazech $filter, $order-by a $select pro vyhledávání klíčových slov ve službě Azure AI Vyhledávač přes číselná a řetězcová pole (nevzájemná).

Jazyk se prezentuje jako "dole nahoru" počínaje nejzásadnějšími prvky. Výrazy OData, které můžete vytvořit v požadavku dotazu, jsou jednoduché až vysoce složité, ale všechny sdílejí společné prvky. Mezi sdílené prvky patří:

• Cesty k polím, které odkazují na konkrétní pole indexu
• Konstanty, které jsou literálními hodnotami určitého datového typu.

Jakmile pochopíte tyto běžné koncepty, můžete pokračovat v syntaxi nejvyšší úrovně pro každý výraz:

• $filter výrazy se vyhodnocují během analýzy dotazů, omezují vyhledávání na konkrétní pole nebo přidávají kritéria shody použitá při prohledávání indexu.
• $orderby výrazy se aplikují jako krok post-processingového zpracování nad sadou výsledků pro seřazení vrácených dokumentů.
• $select výrazy určují, která pole dokumentu jsou zahrnuta do sady výsledků.

Syntaxe těchto výrazů se liší od jednoduché nebo úplné syntaxe dotazu použité v parametru vyhledávání, i když zde existuje určité překrytí v syntaxi pro odkazování na pole.

Příklady v jiných jazycích, jako je Python nebo C#, najdete v příkladech v úložišti azure-search-vector-samples .

Cesty k polím

Následující ebNF (Extended Backus-Naur Form) definuje gramatiku cest polí.

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

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

K dispozici je také interaktivní diagram syntaxe:

Cesta k poli se skládá z jednoho nebo více identifikátorů, které jsou odděleny lomítky. Každý identifikátor je posloupnost znaků, která musí začínat písmenem nebo podtržítkem ASCII a obsahovat pouze písmena ASCII, číslice nebo podtržítka. Písmena můžou být velká nebo malá.

Identifikátor může odkazovat buď na název pole, nebo na proměnnou rozsahu v kontextu výrazu kolekce (any nebo all) ve filtru. Proměnná pro rozsah je jako proměnná smyčky, která představuje aktuální prvek kolekce. U složitých kolekcí tato proměnná představuje objekt, což je důvod, proč můžete použít cesty polí k odkazování na podpole proměnné. Toto je analogické tečkové notaci v mnoha programovacích jazycích.

Příklady cest polí jsou uvedeny v následující tabulce:

Význam cesty pole se liší v závislosti na kontextu. V filtrech cesta k poli odkazuje na hodnotu jedné instance pole v aktuálním dokumentu. V jiných kontextech, jako jsou $orderby a $select, nebo při poli hledání (fielded search) v úplné syntaxi Lucene, odkazuje cesta pole na samotné pole. Tento rozdíl má určité důsledky pro použití cest polí ve filtrech.

Zvažte cestu pole Address/City. Ve filtru to odkazuje na jedno město pro aktuální dokument, například "San Francisco". Naproti tomu Rooms/Type odkazuje na Type dílčí pole pro mnoho místností (například "standard" pro první místnost, "deluxe" pro druhý pokoj atd.). Vzhledem k tomu Rooms/Type , že neodkazuje na jednu instanci dílčího pole Type, nelze ji použít přímo ve filtru. Místo toho byste k filtrování typu místnosti použili výraz lambda s proměnnou řady, například takto:

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

V tomto příkladu se proměnná rozsahu room objevuje v cestě room/Type pole. Tímto způsobem room/Type odkazuje na typ aktuální místnosti v aktuálním dokumentu. Toto je jedna instance dílčího Type pole, takže ji lze použít přímo ve filtru.

Použití cest k polím

Cesty k polím se používají v mnoha parametrech rozhraní REST API služby Azure AI Vyhledávač. Následující tabulka uvádí všechna místa, kde se dají použít, a všechna omezení jejich použití:

Konstanty

Konstanty v OData jsou literální hodnoty daného typu EDM (Entity Data Model). Seznam podporovaných typů ve službě Azure AI Vyhledávač najdete v tématu Podporované datové typy . Konstanty u typů kolekcí nejsou podporovány.

Následující tabulka uvádí příklady konstant pro každý nevektorový datový typ, který podporuje výrazy OData:

Odmaskování speciálních znaků v řetězcových konstantách

Řetězcové konstanty v OData jsou oddělené jednoduchými uvozovkami. Pokud potřebujete vytvořit dotaz s řetězcovou konstantou, která by sama mohla obsahovat jednoduché uvozovky, můžete vložené uvozovky escapeovat tak, že je zdvojnásobíte.

Například fráze s neformátovaným apostrofem jako "Alice's car" by byla reprezentována v OData jako řetězcová konstanta 'Alice''s car'.

Syntaxe konstant

Následující formulář EBNF (Extended Backus-Naur Form) definuje gramatiku většiny konstant zobrazených v předchozí tabulce. Gramatiku pro geoprostorové typy najdete v geoprostorových funkcích OData ve službě Azure AI Vyhledávač.

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'

K dispozici je také interaktivní diagram syntaxe:

Vytváření výrazů z cest polí a konstant

Cesty polí a konstanty jsou nejzákladnější součástí výrazu OData, ale samy o sobě jsou již úplnými výrazy. Ve skutečnosti je parametr $select ve službě Azure AI Vyhledávač pouze seznamem cest polí odděleným čárkami a $orderby není o moc složitější než $select. Pokud máte pole typu Edm.Boolean v indexu, můžete dokonce napsat filtr, který není nic jiného než cesta k tomuto poli. Konstanty true a false jsou stejně platné filtry.

Je ale častější mít komplexní výrazy, které odkazují na více než jedno pole a konstantu. Tyto výrazy jsou sestaveny různými způsoby v závislosti na parametru.

Následující formulář EBNF (Extended Backus-Naur Form) definuje gramatiku pro parametry $filter, $orderby a $select . Jsou sestavené z jednodušších výrazů, které odkazují na cesty polí a konstanty:

filter_expression ::= boolean_expression

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

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

K dispozici je také interaktivní diagram syntaxe:

Další kroky

Parametry $orderby a $select jsou seznamy jednodušších výrazů oddělené čárkami. Parametr $filter je logický výraz, který se skládá z jednodušších dílčích výrazů. Tyto dílčí výrazy jsou kombinovány pomocí logických operátorů, jako jsou and, or a not, porovnávací operátory, jako jsou , eq a lt, a operátory kolekce, jako jsou gt a .

Parametry $filter, $orderby a $select jsou podrobněji prozkoumány v následujících článcích:

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