Az OData nyelvének áttekintése az $orderbyAzure AI Searchben és $select az $filterAzure AI Searchben

  • Cikk

Ez a cikk áttekintést nyújt az Azure AI Search $filter, $order by és $select kifejezéseiben használt OData kifejezési nyelvről. 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.

Megjegyzés:

Az Azure AI Search terminológiája néhány szempontból eltér az OData szabványtól . Az Azure AI Search egy mezőjét OData-tulajdonságnak nevezzük, és hasonlóképpen a mező elérési útját és a tulajdonság elérési útját is. Az Azure AI Searchben dokumentumokat tartalmazó indexet az OData általában entitásokat tartalmazó entitáskészletként hivatkozik. Ebben a hivatkozásban az Azure AI Search terminológiája használatos.

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ő:

OData szintaxisdiagram az Azure AI Searchhöz

Megjegyzés:

A teljes EBNF-hez tekintse meg az Azure AI Search OData-kifejezésszintaxis-hivatkozását.

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:

Mező elérési útja Leírás
HotelName Az index legfelső szintű mezőjére hivatkozik
Address/City City Egy összetett mező almezőjére hivatkozik az indexben; Address a példa típusa Edm.ComplexType
Rooms/Type Type Egy összetett gyűjteménymező almezőjére hivatkozik az indexben; Rooms ebben a példában a típus a következőCollection(Edm.ComplexType):
Stores/Address/Country Country Egy összetett gyűjteménymező almezőjének Address almezőjére hivatkozik az indexben; Stores típusa Collection(Edm.ComplexType) és Address típusa Edm.ComplexType ebben a példában
room/Type Type A tartományváltozó almezőjeroom, például a szűrőkifejezésbenRooms/any(room: room/Type eq 'deluxe')
store/Address/Country Country A tartományváltozó almezőjének Address almezőjestore, például a szűrőkifejezésbenStores/any(store: store/Address/Country eq 'Canada')

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 maga a mező. 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ő elérési útjá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 Rooms/Type , hivatkozik az Type almező számos szoba (mint a "standard" az első szoba, "deluxe" a második szoba, és így tovább). Mivel Rooms/Type nem hivatkozik az almező Typeegyetlen példányára, nem használható közvetlenül egy szűrőben. 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 Search 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:

API Paraméter neve Restrictions
Index létrehozása vagy frissítése suggesters/sourceFields None
Index létrehozása vagy frissítése scoringProfiles/text/weights Csak kereshető mezőkre hivatkozhat
Index létrehozása vagy frissítése scoringProfiles/functions/fieldName Csak szűrhető mezőkre hivatkozhat
Keresés search mikor queryType van full Csak kereshető mezőkre hivatkozhat
Keresés facet Csak a facetable mezőkre hivatkozhat
Keresés highlight Csak kereshető mezőkre hivatkozhat
Keresés searchFields Csak kereshető mezőkre hivatkozhat
Javaslat és automatikus kiegészítés searchFields Csak olyan mezőkre hivatkozhat, amelyek egy javaslattevőhöz tartoznak
Keresés, javaslat és automatikus kiegészítés $filter Csak szűrhető mezőkre hivatkozhat
Keresés és javaslat $orderby Csak rendezhető mezőkre hivatkozhat
Keresés, javaslat és keresés $select Csak lekért mezőkre hivatkozhat

Állandók

Az OData-konstansok egy adott entity data model (EDM) típusú konstansértékek. Az Azure AI Searchben 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 Azure AI Search által támogatott adattípusok konstansainak példáit mutatja be:

Adattípus Példaállandók
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'

Speciális karakterek menekülése sztringállandókban

Az OData sztringállandóit egyetlen 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.

Fontos

A szűrők programozott létrehozásakor fontos megjegyezni, hogy a felhasználói bemenetből származó sztringállandók kivédésére van szükség. Ez az injektálási támadások lehetőségének mérséklése, különösen akkor, ha szűrőket használ a biztonsági vágás implementálásához.

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 Search 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ő:

OData szintaxisdiagram az Azure AI Searchhöz

Megjegyzés:

A teljes EBNF-hez tekintse meg az Azure AI Search OData-kifejezésszintaxis-hivatkozását.

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

A legtöbb esetben azonban összetettebb kifejezésekre lesz szüksége, amelyek 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ő:

OData szintaxisdiagram az Azure AI Searchhöz

Megjegyzés:

A teljes EBNF-hez tekintse meg az Azure AI Search OData-kifejezésszintaxis-hivatkozását.

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 a , or, és notaz összehasonlító operátorok, példáuleq , lt, gtstb.allanyand

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