Omówienie języka OData dla usług $filter, $orderbyi $select w usłudze Azure AI Search

  • Artykuł

Ten artykuł zawiera omówienie języka wyrażeń OData używanego w usłudze $filter, $order i wyrażeniach $select w usłudze Azure AI Search. Język jest przedstawiany jako "bottom-up" począwszy od najbardziej podstawowych elementów. Wyrażenia OData, które można utworzyć w żądaniu zapytania, wahają się od prostych do wysoce złożonych, ale wszystkie mają wspólne elementy. Elementy udostępnione obejmują:

  • Ścieżki pól odwołujące się do określonych pól indeksu.
  • Stałe, które są wartościami literałów określonego typu danych.

Po zapoznaniu się z tymi typowymi pojęciami możesz kontynuować składnię najwyższego poziomu dla każdego wyrażenia:

  • $filter wyrażenia są oceniane podczas analizowania zapytań, ograniczania wyszukiwania do określonych pól lub dodawania kryteriów dopasowania używanych podczas skanowania indeksu.
  • $orderby wyrażenia są stosowane jako krok przetwarzania końcowego w zestawie wyników w celu sortowania zwracanych dokumentów.
  • $select wyrażenia określają, które pola dokumentów znajdują się w zestawie wyników.

Składnia tych wyrażeń różni się od prostej lub pełnej składni zapytań używanej w parametrze wyszukiwania , chociaż w składni odwołującej się do pól występuje pewne nakładanie.

Uwaga

Terminologia w usłudze Azure AI Search różni się od standardu OData na kilka sposobów. To, co nazywamy polem w usłudze Azure AI Search, jest nazywane właściwością OData i podobnie dla ścieżki pola a ścieżki właściwości. Indeks zawierający dokumenty w usłudze Azure AI Search jest bardziej ogólnie określany w usłudze OData jako zestaw jednostek zawierający jednostki. Terminologia usługi Azure AI Search jest używana w tej dokumentacji.

Ścieżki pól

Poniższy formularz EBNF (rozszerzony formularz Backus-Naur) definiuje gramatykę ścieżek pól.

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

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

Dostępny jest również interakcyjny diagram składni:

Diagram składni OData dla usługi Azure AI Search

Uwaga

Zobacz dokumentację składni wyrażeń OData dla usługi Azure AI Search , aby zapoznać się z pełną pełną NF.

Ścieżka pola składa się z co najmniej jednego identyfikatora oddzielonego ukośnikami . Każdy identyfikator jest sekwencją znaków, które muszą zaczynać się od litery ASCII lub podkreślenia i zawierają tylko litery ASCII, cyfry lub podkreślenia. Litery mogą być pisane wielkimi lub małymi literami.

Identyfikator może odwoływać się do nazwy pola lub zmiennej zakresu w kontekście wyrażenia kolekcji (any lub all) w filtrze. Zmienna zakresu jest podobna do zmiennej pętli reprezentującej bieżący element kolekcji. W przypadku złożonych kolekcji ta zmienna reprezentuje obiekt, dlatego można użyć ścieżek pól do odwoływania się do podpole zmiennej. Jest to analogiczne do notacji kropkowej w wielu językach programowania.

Przykłady ścieżek pól przedstawiono w poniższej tabeli:

Ścieżka pola opis
HotelName Odwołuje się do pola najwyższego poziomu indeksu
Address/City Odwołuje się do City pola podrzędnego pola złożonego w indeksie; Address jest typu Edm.ComplexType w tym przykładzie
Rooms/Type Odwołuje się do Type pola podrzędnego złożonego pola kolekcji w indeksie; Rooms jest typu Collection(Edm.ComplexType) w tym przykładzie
Stores/Address/Country Odwołuje się do Country pola podrzędnego pola podrzędnego Address złożonego pola kolekcji w indeksie; Stores jest typu i Address jest typu Collection(Edm.ComplexType)Edm.ComplexType w tym przykładzie
room/Type Odwołuje się do Type podpola zmiennej room zakresu, na przykład w wyrażeniu filtru Rooms/any(room: room/Type eq 'deluxe')
store/Address/Country Odwołuje się do Country podpola podpola Addressstore zmiennej zakresu, na przykład w wyrażeniu filtru Stores/any(store: store/Address/Country eq 'Canada')

Znaczenie ścieżki pola różni się w zależności od kontekstu. W filtrach ścieżka pola odwołuje się do wartości pojedynczego wystąpienia pola w bieżącym dokumencie. W innych kontekstach, takich jak $orderby, $select lub w wyszukiwaniu w polu w pełnej składni Lucene, ścieżka pola odwołuje się do samego pola. Ta różnica ma pewne konsekwencje dla sposobu używania ścieżek pól w filtrach.

Rozważ ścieżkę Address/Citypola . W filtrze odnosi się to do pojedynczego miasta dla bieżącego dokumentu, takiego jak "San Francisco". Rooms/Type Natomiast odnosi się do podpola Type dla wielu pokoi (takich jak "standard" dla pierwszego pokoju, "deluxe" dla drugiego pokoju itd.). Ponieważ Rooms/Type nie odnosi się do pojedynczego wystąpienia pola podrzędnego Type, nie można go używać bezpośrednio w filtrze. Zamiast tego, aby filtrować według typu pomieszczenia, należy użyć wyrażenia lambda ze zmienną zakresu, w następujący sposób:

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

W tym przykładzie zmienna room zakresu jest wyświetlana w ścieżce room/Type pola. W ten sposób room/Type odnosi się do typu bieżącego pokoju w bieżącym dokumencie. Jest to pojedyncze wystąpienie pola podrzędnego Type , więc można go używać bezpośrednio w filtrze.

Używanie ścieżek pól

Ścieżki pól są używane w wielu parametrach interfejsów API REST usługi Azure AI Search. W poniższej tabeli wymieniono wszystkie miejsca, w których można ich używać, oraz wszelkie ograniczenia dotyczące ich użycia:

Interfejs API Nazwa parametru Ograniczenia
Tworzenie lub aktualizowanie indeksu suggesters/sourceFields Brak
Tworzenie lub aktualizowanie indeksu scoringProfiles/text/weights Może odwoływać się tylko do pól z możliwością wyszukiwania
Tworzenie lub aktualizowanie indeksu scoringProfiles/functions/fieldName Może odwoływać się tylko do pól możliwych do filtrowania
Wyszukiw. search gdy queryType jest full Może odwoływać się tylko do pól z możliwością wyszukiwania
Wyszukiw. facet Może odwoływać się tylko do pól aspektowych
Wyszukiw. highlight Może odwoływać się tylko do pól z możliwością wyszukiwania
Wyszukiw. searchFields Może odwoływać się tylko do pól z możliwością wyszukiwania
Sugerowanie i autouzupełnianie searchFields Może odwoływać się tylko do pól, które są częścią sugestora
Wyszukiwanie, sugerowanie i autouzupełnianie $filter Może odwoływać się tylko do pól możliwych do filtrowania
Wyszukiwanie i sugerowanie $orderby Może odwoływać się tylko do pól sortowalnych
Wyszukiwanie, sugerowanie i wyszukiwanie $select Może odwoływać się tylko do pól, które można pobrać

Stałe

Stałe w usłudze OData to wartości literału danego typu modelu danych jednostki (EDM). Zobacz Obsługiwane typy danych, aby uzyskać listę obsługiwanych typów w usłudze Azure AI Search. Stałe typów kolekcji nie są obsługiwane.

W poniższej tabeli przedstawiono przykłady stałych dla każdego z typów danych obsługiwanych przez usługę Azure AI Search:

Typ danych Przykładowe stałe
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'

Ucieczka znaków specjalnych w stałych ciągów

Stałe ciągów w usłudze OData są rozdzielane pojedynczymi cudzysłowami. Jeśli musisz skonstruować zapytanie ze stałą ciągu, która może zawierać pojedyncze cudzysłowy, możesz uniknąć osadzonych cudzysłowów, podwojając je.

Na przykład fraza z niesformatowanym apostrofem, na przykład "samochód Alicji", będzie reprezentowana w usłudze OData jako stała 'Alice''s car'ciągu .

Ważne

Podczas programowego konstruowania filtrów należy pamiętać o ucieczce stałych ciągów pochodzących z danych wejściowych użytkownika. Ma to na celu ograniczenie możliwości ataków polegających na wstrzyknięciu, zwłaszcza w przypadku używania filtrów do implementowania przycinania zabezpieczeń.

Składnia stałych

Poniższy formularz EBNF (rozszerzony formularz Backus-Naur) definiuje gramatykę dla większości stałych pokazanych w powyższej tabeli. Gramatyka typów geoprzestrzeni znajduje się w funkcjach geoprzestrzeniowych OData w usłudze 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'

Dostępny jest również interakcyjny diagram składni:

Diagram składni OData dla usługi Azure AI Search

Uwaga

Zobacz dokumentację składni wyrażeń OData dla usługi Azure AI Search , aby zapoznać się z pełną pełną NF.

Kompilowanie wyrażeń ze ścieżek pól i stałych

Ścieżki pól i stałe są najbardziej podstawową częścią wyrażenia OData, ale są już pełne wyrażenia. W rzeczywistości parametr $select w usłudze Azure AI Search nie jest niczym innym niż rozdzielona przecinkami lista ścieżek pól, a $orderby nie jest znacznie bardziej skomplikowana niż $select. Jeśli masz pole typu Edm.Boolean w indeksie, możesz nawet napisać filtr, który nie jest niczym, ale ścieżką tego pola. Stałe true i false są podobnie prawidłowymi filtrami.

Jednak w większości przypadków będziesz potrzebować bardziej złożonych wyrażeń odwołujących się do więcej niż jednego pola i stałej. Te wyrażenia są tworzone na różne sposoby w zależności od parametru.

Poniższy formularz EBNF (rozszerzony formularz Backus-Naur) definiuje gramatykę parametrów $filter, $orderby i $select . Są one tworzone na podstawie prostszych wyrażeń odwołujących się do ścieżek pól i stałych:

filter_expression ::= boolean_expression

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

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

Dostępny jest również interakcyjny diagram składni:

Diagram składni OData dla usługi Azure AI Search

Uwaga

Zobacz dokumentację składni wyrażeń OData dla usługi Azure AI Search , aby zapoznać się z pełną pełną NF.

Następne kroki

Parametry $orderby i $select to rozdzielane przecinkami listy prostszych wyrażeń. Parametr $filter jest wyrażeniem logicznym składającym się z prostszych podrażeń podrzędnych. Te podrażenia są łączone przy użyciu operatorów logicznych, takich jak , ori , operatory porównania, takie jakeqand , lt, gti tak dalej, i operatory kolekcji, takie jak any i .allnot

Parametry $filter, $orderby i $select zostały szczegółowo opisane w następujących artykułach: