Příklady jednoduchých vyhledávacích dotazů ve službě Azure AI Search
Ve službě Azure AI Search vyvolá jednoduchá syntaxe dotazu výchozí analyzátor dotazů pro fulltextové vyhledávání. Analyzátor je rychlý a zpracovává běžné scénáře, včetně fulltextového vyhledávání, filtrovaného a fasetového vyhledávání a vyhledávání předpon. Tento článek používá příklady k ilustraci jednoduchého použití syntaxe v požadavku rozhraní REST API (Search Documents).
Poznámka:
Alternativní syntaxe dotazu je Lucene, která podporuje složitější struktury dotazů, jako je přibližné vyhledávání a vyhledávání zástupných znaků. Další informace naleznete v tématu Příklady úplné syntaxe vyhledávání Lucene .
Ukázkový index hotelů
Následující dotazy jsou založené na ukázkovém indexu hotelů, který můžete vytvořit podle pokynů v rychlém startu: Vytvoření indexu vyhledávání na webu Azure Portal.
Příklady dotazů jsou vyjádřeny pomocí rozhraní REST API a požadavků POST. Můžete je vložit a spustit v klientovi REST. Nebo použijte zobrazení JSON Průzkumníka služby Search na webu Azure Portal. V zobrazení JSON můžete vložit příklady dotazů uvedené zde v tomto článku.
Hlavičky požadavku musí mít následující hodnoty:
| Key | Hodnota |
|---|---|
| Content-Type | application/json |
| api-key | <your-search-service-api-key>– dotaz nebo klíč správce |
Parametry identifikátoru URI musí obsahovat koncový bod vyhledávací služby s názvem indexu, kolekcemi docs, příkazem pro vyhledávání a verzí rozhraní API, podobně jako v následujícím příkladu:
https://{{service-name}}.search.windows.net/indexes/hotels-sample-index/docs/search?api-version=2024-07-01
Text požadavku by se měl vytvořit jako platný JSON:
{
"search": "*",
"queryType": "simple",
"select": "HotelId, HotelName, Category, Tags, Description",
"count": true
}
searchnastavená na * je nespecifikovaný dotaz, který odpovídá hledání s hodnotou null nebo prázdným vyhledáváním. Není to zvlášť užitečné, ale je to nejjednodušší hledání, které můžete udělat, a zobrazuje všechna zobrazitelná pole v indexu se všemi hodnotami.queryTypenastavená na jednoduchou hodnotu je výchozí a dá se vynechat, ale je třeba zdůraznit, že příklady dotazů v tomto článku jsou vyjádřeny v jednoduché syntaxi.selectPro složení výsledků hledání se používá seznam polí oddělených čárkami, včetně těch polí, která jsou užitečná v kontextu výsledků hledání.countvrátí počet dokumentů odpovídajících kritériím hledání. U prázdného vyhledávacího řetězce je počet všech dokumentů v indexu (50 v indexu hotels-sample-index).
Příklad 1: Fulltextové vyhledávání
Fulltextové vyhledávání může být libovolný počet samostatných termínů nebo uvozovek uzavřených frází s logickými operátory nebo 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
}
Hledání klíčových slov, které se skládá z důležitých termínů nebo frází, funguje nejlépe. Řetězcová pole procházejí při indexování a dotazování textovou analýzou, zahazují žádná nepotřebná slova, jako je the, a to. Pokud chcete zjistit, jak se řetězec dotazu tokenizuje v indexu, předejte řetězec ve volání Analyzovat text do indexu.
Parametr searchMode řídí přesnost a úplnost. Pokud chcete další úplnost, použijte výchozí libovolnou hodnotu, která vrátí výsledek, pokud se některá část řetězce dotazu shoduje. Pokud dáváte přednost přesnosti, kde musí být všechny části řetězce spárovány, změňte searchMode na všechny. Zkuste předchozí dotaz oba způsoby zjistit, jak searchMode změní výsledek.
Odpověď pro dotaz na bazén spa + letiště by měla vypadat podobně jako v následujícím příkladu.
"@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"
}
]
Všimněte si skóre hledání v odpovědi. Toto je skóre relevance shody. Vyhledávací služba ve výchozím nastavení vrátí prvních 50 shod na základě tohoto skóre.
Jednotné skóre 1,0 nastane, když neexistuje žádné pořadí, a to buď proto, že hledání nebylo fulltextové vyhledávání, nebo protože nebyla zadána žádná kritéria. Například v prázdném hledání (search=*) se řádky vrátí v libovolném pořadí. Když zahrnete skutečná kritéria, uvidíte, že se skóre hledání vyvíjí na smysluplné hodnoty.
Příklad 2: Vyhledání podle ID
Po vrácenívýsledkůch Tento příklad ukazuje, jak vrátit jeden dokument pomocí funkce Získat dokument předáním ID dokumentu.
GET /indexes/hotels-sample-index/docs/41?api-version=2024-07-01
Všechny dokumenty mají jedinečný identifikátor. Pokud používáte Azure Portal, vyberte index na kartě Indexy a pak se podívejte na definice polí, abyste zjistili, které pole je klíčem. V rozhraní REST API vrátí volání GET Index definici indexu v textu odpovědi.
Odpověď pro předchozí dotaz se skládá z dokumentu, jehož klíč je 41. Všechna pole označená jako načítaná v definici indexu se dají vrátit ve výsledcích hledání a vykreslit v aplikaci.
{
"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"
}
}
Příklad 3: Filtrování textu
Syntaxe filtru je výraz OData, který můžete použít sám nebo s search. Při společném použití ve stejném požadavku filter se nejprve použije na celý index a pak se search provede s výsledky filtru. Používání filtrů tak může být užitečné pro zlepšení výkonu dotazů zmenšením sady dokumentů, které musí dotaz vyhledávání zpracovat.
Filtry lze definovat u libovolného pole označeného jako filterable v definici indexu. Pro hotely s ukázkovým indexem jsou filtrovatelná pole Kategorie, Značky, ParkingIncluded, Rating a většina polí Adresa .
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
}
Odpověď na předchozí dotaz je vymezena pouze na ty hotely, které jsou zařazené do kategorie Boutique, a zahrnují termíny umění nebo prohlídky. V tomto případě je jen jedna shoda.
"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"
}
]
Příklad 4: Funkce filtru
Výrazy filtru můžou zahrnovat funkce search.ismatch a search.ismatchscoring, které umožňují vytvořit vyhledávací dotaz v rámci filtru. Tento výraz filtru používá zástupný znak zdarma k výběru vybavení včetně bezplatné wi-fi, bezplatného parkování atd.
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
}
Odpověď na předchozí dotaz odpovídá 27 hotelům, které nabízejí bezplatné vybavení. Všimněte si, že skóre hledání je jednotné 1 ve výsledcích. Důvodem je to, že hledaný výraz má hodnotu null nebo prázdný, takže výsledkem bude shoda s doslovnými filtry, ale žádné fulltextové vyhledávání. Skóre relevance se vrátí pouze při fulltextové vyhledávání. Pokud používáte filtry bez search, ujistěte se, že máte dostatečná seřazená pole, abyste mohli řídit pořadí hledání.
"@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"
]
},
. . .
Příklad 5: Filtry rozsahu
Filtrování rozsahu se podporuje prostřednictvím výrazů filtrů pro libovolný datový typ. Následující příklady ilustrují číselné a řetězcové oblasti. Datové typy jsou důležité ve filtrech oblastí a fungují nejlépe, když jsou číselná data v číselných polích a řetězcová data v řetězcových polích. Číselná data v řetězcových polích nejsou vhodná pro oblasti, protože číselné řetězce nejsou srovnatelné.
Následující dotaz je číselný rozsah. V indexu hotels-sample-index je Ratingjediným filtrovatelným číselným polem .
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
}
Odpověď pro tento dotaz by měla vypadat podobně jako v následujícím příkladu, oříznutá kvůli stručnosti.
"@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
},
...
Dalším dotazem je filtr rozsahu přes pole řetězce (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
}
Odpověď pro tento dotaz by měla vypadat podobně jako v následujícím příkladu, oříznutá kvůli stručnosti. V tomto příkladu není možné řadit podle StateProvince , protože pole není v definici indexu přiřazeno jako seřazené .
{
"@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 "
}
},
. . .
Příklad 6: Geoprostorové vyhledávání
Hotel-sample-index obsahuje pole Umístění se souřadnicemi zeměpisné šířky a délky. V tomto příkladu se používá funkce geo.distance, která filtruje dokumenty v rámci obvodu počátečního bodu na libovolnou vzdálenost (v kilometrech), kterou zadáte. Poslední hodnotu v dotazu (10) můžete upravit tak, aby se zmenšila nebo zvětšila plocha dotazu.
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
}
Odpověď pro tento dotaz vrátí všechny hotely ve vzdálenosti 10 kilometrů od zadaných souřadnic:
{
"@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"
}
}
]
}
Příklad 7: Logické hodnoty s searchMode
Jednoduchá syntaxe podporuje logické operátory ve formě znaků (+, -, |) pro podporu logiky DOTAZU AND, OR a NOT. Logické vyhledávání se chová podle očekávání s několika pozoruhodnými výjimkami.
V logickém vyhledávání zvažte přidání parametru searchMode jako mechanismu pro ovlivnění přesnosti a úplnosti. Platné hodnoty zahrnují "searchMode": "any" upřednostnění odvolání (dokument, který splňuje některá kritéria, je považován za shodu) a "searchMode": "all" upřednostnění přesnosti (všechna kritéria musí být v dokumentu spárována).
V kontextu logického vyhledávání může být výchozí nastavení "searchMode": "any" matoucí, pokud dotaz nakládáte s více operátory a získáváte širší místo užších výsledků. To platí zejména u funkce NOT, kde výsledky obsahují všechny dokumenty , které neobsahují konkrétní termín nebo frázi.
V následujícím příkladu je uvedena ukázka. Dotaz hledá shody v restauraci, která vylučuje klimatizaci fráze. Pokud spustíte následující dotaz s vlastnostmi searchMode (any), vrátí se 43 dokumentů: dokumenty obsahující termín restaurace a všechny dokumenty, které nemají frázi *klimatizace.
Všimněte si, že mezi logickým operátorem (-) a klimatizací frází není mezera. Uvozovky jsou uvozovky uvozovky (\").
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
}
Změna tak, aby "searchMode": "all" vynucuje kumulativní účinek na kritéria a vrací menší sadu výsledků (sedm shod) sestávajících z dokumentů obsahujících termín restaurace, minus těch, které obsahují klimatizaci frází.
Odpověď pro tento dotaz by teď vypadala podobně jako v následujícím příkladu, oříznutá kvůli stručnosti.
{
"@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"
]
},
...
Příklad 8: Stránkování výsledků
V předchozích příkladech jste se dozvěděli o parametrech, které ovlivňují složení výsledků hledání, včetně select toho, která pole jsou ve výsledku, pořadí řazení a jak zahrnout počet všech shod. Tento příklad je pokračováním složení výsledků hledání ve formě stránkovaných parametrů, které umožňují dávkovat počet výsledků, které se zobrazí na libovolné stránce.
Ve výchozím nastavení vyhledávací služba vrátí prvních 50 shod. Chcete-li řídit počet shod na každé stránce, použijte top k definování velikosti dávky a pak použijte skip k vyzvednutí následných dávek.
Následující příklad používá u pole filtr a pořadí Rating řazení (Hodnocení je filtrovatelné i seřazené), protože je jednodušší zobrazit účinky stránkování na seřazené výsledky. V běžném full vyhledávacím dotazu jsou nejvyšší shody seřazené a stránkované podle @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
}
Dotaz najde 21 odpovídajících dokumentů, ale protože jste zadali top, odpověď vrátí pouze prvních pět shod, přičemž hodnocení začíná 4,9 a končí na 4,7 s Lakeside B & B.
Pokud chcete získat dalších pět, přeskočte první dávku:
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
}
Odpověď druhé dávky přeskočí prvních pět shod a vrátí další pět, počínaje Pull'r Inn Motel. Pokud chcete pokračovat v dalších dávkách, ponecháte top jich pět a pak v každém novém požadavku zvýšíte skip o pět (skip=5, skip=10, skip=15 atd.).
{
"@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
}
]
}
Související obsah
Teď, když máte nějaký postup se základní syntaxí dotazu, zkuste zadat dotazy v kódu. Následující odkaz popisuje, jak nastavit vyhledávací dotazy pomocí sad Azure SDK.
Další odkazy na syntaxi, architekturu dotazů a příklady najdete na následujících odkazech: