Přehled jazyka OData pro $filter, $orderbya $select ve službě Azure AI Search
Tento článek obsahuje přehled jazyka výrazů OData používaného v $filter, $order-by a výrazech $select ve službě Azure AI Search. 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í.
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:
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ýrazukolekce (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 Addressstore 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í:
| 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. |
| Search | search kdy queryType je full |
Může odkazovat pouze na prohledávatelná pole. |
| Search | facet |
Může odkazovat pouze na fasetová pole. |
| Search | highlight |
Může odkazovat pouze na prohledávatelná pole. |
| Search | 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ý z datových typů podporovaných službou Azure AI Search:
| 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:
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.
Ve většině případů ale budete potřebovat složitější 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:
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 anyalla .
Parametry $filter, $orderby a $select jsou podrobněji prozkoumány v následujících článcích: