Azure AI Search の OData フルテキスト検索機能 - `search.ismatch` と `search.ismatchscoring`

2025-07-10

Azure AI Search では、 OData フィルター式のコンテキストでのフルテキスト検索がサポートされて、 search.ismatch関数とsearch.ismatchscoring 関数を介しています。これらの関数を使用すると、Search API の最上位レベルの search パラメーターを使用するだけでは不可能な方法で、フルテキスト検索と厳密なブール型フィルター処理を組み合わせることができます。

注

search.ismatch および search.ismatchscoring 関数は、Search API のフィルター内でのみサポートされます。これらは、 Suggest API または Autocomplete API ではサポートされていません。

構文

次の EBNF (拡張バッカス・ナウア記法) では、search.ismatch および search.ismatchscoring 関数の文法を定義しています。

search_is_match_call ::=
    'search.ismatch'('scoring')?'(' search_is_match_parameters ')'

search_is_match_parameters ::=
    string_literal(',' string_literal(',' query_type ',' search_mode)?)?

query_type ::= "'full'" | "'simple'"

search_mode ::= "'any'" | "'all'"

対話型の構文ダイアグラムも利用できます。

Azure AI Searchの OData 構文図

注

完全な EBNF については、Azure AI Searchの OData 式構文参照を参照してください。

search.ismatch

search.ismatch 関数では、フィルター式の一部としてフルテキスト検索クエリが評価されます。一致するドキュメントが結果セットに返されます。この関数の次のオーバーロードが利用できます。

search.ismatch(search)
search.ismatch(search, searchFields)
search.ismatch(search, searchFields, queryType, searchMode)

次の表では、各パラメーターを定義しています。

パラメーター名	タイプ	説明
`search`	`Edm.String`	検索クエリ (simple または full Lucene クエリ構文)。
`searchFields`	`Edm.String`	検索する検索可能フィールドのコンマ区切りリスト。既定値はインデックスのすべての検索可能フィールドになります。 `search` パラメーターでフィールド検索を使用すると、Lucene クエリのフィールド指定子によって、このパラメーターで指定されたすべてのフィールドがオーバーライドされます。
`queryType`	`Edm.String`	`'simple'` または `'full'`。既定値は `'simple'` です。 `search` パラメーターで使用されたクエリ言語を指定します。
`searchMode`	`Edm.String`	`'any'` または `'all'`。既定値は `'any'` です。ドキュメントを一致としてカウントするために、`search` パラメーター内の任意の検索語句またはすべての検索語句が一致する必要があるかどうかが示されます。 `search` パラメーターで Lucene Boolean 演算子を使用する場合は、このパラメーターよりも優先されます。

上記のパラメーターはすべて、それに対応するSearch API の検索要求パラメーターに等しくなります。

search.ismatch関数はEdm.Boolean型の値を返します。これにより、ブール論理演算子を使用して、他のフィルター部分式と共に作成できます。

注

Azure AI Search では、ラムダ式内での search.ismatch または search.ismatchscoring の使用はサポートされていません。つまり、フルテキスト検索の一致を同じオブジェクトの厳密なフィルター一致と関連付けることができるオブジェクトのコレクションにフィルターを書き込むことはできません。この制限と例の詳細については、「 Azure AI Search での収集フィルターのトラブルシューティング」を参照してください。この制限が存在する理由の詳細については、「 Azure AI Searchのコレクションフィルターについて」を参照してください。

search.ismatchscoring

search.ismatchscoring 関数では、search.ismatch 関数と同様に、パラメーターとして渡されたフルテキスト検索クエリに一致したドキュメントに対して true が返されます。これらの違いは、 search.ismatchscoring クエリと一致するドキュメントの関連性スコアがドキュメントスコア全体に影響するのに対し、 search.ismatchの場合、ドキュメントスコアは変更されないということです。この関数の次のオーバーロードは search.ismatch のそれと等しいパラメーターで利用できます。

search.ismatchscoring(search)
search.ismatchscoring(search, searchFields)
search.ismatchscoring(search, searchFields, queryType, searchMode)

search.ismatch 関数と search.ismatchscoring 関数の両方を同じフィルター式で使用できます。

例

"waterfront" という言葉の付いたドキュメントを探します。このフィルターはを指定したsearch=waterfrontと同じになります。

    search.ismatchscoring('waterfront')

この要求の完全なクエリ構文を次に示します。この構文は、Azure portal の Search Explorer で実行できます。出力は、ウォーターフロント、水、前面での一致で構成されます。

{
  "search": "*",
  "select": "HotelId, HotelName, Description",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatchscoring('waterfront')"
}

"pool" という単語と評価が 4 以上のドキュメント、または "motel" という単語が 3.2 に等しいドキュメントを検索します。この要求は、 search.ismatchscoring 関数なしでは表現できなかったことに注意してください。

    search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2

Search Explorer のこの要求の完全なクエリ構文を次に示します。出力は、評価が 4 より大きいプール、 または 評価が 3.2 のモーテルでの一致で構成されます。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatchscoring('pool') and Rating ge 4 or search.ismatchscoring('motel') and Rating eq 3.2"
}

"luxury" という言葉のないドキュメントを探します。

    not search.ismatch('luxury')

この要求の完全なクエリ構文を次に示します。出力は、ラグジュアリーという用語の一致で構成されます。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "not search.ismatch('luxury')"
}

"ocean" という語句または評価が 3.2 のドキュメントを検索します。 search.ismatchscoring クエリは、HotelNameおよびDescriptionフィールドに対してのみ実行されます。

この要求の完全なクエリ構文を次に示します。結合の 2 番目の句にのみ一致するドキュメントも返されます (具体的には、 Rating が 3.2 と等しいホテル)。これらのドキュメントが式のスコア付けされた部分のいずれとも一致しなかったことを明確にするために、スコアが 0 で返されます。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Rating",
  "searchMode": "all",
  "queryType": "full",
  "count": true,
  "filter": "search.ismatchscoring('ocean', 'Description,HotelName') or Rating eq 3.2"
}

出力は、説明またはホテル名に "ocean" と記載されているホテル、または評価が 3.2 のホテルの 4 つの一致で構成されます。 2 番目の句の一致の検索スコアが 0 であることに注意してください。

{
  "@odata.count": 4,
  "value": [
    {
      "@search.score": 1.6076145,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
      "Rating": 4.2
    },
    {
      "@search.score": 1.0594962,
      "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.",
      "Rating": 3.5
    },
    {
      "@search.score": 0,
      "HotelId": "40",
      "HotelName": "Trails End Motel",
      "Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "Rating": 3.2
    },
    {
      "@search.score": 0,
      "HotelId": "26",
      "HotelName": "Planetary Plaza & Suites",
      "Description": "Extend Your Stay. Affordable home away from home, with amenities like free Wi-Fi, full kitchen, and convenient laundry service.",
      "Rating": 3.2
    }
  ]
}

「ホテル」と「空港」という用語がホテルの説明で互いに5単語以内にあり、少なくとも一部の客室では喫煙が許可されていない文書を検索します。

    search.ismatch('"hotel airport"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)

完全なクエリ構文を次に示します。検索エクスプローラーで実行するには、円記号を使用して内部引用符をエスケープします。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatch('\"hotel airport\"~5', 'Description', 'full', 'any') and Rooms/any(room: not room/SmokingAllowed)"
}

出力は、"hotel" と "airport" という用語が 5 単語以内にある 1 つのドキュメントで構成されます。ほとんどのホテルでは、この検索結果に含まれる部屋を含め、複数の部屋で喫煙が許可されています。

{
  "@odata.count": 1,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "40",
      "HotelName": "Trails End Motel",
      "Description": "Only 8 miles from Downtown. On-site bar/restaurant, Free hot breakfast buffet, Free wireless internet, All non-smoking hotel. Only 15 miles from airport.",
      "Tags": [
        "bar",
        "free wifi",
        "restaurant"
      ],
      "Rating": 3.2
    }
  ]
}

[説明] フィールドで、文字 "lux" で始まる単語を含むドキュメントを検索します。このクエリでは、プレフィックス検索を search.ismatch と組み合わせて使用します。

    search.ismatch('lux*', 'Description')

完全なクエリを次に示します。

{
  "search": "*",
  "select": "HotelId, HotelName, Description, Tags, Rating",
  "searchMode": "all",
  "queryType": "simple",
  "count": true,
  "filter": "search.ismatch('lux*', 'Description')"
}

出力は、次の一致で構成されます。

{
  "@odata.count": 4,
  "value": [
    {
      "@search.score": 1,
      "HotelId": "18",
      "HotelName": "Ocean Water Resort & Spa",
      "Description": "New Luxury Hotel for the vacation of a lifetime. Bay views from every room, location near the pier, rooftop pool, waterfront dining & more.",
      "Tags": [
        "view",
        "pool",
        "restaurant"
      ],
      "Rating": 4.2
    },
    {
      "@search.score": 1,
      "HotelId": "13",
      "HotelName": "Luxury Lion Resort",
      "Description": "Unmatched Luxury. Visit our downtown hotel to indulge in luxury accommodations. Moments from the stadium and transportation hubs, we feature the best in convenience and comfort.",
      "Tags": [
        "bar",
        "concierge",
        "restaurant"
      ],
      "Rating": 4.1
    },
    {
      "@search.score": 1,
      "HotelId": "16",
      "HotelName": "Double Sanctuary Resort",
      "Description": "5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.",
      "Tags": [
        "view",
        "pool",
        "restaurant",
        "bar",
        "continental breakfast"
      ],
      "Rating": 4.2
    },
    {
      "@search.score": 1,
      "HotelId": "14",
      "HotelName": "Twin Vortex Hotel",
      "Description": "New experience in the making. Be the first to experience the luxury of the Twin Vortex. Reserve one of our newly-renovated guest rooms today.",
      "Tags": [
        "bar",
        "restaurant",
        "concierge"
      ],
      "Rating": 4.4
    }
  ]
}

次の方法で共有

Azure AI Search の OData フルテキスト検索機能 - search.ismatch と search.ismatchscoring

構文

search.ismatch

search.ismatchscoring

例

次のステップ

フィードバック

その他のリソース

Azure AI Search の OData フルテキスト検索機能 - `search.ismatch` と `search.ismatchscoring`