Översikt över OData-språk för $filter, $orderbyoch $select i Azure AI Search

  • Artikel

Den här artikeln innehåller en översikt över det OData-uttrycksspråk som används i $filter, $order och $select uttryck i Azure AI Search. Språket presenteras "bottom-up" som börjar med de mest grundläggande elementen. De OData-uttryck som du kan konstruera i en frågebegäran sträcker sig från enkla till mycket komplexa, men de delar alla gemensamma element. Delade element är:

  • Fältsökvägar, som refererar till specifika fält i ditt index.
  • Konstanter, som är literalvärden för en viss datatyp.

När du förstår de här vanliga begreppen kan du fortsätta med syntaxen på den översta nivån för varje uttryck:

  • $filter uttryck utvärderas under frågeparsning, begränsar sökningen till specifika fält eller lägger till matchningsvillkor som används vid indexgenomsökningar.
  • $orderby uttryck används som ett efterbearbetningssteg över en resultatuppsättning för att sortera de dokument som returneras.
  • $select uttryck avgör vilka dokumentfält som ingår i resultatuppsättningen.

Syntaxen för dessa uttryck skiljer sig från den enkla eller fullständiga frågesyntax som används i sökparametern, även om det finns viss överlappning i syntaxen för referensfält.

Kommentar

Terminologin i Azure AI Search skiljer sig från OData-standarden på några olika sätt. Det vi kallar ett fält i Azure AI Search kallas för en egenskap i OData och på samma sätt för fältsökväg kontra egenskapssökväg. Ett index som innehåller dokument i Azure AI Search kallas mer allmänt i OData som en entitetsuppsättning som innehåller entiteter. Terminologin för Azure AI Search används i den här referensen.

Fältsökvägar

Följande EBNF (Extended Backus-Naur Form) definierar grammatiken för fältsökvägar.

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

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

Ett interaktivt syntaxdiagram är också tillgängligt:

OData-syntaxdiagram för Azure AI Search

Kommentar

Se syntaxreferens för OData-uttryck för Azure AI Search för hela EBNF.

En fältsökväg består av en eller flera identifierare avgränsade med snedstreck. Varje identifierare är en sekvens med tecken som måste börja med en ASCII-bokstav eller understreck och som endast innehåller ASCII-bokstäver, siffror eller understreck. Bokstäverna kan vara övre eller gemener.

En identifierare kan referera antingen till namnet på ett fält eller till en intervallvariabel i kontexten för ett samlingsuttryck (any eller all) i ett filter. En intervallvariabel är som en loopvariabel som representerar samlingens aktuella element. För komplexa samlingar representerar variabeln ett objekt, vilket är anledningen till att du kan använda fältsökvägar för att referera till underfält i variabeln. Detta motsvarar punkt notation i många programmeringsspråk.

Exempel på fältsökvägar visas i följande tabell:

Fältsökväg beskrivning
HotelName Refererar till ett toppnivåfält i indexet
Address/City Refererar till City underfältet för ett komplext fält i indexet. Address Är av typen Edm.ComplexType i det här exemplet
Rooms/Type Refererar till Type underfältet för ett komplext samlingsfält i indexet. Rooms Är av typen Collection(Edm.ComplexType) i det här exemplet
Stores/Address/Country Refererar till Country underfältet i Address underfältet för ett komplext samlingsfält i indexet. Stores Är av typen Collection(Edm.ComplexType) och Address är av typen Edm.ComplexType i det här exemplet
room/Type Refererar till Type underfältet för room intervallvariabeln, till exempel i filteruttrycket Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Refererar till Country underfältet i Address underfältet för store intervallvariabeln, till exempel i filteruttrycket Stores/any(store: store/Address/Country eq 'Canada')

Innebörden av en fältsökväg varierar beroende på kontexten. I filter refererar en fältsökväg till värdet för en enda instans av ett fält i det aktuella dokumentet. I andra sammanhang, till exempel $orderby, $select eller i fältsökning i den fullständiga Lucene-syntaxen, refererar en fältsökväg till själva fältet. Den här skillnaden har vissa konsekvenser för hur du använder fältsökvägar i filter.

Överväg fältsökvägen Address/City. I ett filter refererar detta till en enda stad för det aktuella dokumentet, till exempel "San Francisco". Däremot Rooms/Type refererar till Type underfältet för många rum (som "standard" för det första rummet, "deluxe" för det andra rummet och så vidare). Eftersom Rooms/Type inte refererar till en enda instans av underfältet Typekan den inte användas direkt i ett filter. Om du i stället vill filtrera efter rumstyp använder du ett lambda-uttryck med en intervallvariabel, så här:

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

I det här exemplet visas intervallvariabeln room i room/Type fältsökvägen. På så sätt room/Type refererar till typen av aktuellt rum i det aktuella dokumentet. Det här är en enda instans av Type underfältet, så det kan användas direkt i filtret.

Använda fältsökvägar

Fältsökvägar används i många parametrar i REST-API:erna för Azure AI Search. I följande tabell visas alla platser där de kan användas, plus eventuella begränsningar för deras användning:

API Parameternamn Begränsningar
Skapa eller uppdatera index suggesters/sourceFields Inga
Skapa eller uppdatera index scoringProfiles/text/weights Kan bara referera till sökbara fält
Skapa eller uppdatera index scoringProfiles/functions/fieldName Kan bara referera till filterbara fält
Sök search när queryType är full Kan bara referera till sökbara fält
Sök facet Kan bara referera till fasettfält
Sök highlight Kan bara referera till sökbara fält
Sök searchFields Kan bara referera till sökbara fält
Föreslå och komplettera automatiskt searchFields Kan bara referera till fält som ingår i en förslagsanvändare
Sök, föreslå och komplettera automatiskt $filter Kan bara referera till filterbara fält
Sök och föreslå $orderby Kan bara referera till sorterbara fält
Sök, föreslå och leta upp $select Kan bara referera till hämtningsbara fält

Konstanter

Konstanter i OData är literalvärden av en viss EDM-typ (Entity Data Model ). En lista över typer som stöds i Azure AI Search finns i Datatyper som stöds. Konstanter av samlingstyper stöds inte.

I följande tabell visas exempel på konstanter för var och en av de datatyper som stöds av Azure AI Search:

Datatyp Exempelkonstanter
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'

Undfly specialtecken i strängkonstanter

Strängkonstanter i OData avgränsas med enkla citattecken. Om du behöver skapa en fråga med en strängkonstant som i sig kan innehålla enkla citattecken kan du undvika de inbäddade citattecknarna genom att fördubbla dem.

Till exempel skulle en fras med en oformaterad apostrofer som "Alice bil" representeras i OData som strängkonstanten 'Alice''s car'.

Viktigt!

När du skapar filter programmatiskt är det viktigt att komma ihåg att escape-strängkonstanter som kommer från användarindata. Detta är för att minska risken för inmatningsattacker, särskilt när du använder filter för att implementera säkerhetstrimning.

Syntax för konstanter

Följande EBNF (Extended Backus-Naur Form) definierar grammatiken för de flesta av konstanterna som visas i tabellen ovan. Grammatiken för geo-spatiala typer finns i geo-spatiala OData-funktioner i 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'

Ett interaktivt syntaxdiagram är också tillgängligt:

OData-syntaxdiagram för Azure AI Search

Kommentar

Se syntaxreferens för OData-uttryck för Azure AI Search för hela EBNF.

Skapa uttryck från fältsökvägar och konstanter

Fältsökvägar och konstanter är den mest grundläggande delen av ett OData-uttryck, men de är redan fullständiga uttryck själva. I själva verket är $select-parametern i Azure AI Search inget annat än en kommaavgränsad lista över fältsökvägar och $orderby är inte mycket mer komplicerad än $select. Om du råkar ha ett fält av typen Edm.Boolean i indexet kan du till och med skriva ett filter som bara är sökvägen till det fältet. Konstanterna true och false är jämväl giltiga filtrerar.

För det mesta behöver du dock mer komplexa uttryck som refererar till mer än ett fält och en konstant. Dessa uttryck skapas på olika sätt beroende på parametern.

Följande EBNF (Extended Backus-Naur Form) definierar grammatiken för parametrarna $filter, $orderby och $select . Dessa bygger på enklare uttryck som refererar till fältsökvägar och konstanter:

filter_expression ::= boolean_expression

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

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

Ett interaktivt syntaxdiagram är också tillgängligt:

OData-syntaxdiagram för Azure AI Search

Kommentar

Se syntaxreferens för OData-uttryck för Azure AI Search för hela EBNF.

Nästa steg

Parametrarna $orderby och $select är båda kommaavgränsade listor med enklare uttryck. Parametern $filter är ett booleskt uttryck som består av enklare underuttryck. Dessa underuttryck kombineras med logiska operatorer som and, oroch not, jämförelseoperatorer someq , lt, gt, och så vidare och insamlingsoperatorer som any och all.

Parametrarna $filter, $orderby och $select utforskas mer detaljerat i följande artiklar: