Az OData nyelvének áttekintése az $filter, $orderby és $select elemekhez az Azure AI Keresésben

Ez a cikk áttekintést nyújt az OData-kifejezésnyelvről, amelyet az Azure AI Keresésben a kulcsszókereséshez használnak a numerikus és sztringes (nem vektor) mezőknél $filter, $order-by, és $select kifejezésekben.

A nyelv "alulról felfelé" jelenik meg, kezdve a legalapvetőbb elemekkel. A lekérdezéskérelemben létrehozható OData-kifejezések az egyszerűtől a rendkívül összetettig terjednek, de mindegyik közös elemeket használ. A megosztott elemek a következők:

• Mezőútvonalak, amelyek az index adott mezőire vonatkoznak.
• Konstansok, amelyek egy adott adattípus konstans értékei.

Miután megismerte ezeket a gyakori fogalmakat, folytathatja az egyes kifejezések legfelső szintű szintaxisát:

• $filter kifejezések kiértékelése a lekérdezéselemzés során, a keresés adott mezőkre való korlátozása vagy az indexvizsgálatok során használt egyezési feltételek hozzáadása.
• $orderby kifejezések utófeldolgozási lépésként kerülnek alkalmazásra egy eredménykészleten a visszaadott dokumentumok rendezéséhez.
• $select kifejezések határozzák meg, hogy mely dokumentummezők szerepelnek az eredményhalmazban.

Ezeknek a kifejezéseknek a szintaxisa eltér a keresési paraméterben használt egyszerű vagy teljes lekérdezési szintaxistól, bár a hivatkozási mezők szintaxisa átfedésben van.

Más nyelveken, például a Pythonban vagy a C#-ban is találhat példákat az azure-search-vector-samples adattárban.

Mezőútvonalak

A mezőútvonalak nyelvtanát az alábbi EBNF (Extended Backus-Naur form) határozza meg.

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

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

Interaktív szintaxisdiagram is elérhető:

A mezőútvonalak egy vagy több , perjelekkel elválasztott azonosítóból állnak. Minden azonosító olyan karaktersorozat, amelynek ASCII betűvel vagy aláhúzásjellel kell kezdődnie, és csak ASCII-betűket, számjegyeket vagy aláhúzásjeleket tartalmaz. A betűk lehetnek nagybetűsek vagy kisbetűk.

Az azonosítók hivatkozhatnak egy mező nevére, vagy egy tartományváltozóra a szűrőben lévő gyűjteménykifejezés (any vagy all) kontextusában. A tartományváltozó olyan, mint egy hurokváltozó, amely a gyűjtemény aktuális elemét jelöli. Összetett gyűjtemények esetén ez a változó egy objektumot jelöl, ezért mezőútvonalak használatával hivatkozhat a változó almezőire. Ez sok programozási nyelv pontjegyzetéhez hasonló.

Példák a mezőútvonalakra az alábbi táblázatban:

A mezőútvonal jelentése a környezettől függően eltérő. A szűrőkben a mező elérési útja az aktuális dokumentumban lévő mező egyetlen példányának értékét jelenti. Más környezetekben, például $orderby, $select, vagy a teljes Lucene szintaxisban lévő mezős keresésben a mező elérési útja magára a mezőre utal. Ez a különbség bizonyos következményekkel jár arra nézve, hogy miként használja a mezőútvonalakat a szűrőkben.

Vegye figyelembe a mező útvonalát Address/City. A szűrőben ez az aktuális dokumentum egyetlen városára vonatkozik, például a "San Francisco"-ra. Ezzel szemben a Rooms/Type a Type almezőre hivatkozik számos szoba esetében (például "standard" az első szobára, "deluxe" a második szobára, és így tovább). Mivel Rooms/Type nem hivatkozik az almező egyedüli esetére Type, nem használható közvetlenül szűrésnél. Ehelyett a helyiségtípusra való szűréshez egy lambda kifejezést használna egy tartományváltozóval, például a következővel:

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

Ebben a példában a tartományváltozó room megjelenik a room/Type mező elérési útján. Így room/Type az aktuális dokumentum aktuális helyiségének típusára utal. Ez az Type almező egyetlen példánya, így közvetlenül a szűrőben is használható.

Mezőútvonalak használata

A mezőútvonalak az Azure AI Keresés REST API-k számos paraméterében használhatók. Az alábbi táblázat felsorolja az összes helyet, ahol használhatók, valamint a használatukra vonatkozó korlátozásokat:

Állandók

Az OData-konstansok egy adott Entity Data Model (EDM) típushoz tartozó literálértékek. Az Azure AI Keresésben támogatott típusok listáját a Támogatott adattípusok című témakörben találja. A gyűjteménytípusok állandói nem támogatottak.

Az alábbi táblázat az OData-kifejezéseket támogató nem adattípusok konstansainak példáit mutatja be:

Speciális karakterek megkerülése sztringkonstansokban

Az OData sztringkonstansait egyszeres idézőjelek határolják el. Ha olyan sztringállandóval rendelkező lekérdezést kell létrehoznia, amely maga is tartalmazhat egyetlen idézőjelet, a beágyazott idézőjelek megkétszerezésével elkerülheti őket.

Például egy olyan formázatlan aposztrófot tartalmazó kifejezés, mint "Alice autója" az OData-ban sztringállandóként 'Alice''s car'jelenik meg.

Konstansok szintaxisa

Az alábbi EBNF (Extended Backus-Naur Form) a fenti táblázatban látható állandók többségének nyelvtanát határozza meg. A földrajzi térbeli típusok nyelvtana az Azure AI Keresés OData geo-térbeli függvényeiben található.

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'

Interaktív szintaxisdiagram is elérhető:

Kifejezések létrehozása mezőútvonalakból és állandókból

A mezőútvonalak és -állandók az OData-kifejezések legalapvetőbb részei, de már maguk a teljes kifejezések. Az Azure AI Keresés $select paramétere valójában nem más, mint a mezőútvonalak vesszővel tagolt listája, és $orderby nem sokkal bonyolultabb, mint $select. Ha történetesen egy típusmező Edm.Boolean van az indexben, akár olyan szűrőt is írhat, amely nem más, mint a mező elérési útja. Az állandók true és false ugyanígy érvényes szűrők.

Gyakoribb azonban, hogy összetett kifejezések egynél több mezőre és állandóra hivatkoznak. Ezek a kifejezések a paramétertől függően különböző módokon épülnek fel.

A következő EBNF (Extended Backus-Naur form) határozza meg a $filter, $orderby és $select paraméterek nyelvtanát. Ezek a mezőútvonalakra és állandókra hivatkozó egyszerűbb kifejezésekből épülnek fel:

filter_expression ::= boolean_expression

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

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

Interaktív szintaxisdiagram is elérhető:

Következő lépések

A $orderby és $select paraméterek az egyszerűbb kifejezések vesszővel tagolt listái. A $filter paraméter egy logikai kifejezés, amely egyszerűbb részexpressziókból áll. Ezek az alkifejezések olyan logikai operátorok használatával vannak kombinálva, mint and, or és not, az összehasonlító operátorok, például eq, lt, gt stb., valamint a kollekciós operátorok, mint any és all.

A $filter, $orderby és $select paramétereket az alábbi cikkek részletesebben ismertetik:

• OData $filter szintaxis az Azure AI Keresésben
• OData $orderby szintaxis az Azure AI Keresésben
• OData $select szintaxis az Azure AI Keresésben