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 Úplná Lucene, která podporuje složitější struktury dotazů, jako je přibližné vyhledávání a vyhledávání se zástupnými cardy. Další informace a příklady najdete v tématu Použití úplné syntaxe 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 tomto rychlém startu.
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=2023-11-01
Text požadavku by se měl vytvořit jako platný JSON:
{
"search": "*",
"queryType": "simple",
"select": "HotelId, HotelName, Category, Tags, Description",
"count": true
}
Hodnota "search" nastavená na
*není zadaný dotaz, který odpovídá hodnotě null nebo prázdnému vyhledávání. 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."queryType" nastavený na "simple" je výchozí a dá se vynechat, ale je zahrnuta k dalšímu posílení, že příklady dotazů v tomto článku jsou vyjádřeny v jednoduché syntaxi.
"select" nastavený na čárkami oddělený seznam polí se používá pro složení výsledků hledání, včetně jenom těch polí, která jsou užitečná v kontextu výsledků hledání.
Funkce count vrá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 s logickými operátory nebo bez těchto operátorů.
POST /indexes/hotel-samples-index/docs/search?api-version=2023-11-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 a zahazují se žádná nepotřebná slova, jako je "the", "and", "it". 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 odvolat více, použijte výchozí hodnotu any, která vrátí výsledek, pokud se některá část řetězce dotazu shoduje. Pokud dáváte přednost přesnosti, kde se musí shodovat všechny části řetězce, změňte searchMode na "all". Zkuste výše uvedený dotaz jak zjistit, jak searchMode změní výsledek.
Odpověď na dotaz "pool spa +airport" by měla vypadat podobně jako v následujícím příkladu, oříznutá kvůli stručnosti.
"@odata.count": 6,
"value": [
{
"@search.score": 7.3617697,
"HotelId": "21",
"HotelName": "Nova Hotel & Spa",
"Description": "1 Mile from the airport. Free WiFi, Outdoor Pool, Complimentary Airport Shuttle, 6 miles from the beach & 10 miles from downtown.",
"Category": "Resort and Spa",
"Tags": [
"pool",
"continental breakfast",
"free parking"
]
},
{
"@search.score": 2.5560288,
"HotelId": "25",
"HotelName": "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": "Luxury",
"Tags": [
"24-hour front desk service",
"continental breakfast",
"free wifi"
]
},
{
"@search.score": 2.2988036,
"HotelId": "35",
"HotelName": "Suites At Bellevue Square",
"Description": "Luxury at the mall. Located across the street from the Light Rail to downtown. Free shuttle to the mall and airport.",
"Category": "Resort and Spa",
"Tags": [
"continental breakfast",
"air conditioning",
"24-hour front desk service"
]
}
]
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.
Uniform scores of "1,0" (Jednotné skóre 1,0) nastanou, pokud 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
Při vracení výsledků hledání v dotazu je logickým dalším krokem zadání stránky podrobností, která obsahuje další pole z dokumentu. Tento příklad ukazuje, jak vrátit jeden dokument pomocí vyhledávacího dokumentu předáním ID dokumentu.
GET /indexes/hotels-sample-index/docs/41?api-version=2023-11-01
Všechny dokumenty mají jedinečný identifikátor. Pokud používáte portál, vyberte index na kartě Indexy a pak se podívejte na definice polí, abyste zjistili, které pole je klíčem. Pomocí rest vrátí volání Get Index definici indexu v textu odpovědi.
Odpověď na výše uvedený dotaz se skládá z dokumentu, jehož klíč je 41. Všechna pole, která jsou v definici indexu označená jako "načístelná", se dají vrátit ve výsledcích hledání a vykreslit v aplikaci.
{
"HotelId": "41",
"HotelName": "Ocean Air Motel",
"Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away.",
"Description_fr": "L'hôtel front de mer surplombant la plage dispose de chambres avec balcon privé et 2 piscines intérieures et extérieures. Divers commerces et animations artistiques sont sur la promenade, à quelques pas.",
"Category": "Budget",
"Tags": [
"pool",
"air conditioning",
"bar"
],
"ParkingIncluded": true,
"LastRenovationDate": "1951-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. Používá se společně, filter použije se nejprve na celý index a pak se hledání 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=2023-11-01
{
"search": "art tours",
"queryType": "simple",
"filter": "Category eq 'Resort and Spa'",
"searchFields": "HotelName,Description,Category",
"select": "HotelId,HotelName,Description,Category",
"count": true
}
Odpověď na výše uvedený dotaz je vymezena pouze na ty hotely, které jsou zařazené do kategorií "Report and Spa" (Sestava a Lázně) a které zahrnují termíny "umění" nebo "tours". V tomto případě je jen jedna shoda.
{
"@search.score": 2.8576312,
"HotelId": "31",
"HotelName": "Santa Fe Stay",
"Description": "Nestled on six beautifully landscaped acres, located 2 blocks from the Plaza. Unwind at the spa and indulge in art tours on site.",
"Category": "Resort and Spa"
}
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=2023-11-01
{
"search": "",
"filter": "search.ismatch('free*', 'Tags', 'full', 'any')",
"select": "HotelId, HotelName, Category, Description",
"count": true
}
Odpověď na výše uvedený dotaz odpovídá 19 hotelům, které nabízejí bezplatné vybavení. Všimněte si, že skóre hledání je ve výsledcích jednotné "1,0". 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": 19,
"value": [
{
"@search.score": 1.0,
"HotelId": "31",
"HotelName": "Santa Fe Stay",
"Tags": [
"view",
"restaurant",
"free parking"
]
},
{
"@search.score": 1.0,
"HotelId": "27",
"HotelName": "Super Deluxe Inn & Suites",
"Tags": [
"bar",
"free wifi"
]
},
{
"@search.score": 1.0,
"HotelId": "39",
"HotelName": "Whitefish Lodge & Suites",
"Tags": [
"continental breakfast",
"free parking",
"free wifi"
]
},
{
"@search.score": 1.0,
"HotelId": "11",
"HotelName": "Regal Orb Resort & Spa",
"Tags": [
"free wifi",
"restaurant",
"24-hour front desk service"
]
},
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 jediným filtrovatelným číselným polem Hodnocení.
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-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.0,
"HotelId": "22",
"HotelName": "Stone Lion Inn",
"Rating": 3.9
},
{
"@search.score": 1.0,
"HotelId": "25",
"HotelName": "Scottish Inn",
"Rating": 3.8
},
{
"@search.score": 1.0,
"HotelId": "2",
"HotelName": "Twin Dome Motel",
"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=2023-11-01
{
"search": "*",
"filter": "Address/StateProvince ge 'A*' and Address/StateProvince lt 'D*'",
"select": "HotelId, HotelName, Address/StateProvince",
"count": true
}
Odpověď na tento dotaz by měla vypadat podobně jako v následujícím příkladu a měla by se zkrátit. V tomto příkladu není možné řadit podle StateProvince, protože pole není v definici indexu přiřazené jako "seřaditelné".
"@odata.count": 9,
"value": [
{
"@search.score": 1.0,
"HotelId": "9",
"HotelName": "Smile Hotel",
"Address": {
"StateProvince": "CA "
}
},
{
"@search.score": 1.0,
"HotelId": "39",
"HotelName": "Whitefish Lodge & Suites",
"Address": {
"StateProvince": "CO"
}
},
{
"@search.score": 1.0,
"HotelId": "7",
"HotelName": "Countryside Resort",
"Address": {
"StateProvince": "CA "
}
},
...
Příklad 6: Geoprostorové vyhledávání
Index ukázek hotelů 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=2023-11-01
{
"search": "*",
"filter": "geo.distance(Location, geography'POINT(-122.335114 47.612839)') le 10",
"select": "HotelId, HotelName, Address/City, Address/StateProvince",
"count": true
}
Odpověď na tento dotaz vrátí všechny hotely ve vzdálenosti 10 kilometrů od zadaných souřadnic:
{
"@odata.count": 3,
"value": [
{
"@search.score": 1.0,
"HotelId": "45",
"HotelName": "Arcadia Resort & Restaurant",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
},
{
"@search.score": 1.0,
"HotelId": "24",
"HotelName": "Gacc Capital",
"Address": {
"City": "Seattle",
"StateProvince": "WA"
}
},
{
"@search.score": 1.0,
"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 předchozích příkladech byl parametr zaveden jako mechanismus pro ovlivnění přesnosti a úplnosti, přičemž "searchMode": "any" upřednostnění odvolání (dokument, searchMode který splňuje všechna kritéria, je považován za shodu) a "searchMode=all" upřednostňuje přesnost (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. Vrátí se spuštění následujícího dotazu s vlastnostmi searchMode (any), 42 dokumentů, které obsahují termín "restaurace", a všechny dokumenty, které nemají frázi "klimatizace".
Všimněte si, že mezi logickým operátorem (-) a frází "klimatizace" není mezera.
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-01
{
"search": "restaurant -\"air conditioning\"",
"searchMode": "any",
"searchFields": "Tags",
"select": "HotelId, HotelName, Tags",
"count": true
}
Změna na vynucování "searchMode": "all" kumulativního účinku na kritéria a vrátí menší sadu výsledků (7 shod) sestávajících z dokumentů obsahujících termín "restaurace", minus ty, které obsahují frázi "klimatizace".
Odpověď na tento dotaz by teď vypadala podobně jako v následujícím příkladu, oříznutá kvůli stručnosti.
"@odata.count": 7,
"value": [
{
"@search.score": 2.5460577,
"HotelId": "11",
"HotelName": "Regal Orb Resort & Spa",
"Tags": [
"free wifi",
"restaurant",
"24-hour front desk service"
]
},
{
"@search.score": 2.166792,
"HotelId": "10",
"HotelName": "Countryside Hotel",
"Tags": [
"24-hour front desk service",
"coffee in lobby",
"restaurant"
]
},
...
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á filtr a pořadí řazení u pole Hodnocení (Hodnocení je filtrovatelné i řaditelné), 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=2023-11-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 "Lady of the Lake B & B".
Pokud chcete získat další 5, přeskočte první dávku:
POST /indexes/hotels-sample-index/docs/search?api-version=2023-11-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 hodnotu 5 a pak v každém novém požadavku zvýšíte skip o 5 (skip=5, skip=10, skip=15 atd.).
"value": [
{
"@search.score": 1.0,
"HotelName": "Pull'r Inn Motel",
"Rating": 4.7
},
{
"@search.score": 1.0,
"HotelName": "Sublime Cliff Hotel",
"Rating": 4.6
},
{
"@search.score": 1.0,
"HotelName": "Antiquity Hotel",
"Rating": 4.5
},
{
"@search.score": 1.0,
"HotelName": "Nordick's Motel",
"Rating": 4.5
},
{
"@search.score": 1.0,
"HotelName": "Winter Panorama Resort",
"Rating": 4.5
}
]
Další kroky
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: