Azure AI 搜尋中的簡單搜尋查詢範例

發行項
11/02/2024

在 Azure AI 搜尋服務中，簡單查詢語法會叫用預設查詢剖析器進行全文檢索搜尋。剖析器速度快，可處理常見案例，包括全文檢索搜尋、篩選搜尋、多面向搜尋和前置詞搜尋。本文使用範例來說明搜尋文件 (REST API) 要求中的簡單語法使用方式。

注意

替代查詢語法為 Lucene，可支援更複雜的查詢結構，例如模糊和通配符搜尋。如需詳細資訊，請參閱完整 Lucene 搜尋語法的範例。

飯店範例索引

下列查詢是以 hotels-sample-index 為基礎，您可以依照快速入門：在 Azure 入口網站中建立搜尋索引中的指示來建立。

範例查詢會使用 REST API 和 POST 要求來表達。您可以在 REST 用戶端貼上並加以執行。或者，在 Azure 入口網站中使用 [搜尋總管] 的 JSON 檢視。在 JSON 檢視中，您可以貼上本文此處所示的查詢範例。

要求標頭必須具有下列值：

機碼	值
內容-類型	application/json
api-key	`<your-search-service-api-key>` (查詢或系統管理金鑰)

URI 參數必須包含具有索引名稱、文件集合、搜尋命令和 API 版本的搜尋服務端點，類似於下列範例：

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

要求本文應形成為有效的 JSON：

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

search 設定為 * 是未指定的查詢，相當於 Null 或空白搜尋。這並不特別有用，但這是您可以執行的最簡單搜尋，而且其會顯示索引中所有可擷取的欄位，以及所有值。
queryType 設定為 simple 是預設值，可以省略，但包含強調本文中的查詢範例會以簡單語法表示。
select 設定為逗號分隔的欄位清單會用於搜尋結果組合，包括那些在搜尋結果內容中很有用的欄位。
count 會傳回符合搜尋準則的檔數目。在空的搜尋字串上，此計數將會是索引中的所有文件 (在 hotels-sample-index 中，計數為 50)。

範例 1：全文檢索搜尋

全文搜索可以是任意數目的獨立字詞或引號括住的片語，且不含布爾運算符。

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
}

由重要字詞或片語組成的關鍵字搜尋通常是最適合的。字串欄位會在編制索引和查詢期間進行文字分析，捨棄類似 的無用字，以及。 若要查看查詢字串如何在索引中標記化，請在 Analyze Text 呼叫中，將字串傳遞至索引。

參數 searchMode 會控制精確度和召回率。如果您想要更重新叫用，請使用預設值任何值，如果符合查詢字串的任何部分，則會傳回結果。如果您偏好有效位數，其中必須比對字串的所有部分，請將變更 searchMode 為 all。嘗試上述查詢兩種方式，以查看 searchMode 如何變更結果。

集區 spa + 機場查詢的回應看起來應該類似下列範例。

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

請注意回應中的搜尋分數。這是相符項目的相關性分數。根據預設，搜尋服務會根據此分數傳回前 50 個相符項目。

當沒有排名時，會以 1.0 的統一分數發生，可能是因為搜尋不是全文搜索，或是沒有提供任何準則。例如，在空白搜尋 (search= *) 中，資料列會依任意順序返回。當您包含實際準則時，您會發現搜尋分數逐漸具有其實質意義。

範例 2︰依識別碼查閱

傳回搜尋結果之後，邏輯下一個步驟是提供詳細數據頁面，其中包含檔中更多字段。此範例示範如何藉由傳入文件標識碼，使用取得檔傳回單一檔。

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

所有文件都有唯一識別碼。如果您使用 Azure 入口網站，請從 [索引] 索引標籤中選取索引，然後查看欄位定義，以判斷哪個欄位是索引鍵。在 REST API 中，GET Index 呼叫會傳回響應主體中的索引定義。

上述查詢的回應包含索引鍵為 41 的檔。在索引定義中標示為可擷取的任何字段，都可以在搜尋結果中傳回，並在應用程式中轉譯。

{
    "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：篩選文字

篩選語法是您可搭配 search 使用或單獨使用的 OData 運算式。在相同的要求中一起使用時， filter 會先套用至整個索引，然後在 search 篩選結果上執行。由於篩選能夠減少搜尋查詢需要處理的資料集合，因此對於提升查詢效能方面是很實用的技術。

您可以在索引定義中標示為 filterable 的任何欄位上定義篩選條件。對於 hotels-sample-index，可篩選的欄位包括 Category、Tags、ParkingIncluded、Rating 和大部分的 Address 欄位。

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
}

上述查詢的響應範圍僅限於分類為「精品」的酒店，並包含藝術或旅遊詞彙。在此情況下，只有一個相符項目。

"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：篩選函式

篩選表達式可以包含 search.ismatch 和 search.ismatchscoring 函式，可讓您在篩選內建置搜尋查詢。此篩選條件運算式會針對 free 使用萬用字元來選取便利設施，包含免費 wifi、免費停車等。

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
  }

