Udostępnij za pośrednictwem

Przykłady prostych zapytań wyszukiwania w usłudze Azure AI Search

  • Artykuł

W usłudze Azure AI Search prosta składnia zapytania wywołuje domyślny analizator zapytań na potrzeby wyszukiwania pełnotekstowego. Analizator jest szybki i obsługuje typowe scenariusze, w tym wyszukiwanie pełnotekstowe, wyszukiwanie filtrowane i aspektowe oraz wyszukiwanie prefiksów. W tym artykule użyto przykładów, aby zilustrować proste użycie składni w żądaniu wyszukiwania dokumentów (interfejs API REST).

Uwaga

Alternatywna składnia zapytania to Lucene, która obsługuje bardziej złożone struktury zapytań, takie jak wyszukiwanie rozmyte i wieloznaczne. Aby uzyskać więcej informacji, zobacz Przykłady pełnej składni wyszukiwania Lucene .

Przykładowy indeks hoteli

Następujące zapytania są oparte na indeksie hotels-sample-index, który można utworzyć, postępując zgodnie z instrukcjami w przewodniku Szybki start: tworzenie indeksu wyszukiwania w witrynie Azure Portal.

Przykładowe zapytania są wyrażane przy użyciu interfejsu API REST i żądań POST. Możesz wkleić je i uruchomić w kliencie REST. Możesz też użyć widoku JSON eksploratora wyszukiwania w witrynie Azure Portal. W widoku JSON możesz wkleić przykłady zapytań pokazane tutaj w tym artykule.

Nagłówki żądań muszą mieć następujące wartości:

Key Wartość
Typ zawartości application/json
api-key <your-search-service-api-key>, zapytanie lub klucz administracyjny

Parametry identyfikatora URI muszą zawierać punkt końcowy usługi wyszukiwania z nazwą indeksu, kolekcjami dokumentacji, poleceniem wyszukiwania i wersją interfejsu API, podobnie jak w poniższym przykładzie:

https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01

Treść żądania powinna zostać utworzona jako prawidłowy kod JSON:

{
    "search": "*",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Tags, Description",
    "count": true
}

  • search ustawiono wartość * to nieokreślone zapytanie, równoważne z wyszukiwaniem o wartości null lub pustym. Nie jest to szczególnie przydatne, ale jest to najprostsze wyszukiwanie, które można wykonać, i pokazuje wszystkie pola możliwe do pobrania w indeksie ze wszystkimi wartościami.

  • queryTypeustawienie parametru prostego jest wartością domyślną i można ją pominąć, ale jest uwzględniana w celu podkreślenie, że przykłady zapytań w tym artykule są wyrażane w prostej składni.

  • select ustawienie na rozdzielaną przecinkami listę pól służy do tworzenia wyników wyszukiwania, w tym tylko tych pól, które są przydatne w kontekście wyników wyszukiwania.

  • count Zwraca liczbę dokumentów spełniających kryteria wyszukiwania. W pustym ciągu wyszukiwania liczba jest wszystkimi dokumentami w indeksie (50 w indeksie hotels-sample-index).

Przykład 1. Wyszukiwanie pełnotekstowe

Wyszukiwanie pełnotekstowe może być dowolną liczbą autonomicznych terminów lub fraz ujętych w cudzysłów, z operatorami logicznymi lub bez.

POST /indexes/hotel-samples-index/docs/search?api-version=2024-07-01
{
    "search": "pool spa +airport",
    "searchMode": "any",
    "queryType": "simple",
    "select": "HotelId, HotelName, Category, Description",
    "count": true
}

Wyszukiwanie słów kluczowych składających się z ważnych terminów lub fraz zwykle działa najlepiej. Pola ciągów są poddawane analizie tekstu podczas indeksowania i wykonywania zapytań, upuszczając wyrazy bezznakowe, takie jak i. Aby zobaczyć, jak ciąg zapytania jest tokenizowany w indeksie, przekaż ciąg w wywołaniu Analizuj tekst do indeksu.

Parametr searchMode kontroluje precyzję i kompletność. Jeśli chcesz przypomnieć więcej, użyj domyślnej dowolnej wartości, która zwraca wynik, jeśli jakakolwiek część ciągu zapytania jest zgodna. Jeśli faworyzujesz precyzję, gdzie wszystkie części ciągu muszą być dopasowane, zmień na searchMode wszystkie. Wypróbuj poprzednie zapytanie na oba sposoby, aby zobaczyć, jak funkcja searchMode zmienia wynik.

