Az OData nyelv áttekintése a következő nyelveken: $filter $orderby , és $select Azure Cognitive Search

Azure Cognitive Search az OData-kifejezések szintaxisának egy részkészletét támogatja a $filter, $orderby és $select kifejezésekhez. A szűrőkifejezések kiértékelése a lekérdezések elemezése, a keresés adott mezőkre való korlátozása vagy az indexvizsgálatok során használt megfeleltethető feltételek hozzáadása során történik. Az order-by kifejezéseket a rendszer utófeldolgozási lépésként alkalmazza egy eredményhalmazra a visszaadott dokumentumok rendezése érdekében. A kifejezések kiválasztása határozza 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 mezőkre való hivatkozás szintaxisa átfedésben van.

Ez a cikk áttekintést nyújt a szűrőkben, sorrendben és kifejezések kiválasztásában használt OData-kifejezésnyelvről. A nyelvet "alulról felfelé" mutatjuk, kezdve a legalapvetőbb elemekkel, és ezek alapján építünk. Az egyes paraméterek legfelső szintű szintaxisát egy külön cikkben ismertetjük:

Az OData-kifejezések az egyszerűtől a rendkívül összetettek között vannak, de közös elemeken osztoznak. Az OData-kifejezések legfontosabb részei a Azure Cognitive Search:

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

Megjegyzés

A Azure Cognitive Search terminológiája több szempontból különbözik az OData-szabványtól. A mezők neve az OData Azure Cognitive Search tulajdonsága, a mezőútvonalhoz hasonlóan a tulajdonságútvonalhoz hasonlóan. Az OData Azure Cognitive Search dokumentumokat tartalmazó indexet általában entitásokat tartalmazó entitáshalmazként hivatkozunk az OData-ban. A Azure Cognitive Search terminológiáját használjuk a referenciában.

Mezőútvonalak

A mezőútvonalak nyelvtanát a következő EBNF (bővített Backus-Naur űrlap) határozza meg.

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

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

Egy interaktív szintaxisdiagram is elérhető:

Megjegyzés

A teljes EBNF-hez Azure Cognitive Search OData-kifejezések szintaxisának referenciáját.

A mezők elérési útjai egy vagy több, perjelekkel elválasztott azonosítóból állnak. Minden azonosító olyan karaktersorozat, amely ASCII-betűvel vagy aláhúzásjellel kezdődik, és csak ASCII-betűket, számjegyeket vagy aláhúzásjeleket tartalmazhat. A betűk kis- és nagybetűsek is lehetnek.

Az azonosító hivatkozhat egy mező nevére vagy egy szűrő gyűjteménykifejezésének (vagy ) kontextusában megadott any all tartományváltozóra. A tartományváltozók olyan ciklusváltozók, amelyek a gyűjtemény aktuális elemét jelölik. Összetett gyűjtemények esetében ez a változó egy objektumot képvisel, ezért használhat mezőútvonalat a változó almezőire való hivatkozáshoz. Ez sok programnyelvben használt pontozottsághoz hasonló.

A mezőútvonalak példái az alábbi táblázatban láthatók:

Mező elérési útja Description
HotelName Az index legfelső szintű mezőjére hivatkozik
Address/City Az index egy összetett mezőjének almezője; ebben a példában a típusa City Address Edm.ComplexType
Rooms/Type Az index összetett gyűjteménymezőinek almezőire Type Rooms hivatkozik; ebben a példában a típusa Collection(Edm.ComplexType)
Stores/Address/Country Az indexben egy összetett gyűjteménymező almezője almezőre Country Address Stores Collection(Edm.ComplexType) Address Edm.ComplexType hivatkozik; a típusa és típusa ebben a példában
room/Type A Type tartományváltozó almezője, például a room szűrőkifejezésben Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country A tartományváltozó almezője almezőire hivatkozik, például Country Address a store szűrőkifejezésben Stores/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őútvonalak egy mező egyetlen példányának értékét jelentik az aktuális dokumentumban. Más környezetben, például $orderby, $select, vagy a teljes Luceneszintaxis mezőben való keresésében a mezőútvonal magára a mezőre hivatkozik. Ez a különbség bizonyos következményekkel jár a mezőútvonalak szűrőkben való használatára.

Tekintse meg a mező elérési Address/City útját. Egy szűrőben ez az aktuális dokumentum egyetlen városára vonatkozik, például "San Francisco". Ezzel szemben a több helyiség almezőjét jelöli (például az első teremben a "standard", a második teremben a Rooms/Type Type ".", és így tovább). Mivel nem hivatkozik az almező egyetlen példányára, nem használható közvetlenül egy Rooms/Type Type szűrőben. Ehelyett a helyiség típusára való szűréshez egy lambda kifejezést kell használnia egy tartományváltozóval, a következő szerint:

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

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

Mezőútvonalak használata

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

API Paraméter neve Korlátozások
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
Search search when queryType is full Csak kereshető mezőkre hivatkozhat
Search facet Csak a facetable mezőkre hivatkozhat
Search highlight Csak kereshető mezőkre hivatkozhat
Search searchFields Csak kereshető mezőkre hivatkozhat
Javaslat és automatikus kiegészítés searchFields Csak olyan mezőkre hivatkozhat, amelyek egy javaslattitkozó részei
Keresés, Javaslat, és Automatikus kiegészítés $filter Csak szűrhető mezőkre hivatkozhat
Keresés és javaslat $orderby Csak a rendezhető mezőkre hivatkozhat
Keresés, Javaslat, és Keresés $select Csak lekért mezőkre hivatkozhat

Állandók

Az OData konstansai egy adott entitás adatmodell (EDM) típusának konstansértékei. A támogatott típusok listáját a Támogatott adattípusok a Azure Cognitive Search. A gyűjteménytípusok állandói nem támogatottak.

Az alábbi táblázat az egyes támogatott adattípusok konstansait mutatja Azure Cognitive Search:

Adattípus Példa konstansok
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 karakterének kikerülés a sztringstanúsok között

Az OData-ban a sztringstanúsok egyszeres idézőjelekkel vannak elválasztva. Ha olyan sztring-állandóval kell lekérdezést összeépítenie, amely magában is tartalmazhat egyszeres idézőjeleket, a beágyazott idézőjelek kivédhetőek a duplálással.

Például egy formázatlan aposztrófmal (például "Alice autója" ) az OData-ban sztringkonstansként jelenne 'Alice''s car' meg.

Fontos

Amikor programozott módon hoz létre szűrőket, fontos, hogy a felhasználói bevitelből származó sztring-konstansokat ne felejtse el kivédeni. Ez csökkenti az injektálásos támadások esélyét,különösen akkor, ha szűrőkkel implementálja a biztonsági vágást.

Állandók szintaxisa

A következő EBNF ( bővítettBackus-Naur űrlap) határozza meg a nyelvtant a fenti táblázatban látható legtöbb állandóhoz. A térinformatikai típusok szintaxisa az OData térinformatikaifüggvényében található a Azure Cognitive 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'

Interaktív szintaxisdiagram is elérhető:

Megjegyzés

A teljes EBNF-ről Azure Cognitive Search OData-kifejezések szintaxisának referenciája tartalmaz további adatokat.

Kifejezések kiépítése mezőútvonalakból és állandókból

A mezőútvonalak és állandók az OData-kifejezések legapvetőbb részei, de maguk is teljes kifejezések. Valójában a $select paramétere nem más Azure Cognitive Search mint a mezőútvonalak vesszővel elválasztott listája, és $orderby sokkal összetettebb, mint a $select. Ha az indexben van egy típusú mező, akár olyan szűrőt is írhat, amely csak az adott mező elérési Edm.Boolean útja. A és a true false konstans hasonlóan érvényes szűrők.

A legtöbb esetben azonban összetettebb kifejezésekre van szükség, amelyek egynél több mezőre és konstansra hivatkoznak. Ezek a kifejezések a paramétertől függően különböző módon vannak felépítve.

A következő EBNF ( Bővített Backus-Naur űrlap) határozza meg a $filter, $orderby és $select nyelvtanát. Ezek egyszerűbb kifejezésekből épülnek fel, amelyek mezőútvonalakra és állandókra hivatkoznak:

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

Megjegyzés

A teljes EBNF-ről Azure Cognitive Search OData-kifejezések szintaxisának referenciája tartalmaz további adatokat.

A $orderby és $select paraméterek egyaránt egyszerűbb kifejezések vesszővel elválasztott listájai. A $filter paraméter egy logikai kifejezés, amely egyszerűbb alkifejezésekből áll. Ezeket az alkifejezéseket olyan logikai operátorok kombinálják, mint a and , or not a és a , az összehasonlító operátorok, például a , a , a eq lt gt stb.és a gyűjtemény operátorai, például a any és all a .

A $filter, $orderby, $select és paraméterekkel kapcsolatos további részleteket a következő cikkekben vizsgáljuk meg:

Lásd még