Azure AI 搜尋服務中的「簡單」搜尋查詢範例

發行項
01/19/2024

在 Azure AI 搜尋中，簡單的查詢語法會叫用預設查詢剖析器進行全文搜索。剖析器快速處理常見案例，包括全文搜索、篩選和多面向搜尋，以及前置詞搜尋。本文使用範例來說明搜尋檔（REST API）要求中的簡單語法用法。

注意

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

旅館範例索引

下列查詢是以 hotels-sample-index 為基礎，您可以依照本快速入門中的指示來建立。

範例查詢會使用 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=2023-11-01

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

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

設定為 * 的「search」是未指定的查詢，相當於 Null 或空白搜尋。它並不特別有用，但它是最簡單的搜尋，它會顯示索引中所有可擷取的欄位，其中包含所有值。
“queryType” 設為 “simple” 是預設值，可以省略，但包含進一步強化本文中的查詢範例以簡單語法表示。
[選取] 設定為以逗號分隔的欄位清單用於搜尋結果組合，包括那些在搜尋結果內容中很有用的欄位。
“count” 會傳回符合搜尋準則的文件數目。在空的搜尋字串上，計數是索引中的所有檔（hotels-sample-index 中為 50 份）。

範例 1：全文搜索

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

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
}

由重要字詞或片語組成的關鍵詞搜尋通常最適合使用。字串欄位會在編制索引和查詢期間進行文字分析，捨棄 “the”、“and”、“ it” 等無內性字組。若要查看查詢字串如何在索引中標記化，請在分析文字呼叫中傳遞字串至索引。

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

「集區 spa +機場」查詢的回應看起來應該類似下列範例，為了簡潔起見而修剪。

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

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

因為搜尋不是全文搜索，或是沒有提供任何準則，因此會發生「1.0」的統一分數。例如，在空的搜尋中（search=*），數據列會以任意順序傳回。當您包含實際準則時，您會看到搜尋分數演變成有意義的值。

範例 2：依標識碼查閱

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

GET /indexes/hotels-sample-index/docs/41?api-version=2023-11-01

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

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

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

範例 3：篩選文字

篩選語法是一種 OData 表達式，您可以單獨或搭配 search使用。一起使用時， filter 會先套用至整個索引，然後在篩選結果上執行搜尋。因此，篩選條件可能是改善查詢效能的實用技術，因為它們可減少搜尋查詢需要處理的檔集。

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

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
}

上述查詢的響應範圍僅限於分類為「報告及 Spa」的旅館，且包含「藝術」或「旅遊」等詞彙。在此情況下，只有一個相符專案。

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

範例 4：篩選函式

篩選表達式可以包含「search.ismatch」和「search.ismatchscoring」函式，可讓您在篩選內建置搜尋查詢。此篩選表達式會使用免費通配符來選取設施，包括免費wifi、停車等等。

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
  }

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

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

範例 5：範圍篩選

範圍篩選是透過篩選任何數據類型的表達式所支援。下列範例說明數值和字串範圍。數據類型在範圍篩選中很重要，當數值數據位於數值欄位，以及字元串欄位中的字串數據時，最適合使用。字串欄位中的數值資料不適用於範圍，因為數值字串無法比較。

下列查詢是數值範圍。在 hotels-sample-index 中，唯一可篩選的數值欄位是 Rating。

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
}

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

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

下一個查詢是字串字段的範圍篩選（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
}

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

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

範例 6：地理空間搜尋

hotels-sample 索引包含具有緯度和經度座標的位置字段。此範例會使用 geo.distance 函式，篩選起點周長內的檔，並篩選到您提供的任意距離（以公里為單位）。您可以調整查詢中最後一個值（10），以減少或放大查詢的表面區域。

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
}

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

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

範例 7：使用 searchMode 的布爾值

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

在先前的範例中， searchMode 參數被引入為影響精確度和召回的機制， "searchMode": "any" 並偏向召回（符合任何準則的文件被視為相符專案），以及「searchMode=all」偏向精確度（所有準則都必須在檔中相符）。

在布爾搜尋的內容中，如果您以多個運算子堆棧查詢，並取得更廣泛的而非較窄的結果，則預設值 "searchMode": "any" 可能會造成混淆。這與 NOT 特別正確，其中結果會包含所有「不包含」特定字詞或片語的檔。

下列範例提供一個實例。使用 searchMode 執行下列查詢（任何），會傳回 42 份檔：包含 “restaurant” 一詞的檔，以及沒有“空調”一詞的所有檔。

請注意，布爾運算符（-）與「空調」一詞之間沒有空格。

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
}

變更以 "searchMode": "all" 強制對準則產生累積效果，並傳回較小的結果集（7 個相符專案），其中包含“restaurant”一詞的檔，減去包含“空調”一詞的檔。

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

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

範例 8：分頁結果

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

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

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

查詢會尋找 21 份相符的檔，但因為您指定 top，回應只會傳回前五個相符專案，評等從 4.9 開始，並以 “Lake B & B 夫人” 結束為 4.7。

若要取得下一個 5，請略過第一個批次：

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
}

第二批的回應會略過前五場比賽，傳回接下來的五場比賽，從 “Pull'r Inn Motel” 開始。若要繼續更多批次，您會保留 top 5，然後在每個新要求上遞增 skip 5（skip=5、skip=10、skip=15 等等）。

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

下一步

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

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

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