Overzicht van de OData-taal $filter voor , en in $orderby $select Azure Cognitive Search

Azure Cognitive Search ondersteunt een subset van de OData-expressiesyntaxis voor expressies $filter, $orderby en $select expressies. Filterexpressie wordt geëvalueerd tijdens het parseren van query's, het beperken van zoekopdrachten tot specifieke velden of het toevoegen van overeenkomstcriteria die worden gebruikt tijdens indexscans. Order by-expressies worden toegepast als een naverwerkingsstap over een resultatenset om de geretourneerde documenten te sorteren. Selecteer expressies om te bepalen welke documentvelden zijn opgenomen in de resultatenset. De syntaxis van deze expressies verschilt van de eenvoudige of volledige querysyntaxis die wordt gebruikt in de zoekparameter, hoewel er enige overlap is in de syntaxis voor verwijzende velden.

Dit artikel biedt een overzicht van de OData-expressietaal die wordt gebruikt in filters, op volgorde en geselecteerde expressies. De taal wordt 'bottom-up' weergegeven, beginnend met de meest eenvoudige elementen en deze verder uit te bouwen. De syntaxis op het hoogste niveau voor elke parameter wordt beschreven in een afzonderlijk artikel:

• $filter syntaxis
• $orderby syntaxis
• $select syntaxis

OData-expressies variëren van eenvoudig tot zeer complex, maar ze delen allemaal gemeenschappelijke elementen. De meest eenvoudige onderdelen van een OData-expressie in Azure Cognitive Search zijn:

• Veldpaden die verwijzen naar specifieke velden van uw index.
• Constanten, letterlijke waarden van een bepaald gegevenstype.

Veldpaden

De volgende EBNF(Extended Backus-Naur Form)definieert de grammatica van veldpaden.

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

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

Er is ook een interactief syntaxisdiagram beschikbaar:

Een veldpad bestaat uit een of meer id's, gescheiden door slashes. Elke id is een reeks tekens die moet beginnen met een ASCII-letter of onderstrepingsteken en alleen ASCII-letters, cijfers of onderstrepingstekens moet bevatten. De letters kunnen hoofdletters of kleine letters zijn.

Een id kan verwijzen naar de naam van een veld of naar een bereikvariabele in de context van een verzamelingsexpressie ( of ) in any een all filter. Een bereikvariabele is als een lusvariabele die het huidige element van de verzameling vertegenwoordigt. Voor complexe verzamelingen vertegenwoordigt die variabele een object. Daarom kunt u veldpaden gebruiken om te verwijzen naar subvelden van de variabele. Dit is vergelijkbaar met punt-notatie in veel programmeertalen.

Voorbeelden van veldpaden worden weergegeven in de volgende tabel:

De betekenis van een veldpad verschilt afhankelijk van de context. In filters verwijst een veldpad naar de waarde van één exemplaar van een veld in het huidige document. In andere contexten, zoals $orderby, $select of in veldzoekactie in de volledige Lucene-syntaxis,verwijst een veldpad naar het veld zelf. Dit verschil heeft enkele gevolgen voor het gebruik van veldpaden in filters.

Kijk eens naar het veldpad Address/City . In een filter verwijst dit naar één plaats voor het huidige document, zoals 'San Francisco'. Verwijst daarentegen naar het subveld voor veel ruimten (zoals 'standaard' voor de eerste kamer, 'ue' voor de tweede Rooms/Type Type kamer, etc.). Omdat Rooms/Type niet naar één exemplaar van het subveld verwijst, kan het niet rechtstreeks in een Type filter worden gebruikt. Als u in plaats daarvan wilt filteren op het type ruimte, gebruikt u een lambda-expressie met een bereikvariabele, zoals:

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

In dit voorbeeld wordt de bereikvariabele room weergegeven in het room/Type veldpad. Op die manier room/Type verwijst naar het type van de huidige ruimte in het huidige document. Dit is één exemplaar van het subveld, zodat het rechtstreeks in Type het filter kan worden gebruikt.

Veldpaden gebruiken

Veldpaden worden gebruikt in veel parameters van de Azure Cognitive Search REST API's. De volgende tabel bevat alle locaties waar ze kunnen worden gebruikt, plus eventuele beperkingen voor hun gebruik:

Constanten

Constanten in OData zijn letterlijke waarden van een bepaald EDM-type (Entity Data Model). Zie Ondersteunde gegevenstypen voor een lijst met ondersteunde typen in Azure Cognitive Search. Constanten van verzamelingstypen worden niet ondersteund.

De volgende tabel bevat voorbeelden van constanten voor elk van de gegevenstypen die worden ondersteund door Azure Cognitive Search:

Escape-tekens in tekenreeksconstanten

Tekenreeksconstanten in OData worden door enkele aanhalingstekens scheidingstekens. Als u een query wilt maken met een tekenreeksconstante die mogelijk enkele aanhalingstekens bevat, kunt u de ingesloten aanhalingstekens escapen door ze te verdubbelen.

Een woordgroep met een niet-opgemaakte apostrof zoals 'De auto van Alice' wordt in OData bijvoorbeeld weergegeven als de tekenreeksconstante 'Alice''s car' .

Constantensyntaxis

De volgende EBNF(Extended Backus-Naur Form)definieert de grammatica voor de meeste constanten die in de bovenstaande tabel worden weergegeven. De grammatica voor geo-ruimtelijke typen vindt u in geo-ruimtelijke OData-functies in 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'

Er is ook een interactief syntaxisdiagram beschikbaar:

Expressies bouwen van veldpaden en constanten

Veldpaden en constanten zijn het meest eenvoudige onderdeel van een OData-expressie, maar ze zijn zelf al volledige expressies. De parameter $select in Azure Cognitive Search is in feite niets anders dan een door komma's gescheiden lijst met veldpaden en $orderby is niet veel gecompliceerder dan $select. Als u een veld van het type in uw index hebt, kunt u zelfs een filter schrijven dat niets anders is dan het Edm.Boolean pad van dat veld. De constanten true en zijn eveneens geldige false filters.

In de meeste tijd hebt u echter complexere expressies nodig die naar meer dan één veld en constante verwijzen. Deze expressies worden op verschillende manieren gebouwd, afhankelijk van de parameter .

De volgende EBNF (Extended Backus-Naur Form)definieert de grammatica voor de $filter, $orderby en $select parameters. Deze zijn opgebouwd uit eenvoudigere expressies die verwijzen naar veldpaden en constanten:

filter_expression ::= boolean_expression

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

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

Er is ook een interactief syntaxisdiagram beschikbaar:

De $orderby en $select zijn beide door komma's gescheiden lijsten met eenvoudigere expressies. De $filter parameter is een Booleaanse expressie die bestaat uit eenvoudigere subexpressie. Deze subexpressie wordt gecombineerd met logische operators zoals and or not , en , vergelijkingsoperatoren zoals eq , , lt gt ,en verzamelingsoperators, zoals any en all .

De parameters $filter, $orderby en $select worden uitgebreid beschreven in de volgende artikelen:

• OData $filter syntaxis in Azure Cognitive Search
• OData $orderby syntaxis in Azure Cognitive Search
• OData $select syntaxis in Azure Cognitive Search

Zie ook

• Facetnavigatie in Azure Cognitive Search
• Filters in Azure Cognitive Search
• Documenten zoeken (Azure Cognitive Search REST API)
• Lucene-querysyntaxis
• Eenvoudige querysyntaxis in Azure Cognitive Search