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 , $order-byi $select wyszukiwania słów kluczowych w $filterusł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 .
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:
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 Address store 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 |
| Wyszukaj | search gdy queryType jest full |
Może odwoływać się tylko do pól z możliwością wyszukiwania |
| Wyszukaj | facet |
Może odwoływać się tylko do pól aspektowych |
| Wyszukaj | highlight |
Może odwoływać się tylko do pól z możliwością wyszukiwania |
| Wyszukaj | 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 innych niż wektory, które obsługują wyrażenia OData:
| 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:
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 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:
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: