Översikt över OData-språk för $filter, $orderbyoch $select i Azure AI Search
Den här artikeln innehåller en översikt över det OData-uttrycksspråk som används i $filter, $order-byoch $select uttryck för nyckelordssökning i Azure AI Search över numeriska fält och strängfält (nonvector).
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.
Exempel på andra språk som Python eller C# finns i exemplen på lagringsplatsen azure-search-vector-samples .
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:
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 |
Ingen |
| 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 icke-bevektordatatyper som stöder OData-uttryck:
| 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:
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.
Det är dock vanligare att ha 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:
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: