OData-språköversikt $filter för , och i $orderby $select Azure Cognitive Search

Azure Cognitive Search stöder en delmängd av OData-uttryckssyntaxen för $filter, $orderby och $select uttryck. Filteruttryck utvärderas vid frågeparsning, begränsar sökningen till specifika fält eller lägger till matchningsvillkor som används vid indexgenomsökningar. Order-by-uttryck tillämpas som ett efterbearbetningssteg över en resultatuppsättning för att sortera de dokument som returneras. Välj 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.

Den här artikeln innehåller en översikt över det OData-uttrycksspråk som används i filter, ordning efter och välj uttryck. Språket visas "nedifrån och upp", från de mest grundläggande elementen och bygger på dem. Syntaxen på den översta nivån för varje parameter beskrivs i en separat artikel:

• $filter syntax
• $orderby syntax
• $select syntax

OData-uttryck sträcker sig från enkla till mycket komplexa, men alla delar gemensamma element. De mest grundläggande delarna i ett OData-uttryck i Azure Cognitive Search är:

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

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:

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 versaler 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 ) i ett all filter. En intervallvariabel är som en loopvariabel som representerar det aktuella elementet i samlingen. 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 underordnade fält i variabeln. Detta motsvarar punkt notation i många programmeringsspråk.

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

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 enskild instans av ett fält i det aktuella dokumentet. I andra kontexter, till exempel $orderby, $select, eller i fältsök i den fullständiga Lucene-syntaxenrefererar 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 refererar till delfältet för många rum (t.ex. "standard" för det första Rooms/Type rummet, "room" för det andra rummet Type och så vidare). Eftersom Rooms/Type inte refererar till en enda instans av underfältet kan den inte användas direkt i Type ett filter. Om du istället vill filtrera på 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 variabeln room intervall i room/Type fältsökvägen. På så sätt room/Type refererar till typen av det aktuella rummet i det aktuella dokumentet. Det här är en enda instans Type av 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 för de Azure Cognitive Search REST-API:erna. I följande tabell visas alla platser där de kan användas, samt eventuella begränsningar för deras användning:

Konstanter

Konstanter i OData är literalvärden för en viss entitetsdatamodell (EDM). Se Datatyper som stöds för en lista över typer som stöds i Azure Cognitive Search. 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 Cognitive Search:

Undantag för specialtecken i strängkonstanter

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

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

Syntax för konstanter

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

Ett interaktivt syntaxdiagram är också tillgängligt:

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 Cognitive Search bara en kommaavgränsad lista med fältsökvägar, och $orderby är inte mycket mer komplicerat än $select. Om du råkar ha ett fält av typen i indexet kan du till och med skriva ett filter som bara är Edm.Boolean sökvägen till det fältet. Konstanterna och true är false också giltiga filter.

I de flesta fall behöver du dock mer komplexa uttryck som refererar till mer än ett fält och en konstant. De här uttrycken är inbyggda 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:

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 hjälp av logiska operatorer som and or not , och , jämförelseoperatorer som eq , , och lt så gt vidare,och samlingsoperatorer som any och all .

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

• OData$filter syntax i Azure Cognitive Search
• OData$orderby syntax i Azure Cognitive Search
• OData $select syntax i Azure Cognitive Search

Se även

• Fasettad navigering i Azure Cognitive Search
• Filter i Azure Cognitive Search
• Sök dokument (Azure Cognitive Search REST API)
• Lucene-frågesyntax
• Enkel frågesyntax i Azure Cognitive Search