Odpowiedź dla zapytania spa puli i lotniska powinna wyglądać podobnie do poniższego przykładu.

"@odata.count": 4,
"value": [
{
    "@search.score": 6.090657,
    "HotelId": "12",
    "HotelName": "Winter Panorama Resort",
    "Description": "Plenty of great skiing, outdoor ice skating, sleigh rides, tubing and snow biking. Yoga, group exercise classes and outdoor hockey are available year-round, plus numerous options for shopping as well as great spa services. Newly-renovated with large rooms, free 24-hr airport shuttle & a new restaurant. Rooms/suites offer mini-fridges & 49-inch HDTVs.",
    "Category": "Resort and Spa"
},
{
    "@search.score": 4.314683,
    "HotelId": "21",
    "HotelName": "Good Business Hotel",
    "Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from Lake Lanier & 10 miles from downtown. Our business center includes printers, a copy machine, fax, and a work area.",
    "Category": "Suite"
},
{
    "@search.score": 3.575948,
    "HotelId": "27",
    "HotelName": "Starlight Suites",
    "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
    "Category": "Suite"
},
{
    "@search.score": 2.6926985,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Description": "Newly Redesigned Rooms & airport shuttle. Minutes from the airport, enjoy lakeside amenities, a resort-style pool & stylish new guestrooms with Internet TVs.",
    "Category": "Suite"
}
]

Zwróć uwagę na wynik wyszukiwania w odpowiedzi. Jest to wynik zgodności. Domyślnie usługa wyszukiwania zwraca 50 pierwszych dopasowań na podstawie tego wyniku.

Jednolite wyniki 1,0 występują, gdy nie ma rangi, albo dlatego, że wyszukiwanie nie było przeszukiwania pełnotekstowego, lub dlatego, że nie podano kryteriów. Na przykład w pustym wyszukiwaniu (search=*) wiersze są zwracane w dowolnej kolejności. W przypadku uwzględnienia rzeczywistych kryteriów zobaczysz, że wyniki wyszukiwania zmieniają się w znaczące wartości.

Przykład 2. Wyszukiwanie według identyfikatora

Po zwróceniu wyników wyszukiwania następnym krokiem jest podanie strony szczegółów zawierającej więcej pól z dokumentu. W tym przykładzie pokazano, jak zwrócić pojedynczy dokument przy użyciu polecenia Pobierz dokument, przekazując identyfikator dokumentu.

GET /indexes/hotels-sample-index/docs/41?api-version=2024-07-01

Wszystkie dokumenty mają unikatowy identyfikator. Jeśli używasz witryny Azure Portal, wybierz indeks na karcie Indeksy , a następnie przyjrzyj się definicjom pól, aby określić, które pole jest kluczem. W interfejsie API REST wywołanie GET Index zwraca definicję indeksu w treści odpowiedzi.

Odpowiedź dla powyższego zapytania składa się z dokumentu, którego klucz to 41. Każde pole oznaczone jako możliwe do pobrania w definicji indeksu może być zwracane w wynikach wyszukiwania i renderowane w aplikacji.

{
    "HotelId": "41",
    "HotelName": "Windy Ocean Motel",
    "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Inspired by the natural beauty of the island, each room includes an original painting of local scenes by the owner. Rooms include a mini fridge, Keurig coffee maker, and flatscreen TV. Various shops and art entertainment are on the boardwalk, just steps away.",
    "Description_fr": "Cet hôtel en bord de mer donnant sur la plage propose des chambres dotées d'un balcon privé et de 2 piscines intérieure et extérieure. Inspiré par la beauté naturelle de l'île, chaque chambre comprend une peinture originale de scènes locales par le propriétaire. Les chambres comprennent un mini-réfrigérateur, une cafetière Keurig et une télévision à écran plat. Divers magasins et divertissements artistiques se trouvent sur la promenade, à quelques pas.",
    "Category": "Suite",
    "Tags": [
    "pool",
    "air conditioning",
    "bar"
    ],
    "ParkingIncluded": true,
    "LastRenovationDate": "2021-05-10T00:00:00Z",
    "Rating": 3.5,
    "Location": {
    "type": "Point",
    "coordinates": [
        -157.846817,
        21.295841
    ],
    "crs": {
        "type": "name",
        "properties": {
        "name": "EPSG:4326"
        }
    }
    },
    "Address": {
    "StreetAddress": "1450 Ala Moana Blvd 2238 Ala Moana Ctr",
    "City": "Honolulu",
    "StateProvince": "HI",
    "PostalCode": "96814",
    "Country": "USA"
    }
}

Przykład 3. Filtrowanie tekstu

Składnia filtru to wyrażenie OData, którego można użyć samodzielnie lub za pomocą searchpolecenia . Gdy używane razem w tym samym żądaniu, filter jest stosowane najpierw do całego indeksu, a następnie search jest wykonywane na wynikach filtru. Z tego względu filtrowanie może być przydatne, jeśli chcemy poprawić wydajność zapytań, ponieważ pozwala ono zawęzić zestaw dokumentów przetwarzany przez zapytanie wyszukiwania.

Filtry można zdefiniować na dowolnym polu oznaczonym jako filterable w definicji indeksu. W przypadku parametrów hotels-sample-index pola z możliwością filtrowania obejmują pola Kategoria, Tagi, ParkingIncluded, Ocena i większość pól Adres .

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "art tours",
    "queryType": "simple",
    "filter": "Category eq 'Boutique'",
    "searchFields": "HotelName,Description,Category",
    "select": "HotelId,HotelName,Description,Category",
    "count": true
}

Odpowiedź dla powyższego zapytania jest ograniczona tylko do tych hoteli sklasyfikowanych jako Butik, które obejmują terminy sztuki lub wycieczki. W tym przypadku jest tylko jedno dopasowanie.

"value": [
{
    "@search.score": 1.2814453,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.",
    "Category": "Boutique"
}
]

Przykład 4. Funkcje filtrowania

Wyrażenia filtru mogą zawierać funkcje search.ismatch i search.ismatchscoring, co umożliwia utworzenie zapytania wyszukiwania w filtrze. To wyrażenie filtru używa symbolu wieloznakowego bezpłatnie, aby wybrać udogodnienia, w tym bezpłatne wifi, bezpłatny parking itd.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
  {
    "search": "",
    "filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
    "select": "HotelName, Tags, Description",
    "count": true
  }

Odpowiedź na poprzednie zapytanie pasuje do 27 hoteli, które oferują bezpłatne udogodnienia. Zwróć uwagę, że wynik wyszukiwania jest jednolity 1 w wynikach. Jest to spowodowane tym, że wyrażenie wyszukiwania ma wartość null lub jest puste, co powoduje dopasowanie filtru dosłownego, ale bez wyszukiwania pełnotekstowego. Wyniki zgodności są zwracane tylko w przypadku wyszukiwania pełnotekstowego. Jeśli używasz filtrów bez search, upewnij się, że masz wystarczające pola sortowania, aby można było kontrolować rangę wyszukiwania.

  "@odata.count": 27,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Country Residence Hotel",
      "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door.",
      "Tags": [
        "laundry service",
        "restaurant",
        "free parking"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Downtown Mix Hotel",
      "Description": "Mix and mingle in the heart of the city. Shop and dine, mix and mingle in the heart of downtown, where fab lake views unite with a cheeky design.",
      "Tags": [
        "air conditioning",
        "laundry service",
        "free wifi"
      ]
    },
    {
      "@search.score": 1,
      "HotelName": "Starlight Suites",
      "Description": "Complimentary Airport Shuttle & WiFi. Book Now and save - Spacious All Suite Hotel, Indoor Outdoor Pool, Fitness Center, Florida Green certified, Complimentary Coffee, HDTV",
      "Tags": [
        "pool",
        "coffee in lobby",
        "free wifi"
      ]
    },
. . .

Przykład 5. Filtry zakresu

Filtrowanie zakresu jest obsługiwane za pomocą wyrażeń filtrów dla dowolnego typu danych. W poniższych przykładach przedstawiono zakresy liczbowe i ciągowe. Typy danych są ważne w filtrach zakresu i działają najlepiej, gdy dane liczbowe znajdują się w polach liczbowych i danych ciągów w polach ciągów. Dane liczbowe w polach ciągów nie są odpowiednie dla zakresów, ponieważ ciągi liczbowe nie są porównywalne.

Poniższe zapytanie jest zakresem liczbowym. W pliku hotels-sample-index jedynym filtrowanym polem liczbowym jest Rating.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating ge 2 and Rating lt 4",
    "select": "HotelId, HotelName, Rating",
    "orderby": "Rating desc",
    "count": true
}

Odpowiedź dla tego zapytania powinna wyglądać podobnie do poniższego przykładu, przycinana w celu zwięzłości.

"@odata.count": 27,
"value": [
{
    "@search.score": 1,
    "HotelId": "22",
    "HotelName": "Lion's Den Inn",
    "Rating": 3.9
},
{
    "@search.score": 1,
    "HotelId": "25",
    "HotelName": "Waterfront Scottish Inn",
    "Rating": 3.8
},
{
    "@search.score": 1,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Rating": 3.6
},
...

Następne zapytanie jest filtrem zakresu w polu ciągu (Address/StateProvince):

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
    "select": "HotelId, HotelName, Address/StateProvince",
    "count": true
}

Odpowiedź dla tego zapytania powinna wyglądać podobnie do poniższego przykładu, przycinana w celu zwięzłości. W tym przykładzie nie można sortować StateProvince według, ponieważ pole nie jest przypisywane jako sortowalne w definicji indeksu.

{
  "@odata.count": 9,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "39",
      "HotelName": "White Mountain Lodge & Suites",
      "Address": {
        "StateProvince": "CO"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "9",
      "HotelName": "Smile Up Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "7",
      "HotelName": "Roach Motel",
      "Address": {
        "StateProvince": "CA "
      }
    },
    {
      "@search.score": 1,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Address": {
        "StateProvince": "CT"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "37",
      "HotelName": "Campus Commander Hotel",
      "Address": {
        "StateProvince": "CA "
      }
    },
. . .

Indeks hotels-sample-index zawiera pole Lokalizacja ze współrzędnymi szerokości i długości geograficznej. W tym przykładzie użyto funkcji geo.distance, która filtruje dokumenty w obwodzie punktu początkowego do dowolnej odległości (w kilometrach) podanej przez Użytkownika. Możesz dostosować ostatnią wartość w zapytaniu (10), aby zmniejszyć lub powiększyć obszar powierzchni zapytania.

POST /indexes/v/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
    "select": "HotelId, HotelName, Address/City, Address/StateProvince",
    "count": true
}

Odpowiedź dla tego zapytania zwraca wszystkie hotele w odległości 10 kilometrów od podanych współrzędnych:

{
  "@odata.count": 3,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "45",
      "HotelName": "Happy Lake Resort & Restaurant",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Address": {
        "City": "Seattle",
        "StateProvince": "WA"
      }
    }
  ]
}

Przykład 7: wartość logiczna z trybem searchMode

Prosta składnia obsługuje operatory logiczne w postaci znaków (+, -, |), aby obsługiwać logikę zapytań AND, OR i NOT. Wyszukiwanie logiczne zachowuje się tak, jak można się spodziewać, z kilkoma godnymi uwagi wyjątkami.

W wyszukiwaniu logicznym rozważ dodanie parametru searchMode jako mechanizmu mającego wpływ na precyzję i kompletność. Prawidłowe wartości obejmują "searchMode": "any" faworyzowanie kompletności (dokument spełniający dowolne kryteria jest uznawany za dopasowanie) i "searchMode": "all" faworyzujący precyzję (wszystkie kryteria muszą być dopasowane w dokumencie).

W kontekście wyszukiwania warunkowego wartość domyślna "searchMode": "any" może być myląca, jeśli stosujesz zapytanie z wieloma operatorami i stajesz się szerszy zamiast węższych wyników. Dotyczy to szczególnie not, gdzie wyniki obejmują wszystkie dokumenty , które nie zawierają określonego terminu lub frazy.

Poniższy przykład stanowi ilustrację. Zapytanie wyszukuje dopasowania w restauracji, które wykluczają klimatyzację frazy. Jeśli uruchomisz następujące zapytanie z trybem searchMode (dowolnym), zostaną zwrócone 43 dokumenty: te zawierające termin restauracja, a także wszystkie dokumenty, które nie mają frazy *klimatyzacji.

Zwróć uwagę, że nie ma spacji między operatorem logicznym (-) i klimatyzacją frazy. Znaki cudzysłowu są ucieczki (\").

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "restaurant -\"air conditioning\"",
    "searchMode": "any",
    "searchFields": "Tags",
    "select": "HotelId, HotelName, Tags",
    "count": true
}

Zmiana na wymusza "searchMode": "all" skumulowany wpływ na kryteria i zwraca mniejszy zestaw wyników (siedem dopasowań) składających się z dokumentów zawierających termin restauracja, minus te zawierające klimatyzację frazy.

Odpowiedź dla tego zapytania będzie teraz wyglądać podobnie do poniższego przykładu, przycinana w celu zwięzłości.

{
  "@odata.count": 14,
  "value": [
    {
      "@search.score": 3.1383743,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "22",
      "HotelName": "Lion's Den Inn",
      "Tags": [
        "laundry service",
        "free wifi",
        "restaurant"
      ]
    },
    {
      "@search.score": 2.028083,
      "HotelId": "34",
      "HotelName": "Lakefront Captain Inn",
      "Tags": [
        "restaurant",
        "laundry service",
        "coffee in lobby"
      ]
    },
...

Przykład 8. Stronicowanie wyników

W poprzednich przykładach przedstawiono parametry wpływające na kompozycję wyników wyszukiwania, w tym select określające, które pola znajdują się w wyniku, kolejności sortowania i jak uwzględnić liczbę wszystkich dopasowań. Ten przykład jest kontynuacją kompozycji wyników wyszukiwania w postaci parametrów stronicowania, które umożliwiają wsadowanie liczby wyników wyświetlanych na dowolnej stronie.

Domyślnie usługa wyszukiwania zwraca 50 pierwszych dopasowań. Aby kontrolować liczbę dopasowań na każdej stronie, użyj polecenia top , aby zdefiniować rozmiar partii, a następnie użyć polecenia skip , aby pobrać kolejne partie.

W poniższym przykładzie użyto filtru i kolejności sortowania w Rating polu (ocena jest filtrowana i sortowana), ponieważ łatwiej jest zobaczyć skutki stronicowania posortowanych wyników. W regularnym pełnym zapytaniu wyszukiwania najważniejsze dopasowania są klasyfikowane i stronicowane według @search.score.

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "count": true
}

Zapytanie znajduje 21 pasujących dokumentów, ale ponieważ określono top, odpowiedź zwraca tylko pięć pierwszych dopasowań, z ocenami zaczynającymi się od 4,9 i kończącą się na 4,7 z usługą Lakeside B i B.

Aby uzyskać następne pięć, pomiń pierwszą partię:

POST /indexes/hotels-sample-index/docs/search?api-version=2024-07-01
{
    "search": "*",
    "filter": "Rating gt 4",
    "select": "HotelName, Rating",
    "orderby": "Rating desc",
    "top": 5,
    "skip": 5,
    "count": true
}

Odpowiedź drugiej partii pomija pierwsze pięć meczów, zwracając następne pięć, począwszy od Pull'r Inn Motel. Aby kontynuować wykonywanie większej liczby partii, należy zachować top liczbę pięciu, a następnie zwiększać skip się o pięć dla każdego nowego żądania (skip=5, skip=10, skip=15 itd.).

{
  "@odata.count": 21,
  "value": [
    {
      "@search.score": 1,
      "HotelName": "Head Wind Resort",
      "Rating": 4.7
    },
    {
      "@search.score": 1,
      "HotelName": "Sublime Palace Hotel",
      "Rating": 4.6
    },
    {
      "@search.score": 1,
      "HotelName": "City Skyline Antiquity Hotel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Nordick's Valley Motel",
      "Rating": 4.5
    },
    {
      "@search.score": 1,
      "HotelName": "Winter Panorama Resort",
      "Rating": 4.5
    }
  ]
}

Powiązana zawartość

Teraz, gdy znasz podstawową składnię zapytań, spróbuj określić zapytania w kodzie. Poniższy link zawiera opis sposobu konfigurowania zapytań wyszukiwania przy użyciu zestawów SDK platformy Azure.

Więcej informacji o składni, architekturze zapytań i przykładach można znaleźć w następujących linkach: