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

Ten artykuł zawiera omówienie języka wyrażeń OData używanego w wyrażeniach , $filteri $order-by wyszukiwania słów kluczowych w $selectusłudze Azure AI Search w polach liczbowych i ciągowych (niewektorów).

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.

Przykłady w innych językach, takich jak Python lub C#, zobacz przykłady w repozytorium azure-search-vector-samples .

Ś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:

Ś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:

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:

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 innych niż wektory, które obsługują wyrażenia OData:

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 .

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:

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 częściej występują złożone wyrażenia odwołujące 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:

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 , andinotgt, i operatory kolekcji, takie jak all

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

• Składnia $filter OData w usłudze Azure AI Search
• Składnia $orderby OData w usłudze Azure AI Search
• Składnia $select OData w usłudze Azure AI Search