上述查詢的回應會比對 27 家提供免費設施的酒店。請注意，搜尋分數是整個結果中的統 一 1 。這是因為搜尋運算式為 Null 或空白，導致逐字篩選條件相符，但全文檢索搜尋則否。相關性分數只會在全文檢索搜尋時傳回。如果您使用沒有 search 的篩選條件，請確定您有足夠的可排序欄位，以便控制搜尋排名。

  "@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︰範圍篩選條件

範圍篩選是透過適用於任何資料類型的篩選條件運算式來支援。下列範例說明數值和字串範圍。資料類型在範圍篩選條件中很重要，而當數值資料位於數值欄位且字串資料位於字串欄位時效果最好。字串欄位中的數值資料不適合用於範圍，因為數值字串無法比較。

下列查詢是數值範圍。在 hotels-sample-index 中，唯一可篩選的數值欄位是 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
}

此查詢的回應看起來應該類似下列範例，為了簡潔起見而修剪。

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

下一個查詢是字串欄位 (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
}

此查詢的回應看起來應該類似下列範例，為了簡潔起見而修剪。在此範例中，無法排序依據 StateProvince ，因為欄位在索引定義中不會屬性為可排序。

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

範例 6：地理空間搜尋

hotels-sample-index 包含 具有緯度和經度座標的位置 字段。這個範例會使用 geo.distance 函式，以篩選起始點周圍以至您提供的任意距離 (以公里為單位) 內的文件。您可以調整查詢 (10) 中的最後一個值，以縮小或放大查詢的介面區。

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
}

此查詢的回應會傳回所提供座標距離 10 公里以內的所有旅館：

{
  "@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︰使用 searchMode 的布林值

簡單語法支援以字元形式（+, -, |）的布爾運算符，以支援AND、OR和NOT查詢邏輯。布林搜尋的行為會如預期般運作，但有一些值得注意的例外狀況。

在布爾搜尋中，請考慮將參數新增 searchMode 為影響精確度和召回的機制。有效值包括 "searchMode": "any" 偏好重新叫用（符合任何準則的文件視為相符專案），以及 "searchMode": "all" 偏向精確度（文件中必須符合所有準則）。

在布林搜尋的執行內容中，如果您以多個運算子堆疊查詢，並取得較廣泛的結果 (而非較狹隘的結果)，預設 "searchMode": "any" 可能會造成混淆。這特別適用於NOT，其中結果包含不包含特定字詞或片語的所有檔。

下列範例提供一個實例。查詢會尋找排除空調片語之餐廳的相符專案。如果您使用 searchMode 執行下列查詢（任何），則會傳回 43 份檔：包含一詞餐廳的檔，以及沒有語句 *空調的所有檔。

請注意，布爾運算符（-）與片語空調之間沒有空間。引號會逸出（\"）。

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"強制對準則產生累積效果，並傳回較小的結果集（七個相符專案），其中包含包含餐廳一詞的檔，減去包含空調片語的檔。

此查詢的響應現在看起來會類似下列範例，為了簡潔起見而修剪。

{
  "@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：分頁結果

在先前的範例中，您已了解影響搜尋結果組合的參數，包括 select，此參數可決定結果中的欄位、排序次序，以及如何包含所有相符項目的計數。此範例是分頁參數形式之搜索結果組合的延續，可讓您批次處理出現在任何指定頁面中的結果數目。

根據預設，搜尋服務會傳回前 50 個相符項目。若要控制每個頁面中的符合項目數，請使用 top 來定義批次的大小，然後使用 skip 來挑選後續的批次。

下列範例會在欄位上使用 Rating 篩選和排序順序（Rating 是可篩選和可排序的），因為更容易看到分頁對排序結果的影響。在一般完整搜尋查詢中，最符合的相符項目會依 @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
}

查詢會尋找 21 個相符的檔，但由於您指定 top，回應只會傳回前五個相符專案，評等從 4.9 開始，並以 4.7 結束，而 Lakeside B 和 B 則以 4.7 結束。

若要取得接下來的五個，請略過第一個批次：

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
}

第二批的回應會略過前五場比賽，返回接下來的五場比賽，從 提取旅館汽車旅館開始。若要繼續進行更多批次，您會保留 top 五個批次，然後在每個新要求上遞增 skip 5 個（skip=5，skip=10，skip=15 等等）。

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

現在您已使用基本查詢語法進行一些練習，請嘗試以程式碼指定查詢。下列連結說明如何使用 Azure SDK 設定搜尋查詢。

快速入門：使用 Azure SDK 進行全文檢索搜尋

您可以在下列連結中找到其他語法參考、查詢架構和範例：

共用方式為

Azure AI 搜尋中的簡單搜尋查詢範例

飯店範例索引

範例 1：全文檢索搜尋

範例 2︰依識別碼查閱

範例 3：篩選文字

範例 4：篩選函式

範例 5︰範圍篩選條件

範例 6：地理空間搜尋

範例 7︰使用 searchMode 的布林值

範例 8：分頁結果

意見反應

其他資源

共用方式為

Azure AI 搜尋中的簡單搜尋查詢範例

飯店範例索引

範例 1：全文檢索搜尋

範例 2︰依識別碼查閱

範例 3：篩選文字

範例 4：篩選函式

範例 5︰範圍篩選條件

範例 6：地理空間搜尋

範例 7︰使用 searchMode 的布林值

範例 8：分頁結果

相關內容

意見反應

其他資源