Omówienie języka OData dla $filter, $orderby i $select w Foundry IQ (Wyszukiwanie AI platformy Azure)

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:

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: