Megosztás a következőn keresztül:

Példák egyszerű keresési lekérdezésekre az Azure AI Searchben

  • Cikk

Az Azure AI Searchben az egyszerű lekérdezési szintaxis meghívja az alapértelmezett lekérdezéselemzőt a teljes szöveges kereséshez. Az elemző gyors, és kezeli a gyakori forgatókönyveket, beleértve a teljes szöveges keresést, a szűrt és a faceted keresést, valamint az előtagkeresést. Ez a cikk példákkal szemlélteti a keresési dokumentumok (REST API) kéréseinek egyszerű szintaxishasználatát.

Feljegyzés

Egy másik lekérdezési szintaxis a Lucene, amely összetettebb lekérdezési struktúrákat támogat, például a homályos és a helyettesítő karaktereket. További információ: Példák a teljes Lucene-keresés szintaxisára .

Hotelek mintaindexe

A következő lekérdezések a hotels-sample-indexen alapulnak, amelyet a gyorsútmutató utasításait követve hozhat létre: Keresési index létrehozása az Azure Portalon.

A példa-lekérdezések a REST API és a POST kérések használatával vannak tagoltan. Beillesztheti és futtathatja őket egy REST-ügyfélben. Vagy használja a Kereséskezelő JSON-nézetét az Azure Portalon. JSON nézetben beillesztheti a cikkben bemutatott lekérdezési példákat.

A kérelemfejléceknek a következő értékekkel kell rendelkezniük:

Kulcs Érték
Content-Type application/json
api-key <your-search-service-api-key>, lekérdezés vagy rendszergazdai kulcs

Az URI-paramétereknek tartalmazniuk kell a keresési szolgáltatás végpontját az index nevével, a dokumentumgyűjteményekkel, a keresési paranccsal és az API-verzióval, az alábbi példához hasonlóan:

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

A kérelem törzsét érvényes JSON-ként kell formázni:

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

  • search értéke * egy meghatározatlan lekérdezés, amely null értékű vagy üres keresésnek felel meg. Ez nem különösen hasznos, de ez a legegyszerűbben elvégezhető keresés, és az index összes beolvasható mezőjét megjeleníti az összes értékkel együtt.

  • queryTypeaz egyszerű beállítás az alapértelmezett érték, amely kihagyható, de azt is ki kell emelni, hogy a cikkben szereplő lekérdezési példák az egyszerű szintaxisban vannak kifejezve.

  • select vesszővel tagolt mezőlistára van állítva a keresési eredmények összetétele, beleértve a keresési eredmények kontextusában hasznos mezőket is.

  • count A keresési feltételeknek megfelelő dokumentumok számát adja vissza. Üres keresési sztring esetén a szám az index összes dokumentuma (50 a hotels-sample-indexben).

1. példa: Teljes szöveges keresés

A teljes szöveges keresés tetszőleges számú önálló kifejezésből vagy idézőjelből álló kifejezés lehet logikai operátorokkal vagy anélkül.

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
}

A fontos kifejezésekből vagy kifejezésekből álló kulcsszókeresés általában a legjobban működik. A sztringmezők szövegelemzésen mennek keresztül az indexelés és a lekérdezés során, és elvetik az olyan nem fontos szavakat, mint az és azokat. Annak megtekintéséhez, hogy egy lekérdezési sztring hogyan van tokenizálva az indexben, adja át a sztringet egy Szövegelemzési hívásban az indexnek.

A searchMode paraméter vezérli a pontosságot és a visszahívást. Ha további visszahívásra van szüksége, használja az alapértelmezett értéket , amely eredményt ad vissza, ha a lekérdezési sztring bármely része megfeleltetve van. Ha a pontosságot részesíti előnyben, ahol a sztring minden részének egyeznie kell, váltson searchMode az összesre. Próbálja meg az előző lekérdezést mindkét módon, hogy lássa, hogyan módosítja a searchMode az eredményt.

A pool spa +airport lekérdezés válaszának az alábbi példához hasonlóan kell kinéznie.

"@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"
}
]

Figyelje meg a keresési pontszámot a válaszban. Ez a találat relevanciapontszáma. A keresési szolgáltatás alapértelmezés szerint a pontszám alapján adja vissza az 50 legjobb találatot.

Az egységes 1,0-s pontszámok akkor fordulnak elő, ha nincs rangsor, vagy azért, mert a keresés nem volt teljes szöveges keresés, vagy mert nem adtak meg feltételeket. Például egy üres keresésben (search=*) a sorok tetszőleges sorrendben térnek vissza. Ha tényleges feltételeket ad meg, a keresési pontszámok értelmes értékekké alakulnak.

2. példa: Keresés azonosító alapján

A keresési eredmények visszaadása után logikus következő lépésként meg kell adnia egy részletes lapot, amely a dokumentum további mezőit tartalmazza. Ez a példa bemutatja, hogyan adhat vissza egyetlen dokumentumot a Dokumentum lekérése funkcióval a dokumentumazonosító megadásával.

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

Minden dokumentum egyedi azonosítóval rendelkezik. Ha az Azure Portalt használja, jelölje ki az indexet az Indexek lapon, majd tekintse meg a meződefiníciókat annak meghatározásához, hogy melyik mező a kulcs. A REST API-ban a GET Index hívás a válasz törzsében lévő indexdefiníciót adja vissza.

Az előző lekérdezés válasza az a dokumentum, amelynek kulcsa 41. Az indexdefinícióban lekérdezhetőként megjelölt mezők visszaadhatók a keresési eredményekben, és megjeleníthetők az alkalmazásban.

{
    "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"
    }
}

3. példa: Szűrés szövegre

A szűrőszintaxis egy olyan OData-kifejezés, amelyet önmagában vagy a searchhasználatával is használhat. Ha ugyanabban a kérelemben együtt használják, filter a rendszer először a teljes indexre alkalmazza, majd a search szűrő eredményein hajtja végre. A szűrők éppen ezért hasznosak a lekérdezés teljesítményének javítására, mivel általuk lecsökkenthető a keresési lekérdezés által feldolgozandó dokumentumok köre.

A szűrők az indexdefinícióban megjelölt filterable bármely mezőn definiálhatók. A szállodai mintaindex esetében a szűrhető mezők közé tartozik a Kategória, a Címkék, a Parkolási cím, az Értékelés és a legtöbb Cím mező. 

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
}

Az előző lekérdezésre adott válasz csak a Butik kategóriába sorolt szállodákra terjed ki, amelyek tartalmazzák a művészeti vagy túrakifejezéseket. Ebben az esetben csak egy egyezés van.

"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"
}
]

4. példa: Szűrőfüggvények

A szűrőkifejezések tartalmazhatnak search.ismatch és search.ismatchscoring függvényeket, így létrehozhat egy keresési lekérdezést a szűrőn belül. Ez a szűrőkifejezés ingyenes helyettesítő karaktert használ a kényelmi funkciók kiválasztásához, beleértve az ingyenes wifit, az ingyenes parkolást és így tovább.

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
  }

Az előző lekérdezésre adott válasz 27 szállodával egyezik meg, amelyek ingyenes szolgáltatásokat kínálnak. Figyelje meg, hogy a keresési pontszám egységes 1 a találatok között. Ennek az az oka, hogy a keresési kifejezés null értékű vagy üres, ami szó szerinti szűrési egyezéseket eredményez, de nem tartalmaz teljes szöveges keresést. A relevanciaértékek csak teljes szöveges kereséssel jelennek meg. Ha szűrőket használ nélküle search, győződjön meg arról, hogy elegendő rendezhető mezővel rendelkezik, hogy szabályozhassa a keresési rangsort.

  "@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"
      ]
    },
. . .

5. példa: Tartományszűrők

A tartományszűrés bármilyen adattípus szűrőkifejezéseivel támogatott. Az alábbi példák numerikus és sztringtartományokat szemléltetnek. Az adattípusok fontosak a tartományszűrőkben, és akkor működnek a legjobban, ha numerikus adatok numerikus mezőkben, sztringadatok pedig sztringmezőkben találhatók. A sztringmezők numerikus adatai nem alkalmasak tartományokra, mert a numerikus sztringek nem összehasonlíthatók.

Az alábbi lekérdezés egy numerikus tartomány. A hotels-sample-indexben az egyetlen szűrhető numerikus mező a 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
}

A lekérdezésre adott válasznak a következő példához hasonlóan kell kinéznie, a rövidítés kedvéért levágva.

"@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
},
...

A következő lekérdezés egy tartományszűrő egy sztringmezőn (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
}

A lekérdezésre adott válasznak a következő példához hasonlóan kell kinéznie, a rövidítés kedvéért levágva. Ebben a példában nem lehet rendezést elvégezniStateProvince, mert a mező nem rendelhető rendezhetőként az indexdefinícióhoz.

{
  "@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 "
      }
    },
. . .

A hotels-sample-index tartalmaz egy Földrajzi hely mezőt szélességi és hosszúsági koordinátákkal. Ez a példa a geo.distance függvényt használja, amely a kiindulási pont kerületén belül szűri a dokumentumokat, egy tetszőleges távolságra (kilométerben), amelyet ön ad meg. A lekérdezés utolsó értékét (10) módosíthatja a lekérdezés felületének csökkentése vagy nagyítása érdekében.

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
}

A lekérdezésre adott válasz a megadott koordinátáktól 10 km-re lévő összes szállodát visszaadja:

{
  "@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"
      }
    }
  ]
}

7. példa: Logikai értékek a searchMode használatával

Az egyszerű szintaxis karakterek (+, -, |) formájában támogatja a logikai operátorokat az AND, OR és NOT lekérdezési logika támogatásához. A logikai keresés a várt módon viselkedik, néhány figyelemre méltó kivétellel.

Logikai keresés esetén fontolja meg a paraméter hozzáadását a pontosság és a searchMode visszahívás befolyásolására szolgáló mechanizmusként. Az érvényes értékek közé tartozik a "searchMode": "any" visszahívás előnyben részesítése (a feltételek bármelyikének megfelelő dokumentum egyezésnek minősül), valamint "searchMode": "all" a pontosság előnyben részesítése (minden feltételnek meg kell egyeznie egy dokumentumban).

A logikai keresés kontextusában az alapértelmezett beállítás "searchMode": "any" zavaró lehet, ha egy lekérdezést több operátorral halmoz fel, és a szűkebb eredmények helyett szélesebb lesz. Ez különösen igaz a NOT esetében, ahol az eredmények tartalmazzák az összes olyan dokumentumot , amely nem tartalmaz egy adott kifejezést vagy kifejezést.

Az alábbi példa egy illusztrációt tartalmaz. A lekérdezés olyan egyezéseket keres az étteremben, amelyek kizárják a légkondicionáló kifejezést. Ha a következő lekérdezést a searchMode (bármelyik) használatával futtatja, a rendszer 43 dokumentumot ad vissza: az étterem kifejezést tartalmazó dokumentumokat, valamint az összes olyan dokumentumot, amely nem tartalmazza a *légkondicionáló kifejezést.

Figyelje meg, hogy nincs térköz a logikai operátor (-) és a légkondicionáló kifejezés között. Az idézőjelek megmenekültek (\").

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
}

"searchMode": "all" A módosítás kumulatív hatást gyakorol a feltételekre, és egy kisebb eredményhalmazt (hét találatot) ad vissza, amely az étterem kifejezést tartalmazó dokumentumokból áll, a légkondicionáló kifejezést tartalmazók nélkül.

A lekérdezésre adott válasz most az alábbi példához hasonlóan fog kinézni, a rövidítés kedvéért levágva.

{
  "@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"
      ]
    },
...

8. példa: Lapozási eredmények

A korábbi példákban megismerhette a keresési eredmények összetételét befolyásoló paramétereket, többek között select azt, hogy mely mezők szerepelnek az eredményben, hogyan rendezheti a sorrendeket, és hogyan lehet belefoglalni az összes találat számát. Ez a példa a keresési eredmények összetételének folytatása lapozási paraméterek formájában, amelyek lehetővé teszik, hogy az adott oldalon megjelenő találatok számát kötegelje.

Alapértelmezés szerint a keresési szolgáltatás az első 50 találatot adja vissza. Az egyes lapok top egyezéseinek számának szabályozásához határozza meg a köteg méretét, majd vegye skip fel a további kötegeket.

Az alábbi példa egy szűrési és rendezési sorrendet használ a Rating mezőben (az értékelés szűrhető és rendezhető is), mert könnyebb látni a lapozásnak a rendezett eredményekre gyakorolt hatását. Egy normál teljes keresési lekérdezésben a rendszer a legfontosabb találatokat rangsorolja és lapozza @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
}

A lekérdezés 21 egyező dokumentumot talál, de mivel megadtatop, a válasz csak az első öt találatot adja vissza, a minősítések 4,9-nél kezdődnek, és 4,7-nél végződnek a Lakeside B > B-vel.

A következő öt lekéréséhez hagyja ki az első köteget:

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
}

A második köteg válasza kihagyja az első öt találatot, és a következő öt találatot adja vissza, kezdve a Pull'r Inn Motelnel. A további kötegek folytatásához ötnél kell tartania top a műveletet, majd minden új kérelemnél ötöt kell növelnie skip (skip=5, skip=10, skip=15 stb.).

{
  "@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
    }
  ]
}

Kapcsolódó tartalom

Most, hogy már rendelkezik némi gyakorlattal az alapszintű lekérdezési szintaxissal, próbálja meg kódban megadni a lekérdezéseket. Az alábbi hivatkozás bemutatja, hogyan állíthat be keresési lekérdezéseket az Azure SDK-k használatával.

További szintaxishivatkozások, lekérdezési architektúra és példák az alábbi hivatkozásokon találhatók: