Sdílet prostřednictvím

Přehled jazyka OData pro $filter, $orderbya $select ve službě Azure AI Search

  • Článek

Tento článek obsahuje přehled jazyka výrazů OData používaného v $filterpolích a $select $order-byvýrazy pro vyhledávání klíčových slov ve službě Azure AI Search přes číselná a řetězcová pole (nevector).

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 použijí jako krok následného zpracování v sadě výsledků pro řazení vrácených dokumentů.
  • $select výrazy určují, která pole dokumentu jsou zahrnuta do sady výsledků.

Syntaxetěchtoch výrazů se liší od jednoduché nebo úplné syntaxe dotazu použité v parametru vyhledávání.

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

Poznámka:

Terminologie ve službě Azure AI Search se liší od standardu OData několika způsoby. Čemu říkáme pole ve službě Azure AI Search, se v OData nazývá vlastnost a podobně pro cestu k poli a cestu k vlastnosti. Index obsahující dokumenty ve službě Azure AI Search se obecněji odkazuje v OData jako sada entit obsahující entity. Terminologie služby Azure AI Search se používá v rámci tohoto odkazu.

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:

Diagram syntaxe OData pro Azure AI Search

Poznámka:

Úplný soubor EBNF najdete v referenčních informacích k syntaxi výrazů OData pro Azure AI Search .

Cesta k poli se skládá z jednoho nebo více identifikátorů oddělených 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 (anynebo all) ve filtru. Proměnná rozsahu 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é. To je podobné zápisu v mnoha programovacích jazycích.

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

Cesta k poli Popis
HotelName Odkazuje na pole nejvyšší úrovně indexu.
Address/City Odkazuje na City dílčí pole komplexního pole v indexu; Address je typu Edm.ComplexType v tomto příkladu.
Rooms/Type Odkazuje na Type dílčí pole komplexního pole kolekce v indexu; Rooms je typu Collection(Edm.ComplexType) v tomto příkladu.
Stores/Address/Country Odkazuje na Country dílčí pole pod pole Address komplexní kolekce v indexu; Stores je typu Collection(Edm.ComplexType) a Address je typu Edm.ComplexType v tomto příkladu.
room/Type Odkazuje na Type podpole proměnné rozsahu room , například ve výrazu filtru. Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Odkazuje na Country pod pole pod pole Address store proměnné rozsahu, například ve výrazu filtru. Stores/any(store: store/Address/Country eq 'Canada')

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, $select nebo v poli hledání 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 Address/Citypole . 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 rozsahu, například takto:

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

V tomto příkladu se proměnná room rozsahu zobrazí 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 Search. Následující tabulka uvádí všechna místa, kde se dají použít, a všechna omezení jejich použití:

rozhraní API Název parametru Omezení
Vytvoření nebo aktualizace indexu suggesters/sourceFields Nic
Vytvoření nebo aktualizace indexu scoringProfiles/text/weights Může odkazovat pouze na prohledávatelná pole.
Vytvoření nebo aktualizace indexu scoringProfiles/functions/fieldName Může odkazovat pouze na filtrovatelná pole.
Vyhledat search kdy queryType je full Může odkazovat pouze na prohledávatelná pole.
Vyhledat facet Může odkazovat pouze na fasetová pole.
Vyhledat highlight Může odkazovat pouze na prohledávatelná pole.
Vyhledat searchFields Může odkazovat pouze na prohledávatelná pole.
Navrhnout a automaticky dokončovat searchFields Může odkazovat pouze na pole, která jsou součástí navrhujícího
Hledání, návrhy a automatické dokončování $filter Může odkazovat pouze na filtrovatelná pole.
Hledání a návrhy $orderby Může odkazovat pouze na řaditelná pole.
Hledání, návrhy a vyhledávání $select Může odkazovat pouze na pole s možností načtení.

Konstanty

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

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

Datový typ Ukázkové konstanty
Edm.Boolean true, false
Edm.DateTimeOffset 2019-05-06T12:30:05.451Z
Edm.Double 3.14159, -1.2e7, NaN, , INF-INF
Edm.GeographyPoint geography'POINT(-122.131577 47.678581)'
Edm.GeographyPolygon geography'POLYGON((-122.031577 47.578581, -122.031577 47.678581, -122.131577 47.678581, -122.031577 47.578581))'
Edm.Int32 123, -456
Edm.Int64 283032927235
Edm.String 'hello'

Zapouzdření 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 uvozovky uvozovky uvozovek vytvořit 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'.

Důležité

Při programovém vytváření filtrů je důležité pamatovat na řídicí řetězcové konstanty, které pocházejí ze vstupu uživatele. To je zmírnit možnost útoků prostřednictvím injektáže, zejména při použití filtrů k implementaci oříznutí zabezpečení.

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 Search.

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:

Diagram syntaxe OData pro Azure AI Search

Poznámka:

Úplný soubor EBNF najdete v referenčních informacích k syntaxi výrazů OData pro Azure AI Search .

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

Cesty polí a konstanty jsou nejzásadnější součástí výrazu OData, ale už jsou úplnými výrazy. Ve skutečnosti není parametr $select ve službě Azure AI Search nic, ale seznam cest polí oddělený čárkami a $orderby není mnohem 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:

Diagram syntaxe OData pro Azure AI Search

Poznámka:

Úplný soubor EBNF najdete v referenčních informacích k syntaxi výrazů OData pro Azure AI Search .

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 andjsou , oranot , relační operátory jako eq, gtlt, a tak dále, a operátory kolekce, jako any alla .

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