Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
Omówienie języka OData dla
Uwaga
Foundry IQ (Wyszukiwanie AI platformy Azure) udostępnia bezpośrednie interfejsy API indeksowania i zapytań, a także interfejsy API wyższego poziomu dla źródeł wiedzy i baz wiedzy do zarządzanego pobierania. Użyj portalu Azure, interfejsów API REST lub Azure SDKs, aby skonfigurować te możliwości lub połączyć agentów z bazami wiedzy w portalu Microsoft Foundry.
Ten artykuł zawiera omówienie języka wyrażeń OData używanego w wyrażeniach $order-by, $select i $filter na potrzeby wyszukiwania słów kluczowych w Foundry IQ (Wyszukiwanie AI platformy Azure) w polach liczbowych i ciągach znaków (niewektorowych).
Język jest przedstawiany w sposób oddolny, zaczynając 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ą przetwarzane podczas analizowania zapytań, co ogranicza wyszukiwanie do określonych pól lub dodaje kryteria dopasowania używane podczas skanowania indeksu.
- $orderby wyrażenia są stosowane jako krok przetwarzania końcowego w zestawie wyników w celu sortowania zwracanych dokumentów.
- wyrażenia $select określają, które pola dokumentu 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 się.
Przykłady w innych językach, takich jak Python lub C#, można znaleźć w repozytorium azure-search-vector-samples.
Uwaga
Terminologia w Foundry IQ różni się od standardu OData na kilka sposobów. To, co nazywamy polem w funkcji IQ usługi Foundry, jest nazywane właściwością w usłudze OData i podobnie dla ścieżki pola w porównaniu ze ścieżką właściwości. Indeks zawierający dokumenty w IQ rozwiązania Foundry jest bardziej ogólnie określany w usłudze OData jako zestaw jednostek zawierający jednostki. W całym tym opisie referencyjnym jest używana terminologia Foundry IQ.
Ś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
Aby uzyskać pełną składnię EBNF, zobacz dokumentację składni wyrażeń OData dla Foundry IQ.
Ś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 odnosić się do nazwy pola lub do 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 w polu podrzędnym Address złożonego pola kolekcji w indeksie; Stores jest typu Collection(Edm.ComplexType), a Address jest typu 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 podpola Country podpola Address zmiennej zakresu store, 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 zakresu room znajduje się w ścieżce pola room/Type. 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ą stosowane w wielu parametrach interfejsów API REST usługi Foundry IQ. W poniższej tabeli wymieniono wszystkie miejsca, w których można ich używać, oraz wszelkie ograniczenia dotyczące ich użycia:
| API | Nazwa parametru | Ograniczenia |
|---|---|---|
| Utwórz lub Zaktualizuj indeks | suggesters/sourceFields |
Brak |
| Tworzenie lub aktualizowanie indeksu | scoringProfiles/text/weights |
Może odwoływać się tylko do pól z możliwością wyszukiwania |
| Utwórz lub zaktualizuj indeks | scoringProfiles/functions/fieldName |
Może odwoływać się tylko do pól możliwych do filtrowania |
| Wyszukiwanie |
search kiedy queryType jest full |
Może odwoływać się tylko do pól z możliwością wyszukiwania |
| Wyszukiwanie | facet |
Może odnosić się tylko do pól możliwych do użycia w facetingu |
| Wyszukiwanie | highlight |
Może odwoływać się tylko do pól z możliwością wyszukiwania |
| Szukaj | 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 Sugestie | $orderby |
Może odwoływać się tylko do pól sortowalnych |
| Wyszukiwanie, Sugerowanie i Wyszukiwanie szczegółów | $select |
Może odwoływać się tylko do pól, które można pobrać |
Stałe
Stałe w OData to literałowe wartości danego typu Modelu Danych Jednostki (EDM). Zobacz Obsługiwane typy danych , aby uzyskać listę obsługiwanych typów w funkcji IQ usługi Foundry. 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' |
Maskowanie znaków specjalnych w stałych łańcuchach
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, jak "samochód Alice", będzie reprezentowana w usłudze OData jako stała ciągu 'Alice''s car'.
Ważne
Podczas programowego konstruowania filtrów należy pamiętać o zabezpieczeniu 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 geoprzestrzennych znajduje się w funkcjach geoprzestrzennych OData w Foundry IQ.
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
Aby uzyskać pełną pełną nfNF, zobacz dokumentację składni wyrażeń OData dla uwierzytelniania IQ usługi Foundry .
Tworzenie 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łnoprawnymi wyrażeniami. W rzeczywistości parametr $select w Foundry IQ nie jest niczym innym niż rozdzieloną przecinkami listą ścieżek pól, a $orderby nie jest dużo bardziej skomplikowany 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
Aby uzyskać pełną składnię EBNF, zobacz dokumentację składni wyrażeń OData dla Foundry IQ.
Następne kroki
Parametry $orderby i $select to rozdzielane przecinkami listy prostszych wyrażeń. Parametr $filter jest wyrażeniem logicznym złożonym z prostszych podwyrażeń. Te podwyrażenia są łączone przy użyciu operatorów logicznych, takich jak and, or i not, operatorów porównania, takich jak eq, lt, gt i tak dalej, oraz operatorów kolekcji, takich jak any i all.
Parametry $filter, $orderby i $select zostały szczegółowo opisane w następujących artykułach: