Azure AI Search'te basit arama sorguları örnekleri

  • Makale

Azure AI Search'te basit sorgu söz dizimi , tam metin araması için varsayılan sorgu ayrıştırıcısını çağırır. Ayrıştırıcı hızlıdır ve tam metin araması, filtrelenmiş ve modelli arama ve ön ek araması gibi yaygın senaryoları işler. Bu makalede, Arama Belgeleri (REST API) isteğinde basit söz dizimi kullanımını göstermek için örnekler kullanılır.

Not

Alternatif sorgu söz dizimi, belirsiz ve joker karakter arama gibi daha karmaşık sorgu yapılarını destekleyen Lucene'dir. Daha fazla bilgi için bkz . Tam Lucene arama söz dizimi örnekleri.

Oteller örnek dizini

Aşağıdaki sorgular, Hızlı Başlangıç: Azure portalında arama dizini oluşturma başlığı altında verilen yönergeleri izleyerek oluşturabileceğiniz hotels-sample-index sorgularını temel alır.

Örnek sorgular REST API ve POST istekleri kullanılarak ifade edilir. Bunları bir REST istemcisinde yapıştırabilir ve çalıştırabilirsiniz. Alternatif olarak Azure portalında Arama gezgininin JSON görünümünü de kullanabilirsiniz. JSON görünümünde, bu makalede gösterilen sorgu örneklerini yapıştırabilirsiniz.

İstek üst bilgileri aşağıdaki değerlere sahip olmalıdır:

Anahtar Değer
İçerik Türü application/json
api-key <your-search-service-api-key>, sorgu veya yönetici anahtarı

URI parametreleri, aşağıdaki örneğe benzer şekilde dizin adı, belge koleksiyonları, arama komutu ve API sürümüne sahip arama hizmeti uç noktanızı içermelidir:

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

İstek gövdesi geçerli JSON olarak oluşturulmalıdır:

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

  • search * olarak ayarlanır, null veya boş aramaya eşdeğer belirtilmemiş bir sorgudur. Özellikle kullanışlı değildir, ancak yapabileceğiniz en basit aramadır ve dizindeki tüm alınabilir alanları ve tüm değerleri gösterir.

  • queryTypeayarı varsayılan değerdir ve atlanabilir, ancak bu makaledeki sorgu örneklerinin basit söz diziminde ifade edildiği vurgulanır.

  • select yalnızca arama sonuçları bağlamında yararlı olan alanlar da dahil olmak üzere arama sonucu oluşturma için virgülle ayrılmış alan listesine ayarlanır.

  • count arama ölçütleriyle eşleşen belge sayısını döndürür. Boş bir arama dizesinde, sayı dizindeki tüm belgelerdir (hotels-sample-index içinde 50).

Örnek 1: Tam metin araması

Tam metin araması, Boole işleçleriyle veya boole işleçleri olmadan herhangi bir sayıda tek başına terim veya tırnak içine alınmış tümcecik olabilir.

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
}

Önemli terimlerden veya tümceciklerden oluşan bir anahtar sözcük araması en iyi şekilde çalışır. Dize alanları dizin oluşturma ve sorgulama sırasında metin analizinden geçer ve ve gibi gereksiz sözcükleri bırakır. Bir sorgu dizesinin dizinde nasıl belirteç haline getirildiğine bakmak için, dizeyi bir Metin Analizi çağrısında dizine geçirin.

searchMode parametresi duyarlığı ve geri çekmeyi denetler. Daha fazla geri çekme istiyorsanız, sorgu dizesinin herhangi bir bölümü eşleşirse sonuç döndüren varsayılan değeri kullanın. Dizenin tüm bölümlerinin eşleşmesi gereken duyarlığı tercih ederseniz tümü olarak değiştirinsearchMode. SearchMode'un sonucu nasıl değiştirdiğini görmek için yukarıdaki sorguyu her iki yolu da deneyin.

Havuz spa +havaalanı sorgusu yanıtı aşağıdaki örneğe benzer olmalıdır.

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

Yanıttaki arama puanına dikkat edin. Bu, maçın ilgi puanıdır. Varsayılan olarak, arama hizmeti bu puana göre ilk 50 eşleşmeyi döndürür.

1,0'lık tekdüzen puanlar, sıralama olmadığında, arama tam metin araması olmadığından veya ölçüt sağlanmadığından oluşur. Örneğin, boş bir aramada (search=*), satırlar rastgele sırayla geri gelir. Gerçek ölçütleri eklediğinizde, arama puanlarının anlamlı değerlere dönüşmesiyle karşılaşırsınız.

Örnek 2: Kimliğine göre arama

Arama sonuçları döndürüldükten sonra, mantıksal bir sonraki adım belgeden daha fazla alan içeren bir ayrıntılar sayfası sağlamaktır. Bu örnekte, belge kimliğini geçirerek Belge Al'ı kullanarak tek bir belgenin nasıl döndürüleceği gösterilmektedir.

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

Tüm belgelerin benzersiz bir tanımlayıcısı vardır. Portalı kullanıyorsanız Dizinler sekmesinden dizini seçin ve ardından hangi alanın anahtar olduğunu belirlemek için alan tanımlarına bakın. REST API'de GET Index çağrısı yanıt gövdesindeki dizin tanımını döndürür.

Önceki sorgunun yanıtı, anahtarı 41 olan belgeden oluşur. Dizin tanımında alınabilir olarak işaretlenen tüm alan arama sonuçlarında döndürülebilir ve uygulamanızda işlenebilir.

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

Örnek 3: Metne göre filtreleme

Filtre söz dizimi , kendi başına veya ile searchkullanabileceğiniz bir OData ifadesidir. Aynı istekte birlikte kullanıldığında, filter önce tüm dizine uygulanır ve ardından search filtrenin sonuçları üzerinde gerçekleştirilir. Filtreler arama sorgusunun işlemesi gereken belge kümesini azalttığından, sorgu performansını iyileştirmeye yönelik kullanışlı bir teknik olabilir.

Filtreler, dizin tanımında olarak filterable işaretlenmiş herhangi bir alanda tanımlanabilir. Hotels-sample-index için, filtrelenebilir alanlar Kategori, Etiketler, ParkGerekli, Derecelendirme ve adres alanlarının çoğudır.

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
}

Önceki sorgunun yanıtının kapsamı yalnızca Butik olarak kategorilere ayrılmış olan ve resim veya tur terimlerini içeren oteller olarak belirlenmiştir. Bu durumda, yalnızca bir eşleşme vardır.

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

Örnek 4: Filtre işlevleri

Filtre ifadeleri search.ismatch ve search.ismatchscoring işlevlerini içerebilir ve filtre içinde bir arama sorgusu oluşturmanıza olanak sağlar. Bu filtre ifadesi ücretsiz wifi, ücretsiz otopark vb. gibi olanakları seçmek için ücretsiz joker karakter kullanır.

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
  }

Önceki sorgunun yanıtı, ücretsiz olanaklar sunan 27 otelle eşleşir. Arama puanının sonuçlar boyunca tekdüzen 1 olduğuna dikkat edin. Bunun nedeni, arama ifadesinin null veya boş olması ve tam metin araması yapılmaması ve tam filtre eşleşmesi ile sonuçlanmasıdır. İlgi puanları yalnızca tam metin aramada döndürülür. filtreleri olmadan searchkullanıyorsanız, arama derecesini denetleyebilmeniz için yeterli sıralanabilir alanınız olduğundan emin olun.

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

Örnek 5: Aralık filtreleri

Aralık filtreleme, herhangi bir veri türü için filtre ifadeleri aracılığıyla desteklenir. Aşağıdaki örneklerde sayısal ve dize aralıkları gösterilmektedir. Veri türleri, aralık filtrelerinde önemlidir ve sayısal veriler sayısal alanlarda ve dize alanlarında dize verileri olduğunda en iyi şekilde çalışır. Sayısal dizeler karşılaştırılabilir olmadığından, dize alanlarındaki sayısal veriler aralıklar için uygun değildir.

Aşağıdaki sorgu sayısal bir aralıktır. hotels-sample-index içinde filtrelenebilir tek sayısal alandır 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
}

Bu sorgunun yanıtı, kısa olması için kırpılmış aşağıdaki örneğe benzer görünmelidir.

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

Sonraki sorgu, bir dize alanı (Address/StateProvince) üzerinde bir aralık filtresidir:

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
}

Bu sorgunun yanıtı, kısa olması için kırpılmış aşağıdaki örneğe benzer görünmelidir. Bu örnekte, alan dizin tanımında sıralanabilir StateProvince olarak ilişkilendirilmediğinden sıralama ölçütü kullanılamaz.

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

hotels-sample-index, enlem ve boylam koordinatlarına sahip bir Konum alanı içerir. Bu örnekte, bir başlangıç noktasının çevresi içindeki belgelere filtre ekleyen geo.distance işlevi , sağladığınız rastgele bir uzaklığa (kilometre cinsinden) kadar kullanılır. Sorgunun yüzey alanını küçültmek veya büyütmek için sorgudaki son değeri (10) ayarlayabilirsiniz.

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
}

Bu sorgunun yanıtı, sağlanan koordinatların 10 kilometre mesafedeki tüm otelleri döndürür:

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

Örnek 7: SearchMode ile Booleanlar

Basit söz dizimi, VE, VEYA ve DEĞİl sorgu mantığını desteklemek için karakter (+, -, |) biçiminde Boole işleçlerini destekler. Boole araması, birkaç önemli özel durumla beklediğiniz gibi davranır.

Boole aramasında, parametreyi searchMode duyarlık ve yakalamayı etkilemek için bir mekanizma olarak eklemeyi göz önünde bulundurun. Geçerli değerler arasında "searchMode": "any" geri çekmeyi tercih etme (ölçütlerden herhangi birini karşılayan bir belge eşleşme olarak kabul edilir) ve "searchMode": "all" duyarlık (tüm ölçütlerin belgede eşleşmesi gerekir) bulunur.

Boole araması bağlamında, bir sorguyu birden çok işleçle yığıyorsanız ve daha dar sonuçlar yerine daha geniş alıyorsanız varsayılan değer "searchMode": "any" kafa karıştırıcı olabilir. Bu özellikle NOT ile geçerlidir; burada sonuçlar belirli bir terim veya tümcecik içermeyen tüm belgeleri içerir.

Aşağıdaki örnek, bir gösterim sağlar. Sorgu, klima ifadesini dışlayan restoranda eşleşmeleri arar. SearchMode (herhangi biri) ile aşağıdaki sorguyu çalıştırırsanız 43 belge döndürülür: restoran terimini içerenler ve *klima ifadesi olmayan tüm belgeler.

Boole operatörü (-) ile klima ifadesi arasında boşluk olmadığına dikkat edin. Tırnak işaretleri kaçış işaretidir (\").

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
}

Ölçütler üzerinde kümülatif bir etkiyi zorunlu kılıp "searchMode": "all" restoran terimini içeren belgelerden oluşan daha küçük bir sonuç kümesi (yedi eşleşme) döndürür ve klima ifadesini içerenler hariç.

Bu sorgunun yanıtı artık kısa olması için kırpılmış aşağıdaki örneğe benzer olacaktır.

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

Örnek 8: Sayfalama sonuçları

Önceki örneklerde, sonuç olarak hangi alanların bulunduğunu belirleme, sıralama düzenleri ve tüm eşleşmelerin sayısını dahil etme dahil olmak üzere select arama sonuçları bileşimini etkileyen parametreler hakkında bilgi edinmişsinizdir. Bu örnek, belirli bir sayfada görünen sonuç sayısını toplu olarak kullanmanıza olanak sağlayan sayfalama parametreleri biçiminde arama sonucu oluşturma işleminin devamıdır.

Varsayılan olarak, arama hizmeti ilk 50 eşleşmeyi döndürür. Her sayfadaki eşleşme sayısını denetlemek için öğesini kullanarak top toplu işlemin boyutunu tanımlayın ve ardından sonraki toplu işleri almak için kullanın skip .

Aşağıdaki örnekte, sıralama sonuçlarında sayfalamanın etkilerini görmek daha kolay olduğundan, alanda bir filtre ve sıralama düzeni Rating (Derecelendirme hem filtrelenebilir hem de sıralanabilir) kullanır. Normal bir tam arama sorgusunda, üst eşleşmeler tarafından derecelendirilir ve sayfalandırılır @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
}

Sorgu eşleşen 21 belge bulur, ancak belirttiğiniz topiçin yanıt yalnızca ilk beş eşleşmeyi döndürür; derecelendirmeler 4,9'dan başlar ve Lakeside B & B ile 4,7'de biter.

Sonraki beşi almak için ilk toplu işlemi atlayın:

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
}

İkinci toplu işlemin yanıtı, Pull'r Inn Motel'den başlayarak sonraki beş eşleşmeyi döndürerek ilk beş eşleşmeyi atlar. Daha fazla toplu işleme devam etmek için beşte tutar top ve her yeni istekte beş artırabilirsiniz skip (skip=5, skip=10, skip=15 vb.).

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

İlgili içerik

Artık temel sorgu söz dizimi konusunda biraz alıştırma yaptığınıza göre kodda sorgu belirtmeyi deneyin. Aşağıdaki bağlantı, Azure SDK'larını kullanarak arama sorguları ayarlamayı kapsar.

Aşağıdaki bağlantılarda daha fazla söz dizimi başvurusu, sorgu mimarisi ve örnek bulunabilir: