Azure AI 検索 での Lucence クエリ構文

Azure AI 検索 でクエリを作成する場合、ワイルドカード、あいまい検索、近接検索、正規表現など、特殊なクエリ フォームに対して 完全な Lucene Query Parser 構文を選択できます。 Lucene Query Parser 構文の多くは、Azure AI 検索 でそのまま実装されています。ただし、範囲検索は例外で、これは $filter 式を介して構築されます。

完全な Lucene 構文を使用するには、queryType を full に設定し、ワイルドカード、あいまい検索、または完全な構文でサポートされている他のクエリ形式のいずれかのクエリ式を渡します。 REST では、クエリ式はsearch 要求の パラメーターで指定されます。

例 (完全な構文)

次の例は、完全な構文を使用して構成された検索要求です。 この特定の例では、フィールド検索とフレーズ ブーストを示します。 カテゴリ フィールドに budget という用語が含まれているホテルを検索します。 フレーズを含むドキュメント "recently renovated" 追加のブーストウェイトを受け取り、フレーズブースト値 (3) の結果として上位にランク付けされる可能性があります。

POST /indexes/hotels-sample/docs/search?api-version=2026-04-01
{
  "queryType": "full",
  "search": "category:budget AND \"recently renovated\"^3",
  "searchMode": "all"
}

どのクエリの種類にも固有ではありませんが、この例では searchMode パラメーターが関連しています。 クエリに演算子があるときは、通常 searchMode=all を設定して、すべての条件が確実に一致するようにします。

その他の例については、Lucene クエリ構文の例に関する記事をご覧ください。 searchMode を含む、クエリ要求とパラメーターの詳細については、ドキュメントの検索 (REST API) に関するページを参照してください。

構文の基礎

次の構文の基礎は、Lucene 構文を使用するすべてのクエリに適用されます。

コンテキストでの演算子評価

配置によって、記号を演算子と解釈するか、または文字列内の 1 つの文字と解釈するかが決まります。

たとえば、Lucene の完全構文では、チルダ (~) はあいまい検索と近接検索の両方に使用されます。 引用符で囲まれた語句の後に配置されると、~ は近接検索を呼び出します。 用語の末尾に配置されると、~ はあいまい検索を呼び出します。

business~analyst のような用語内では、この文字は演算子として評価されません。 この場合は、このクエリが用語または語句のクエリであると想定して、字句解析を使用する完全なテキスト検索によって、~ が削除され、business~analyst の用語が、2つ (business または analyst) に分割されます。

上記の例ではチルダ (~) ですが、すべての演算子に同じ原則が適用されます。

特殊文字のエスケープ

検索文字列の一部として検索演算子を使用するには、円記号 (\) 1 つを前に付けて文字をエスケープします。 たとえば、https:// のワイルドカード検索で、:// がクエリ文字列の一部である場合、search=https\:\/\/* を指定します。 同様に、エスケープされた電話番号パターンは、\+1 \(800\) 642\-7676 のようになります。

エスケープが必要な特殊文字には次の例があります。
+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /

URL での安全でない文字および予約文字のエンコード

安全でない文字および予約文字はすべて、URL でエンコードするようにしてください。 たとえば、# は、URL 内のフラグメント ID またはアンカー ID のため、安全でない文字です。 この文字を URL で使用する場合は、%23 にエンコードする必要があります。 & と = は、予約された文字の例です。これらの文字は、Azure AI 検索 でパラメーターを区切り、値を指定します。 詳しくは、RFC1738: Uniform Resource Locators (URL) に関するページをご覧ください。

安全でない文字は " ` < > # % { } | \ ^ ~ [ ] です。 予約文字は ; / ? : @ = + & です。

ブール演算子

照合の精度を向上させるために、クエリ文字列にブール演算子を埋め込むことができます。 完全な構文は、文字演算子に加え、テキスト演算子をサポートします。 テキスト ブール演算子 (AND、OR、NOT) は、常に大文字で指定します。

¹| 文字は、OR 演算ではサポートされていません。

NOT 論理演算子

• 単純な構文では、否定を含むクエリには常にワイルドカードが自動的に追加されます。 たとえば、クエリ -luxury は自動的に -luxury * に拡張されます。
• 完全な構文では、否定を含むクエリをワイルドカードと組み合わせることはできません。 たとえば、クエリ -luxury * は使用できません。
• 完全な構文では、1 つの否定あるクエリは使用できません。 たとえば、クエリ -luxury は使用できません。
• 完全な構文では、否定は、検索モードに関係なく、常にクエリに AND が設定されているかのように動作します。
  • たとえば、完全な構文の完全な構文クエリ wifi -luxury では、wifi という用語を含むドキュメントのみがフェッチされたあと、それらのドキュメントに否定 -luxury が適用されます。
• 否定を使用してインデックス内のすべてのドキュメントを検索する場合は、any 検索モードを使用した単純な構文をお勧めします。
• 否定を使用してインデックス内のドキュメントのサブセットを検索する場合は、完全な構文、またはすべての検索モードを使用した単純な構文をお勧めします。

フィールド検索

fieldName:searchExpression 構文を使用して、フィールド検索操作を定義できます。検索式は、単一の単語、単一の語句、またはかっこで囲まれた複雑な式が可能であり、必要に応じてブール演算子も使用できます 例として、次のようなものがあります。

• genre:jazz NOT history

• artists:("Miles Davis" "John Coltrane")

複数の文字列を 1 つのエンティティとして評価する場合は、必ず両方の文字列を引用符で囲んでください。この場合は、artists フィールドで 2 人の異なるアーティストを検索します。

fieldName:searchExpression に指定されるフィールドは、searchable フィールドでなければなりません。 フィールド定義におけるインデックス属性の利用方法の詳細については、「インデックスの作成」を参照してください。

あいまい検索

あいまい検索を使用すると、2 つ以下の距離条件を満たす用語を最大 50 の用語まで拡張して、似た構造を持つ用語の一致を見つけることができます。 詳細については、あいまい検索に関するページを参照してください。

あいまい検索を実行するには、1 つの単語の終わりにチルダ記号 ~ を使用し、編集距離を指定する任意のパラメーターである 0 から 2 (既定値) の値を指定します。 たとえば、blue~ または blue~1 は blue、blues、glue を返します。

あいまい検索を適用できるのは用語だけであり、引用符で囲われた語句には適用できませんが、複数の部分から成る名前または語句の各用語に個別にチルダを追加できます。 たとえば、Unviersty~ of~ Wshington~ は、University of Washington とだけ一致します。

近接検索

近接検索は、ある文書で互いに近くにある言葉を検索します。 言葉の終わりにチルダ記号 ~ を挿入し、近接境界となる語数を続けます。 たとえば、"hotel airport"~5 では、ドキュメント内で互いに 5 語以内にある hotel と airport という用語が検索されます。

用語ブースト

検索は 2 つの手順と考えてください。 まず、一致するドキュメントAzure AI 検索検索します。 次に、それらの一致結果を順位付けします。 用語ブーストは、2 番目のステップにのみ影響します。クエリの 1 つの部分に一致するドキュメントを結果の上位に移動できます。

用語ブーストは、スコアリング プロファイルとは異なります。 ブーストは、現在のクエリの単語、語句、またはグループを優先します。 スコアリング プロファイルは、インデックスで定義されているルールに従って、フィールドまたはその他のインデックス コンテンツを優先します。

ブースト スコープ

優先するクエリの部分の直後にキャレット (^) と正の数を記述します。 たとえば、tax^2 は、tax を含むドキュメントを、ブーストされていない用語にのみ一致するドキュメントよりも上位に表示できます。 既定のブースト値は 1 です。 0.2などの 0 ~ 1 の値を使用して、マッチの重みを減らすこともできます。

句読点は、各命令が影響する単語を示します。

• フィールド名とコロン (フィールド プレフィックスと呼ばれます) は、単語、引用符で囲まれた語句、またはかっこで囲まれたグループの前に表示されます。 たとえば、content:はcontentフィールドを見るようにAzure AI 検索に指示します。
• ブースト ( ^2など) は、単語、引用符で囲まれた語句、またはかっこで囲まれたグループの後に表示されます。 Azure AI 検索マッチをランク付けするときに何を優先するかを伝えます。

次の表では、単語間のスペースがsearchMode=anyのように動作する既定のORを使用します。

searchMode=allでは、クエリ deferred tax^2では両方の単語が一致する必要があります。 ブーストは引き続き taxにのみ適用されます。 代わりにいずれかの単語と一致するには、 deferred OR tax^2を記述します。

フレーズまたはグループ全体をブーストする場合は、終わり引用符またはかっこの後にキャレットを配置します。 括弧は語句を形成しません。 単語が隣り合う必要がある場合は、特定の順序で引用符を使用します。

ブーストとフィールド スコープ

フィールド名の後にコロンを付けると、Azure AI 検索 が検索対象とする場所が限定されます。 ブーストによって、Azure AI 検索がマッチをランク付けする方法が変わります。 両方を同じクエリで使用できます。

たとえば、searchFieldsが title に設定されている場合、最初のクエリでは deferred 内のcontentが検索され、taxでtitleが検索されます。 他のクエリの引用符とかっこは、両方の単語を contentに保持します。

ブーストクエリに対するアナライザの影響

通常の単語、語句、および単語のグループの場合、ブーストではテキスト分析はスキップされません。 一致する前に、Azure AI 検索は各フィールドのアナライザーでクエリ テキストを処理します。 その結果、異なるアナライザーを使用するフィールドでは、同じブースト テキストの一致が異なる場合があります。

フィールド プレフィックスを持つ語句またはグループは、そのフィールドのアナライザーを使用します。 フィールド プレフィックスのないテキストでは、検索対象のフィールドごとにアナライザーが使用されます。 たとえば、テキストを小文字に変更するアナライザーは、 "DEFERRED TAX"^2 を小文字のインデックス付き用語と一致させることができます。

ワイルドカード、正規表現、あいまいクエリなどの他のクエリ フォームでは、さまざまな分析ルールが使用されます。 ブーストを追加しても、これらのルールは変更されません。 詳細については、「 ステージ 2: 字句解析」を参照してください。

正規表現検索

正規表現検索では、RegExp クラスに関するページで説明されているように、Apache Lucene で有効なパターンに基づいて一致が検出されます。

Azure AI 検索 での正規表現は次のとおりです。

• スラッシュ / の間で囲む
• 小文字のみ

たとえば、motel または hotel を含むドキュメントを検索するには、/[mh]otel/ を指定します。 正規表現検索では、単一の単語に対して照合が行われます。

一部のツールと言語では、Azure AI 検索 によって適用されるエスケープ ルールを超えて追加のエスケープ文字の要件が適用されます。 JSON の場合、スラッシュを含む文字列は、バック スラッシュでエスケープされます。たとえば、microsoft.com/azure/ は、search=/.*microsoft.com\/azure\/.*/ となります。ここでは、search=/.* <string-placeholder>.*/ は、正規表現を設定し、microsoft.com\/azure\/ は、エスケープされたスラッシュを含む文字列です。

正規表現クエリの 2 つの一般的な記号は、. と * です。 . は任意の 1 文字に一致し、* は前の文字に 0 回以上一致します。 たとえば、/be./ は bee と bet という用語に一致しますが、/be*/ は be、bee、beee と一致しますが、bet とは一致しません。 組み合わせると、.* は任意の一連の文字を一致させることができるので、/be.*/ は be などの better で始まる用語と一致します。

正規表現で構文エラーが発生した場合、特殊文字のエスケープ ルールを見直します。 別のクライアントを試すと、問題がツール固有であるかどうかを確認することもできます。

ワイルドカード検索

複数 (*) または単数 (?) の文字のワイルドカード検索で、一般に認識されている構文を使用できます。 完全な Lucene 構文では、プレフィックスとインフィックスの一致がサポートされています。 サフィックスの一致には、正規表現構文を使用します。

Lucene Query Parser では、これらの文字を語句ではなく 1 つの用語に利用することにご注意ください。

演算子をひとつの式に結合できます。 たとえば、980?2* は、98072-1222 と 98052-1234 に一致します。ここでは、? は、単一文字 (必須) に一致し、* は、その後に続く任意の長さの文字に一致します。

サフィックスの一致には、正規表現のスラッシュ / 区切り記号が必要です。 一般に、* なしで、用語の最初の文字として ? または / 記号を使用することはできません。 また、* は正規表現クエリ以外で使用すると動作が異なる場合があるのでご注意ください。 正規表現のスラッシュ / 区切り記号外では、* はワイルドカード文字であり、正規表現の .* とほぼ同じように、任意の一連の文字に一致します。 たとえば、search=/non.*al/ では search=non*al と 同じ結果セットが生成されます。

ワイルドカード クエリに対するアナライザーの影響

クエリの解析中には、プレフィックス、サフィックス、ワイルドカードとして定式化されたクエリ、または正規の式は、語彙分析をバイパスして、クエリ ツリーにそのまま渡されます。 クエリで指定した形式の文字列がインデックスに含まれている場合に限って、一致が検出されます。 部分一致やパターンをうまく検出するためには、ほとんどの場合、文字列の整合性を維持するインデックスの作成時にアナライザーが必要になります。 詳細については、「Azure AI 検索 クエリでの部分一致検索」を参照してください。

検索クエリ terminal* を使用して、terminate、termination および terminates などの用語を含む結果を返したいとします。

en.lucene (English Lucene) アナライザーを使用する場合、各用語の語幹処理が積極的に適用されます。 たとえば、terminate、termination、terminates はすべて、インデックスではトークン termi にトークン化されます。 一方、ワイルドカードやあいまい検索を使用するクエリの用語はまったく分析されません。そのため、terminat* クエリに一致する結果はありません。

一方、Microsoft analyzers (この場合、en.microsoft アナライザー) はもう少し高度であり、語幹処理の代わりに見出し語選定が使用されます。 つまり、生成されたトークンはすべて正しい英単語になります。 たとえば、terminate、terminates、termination はほとんどの場合、インデックスに全体として残り、ワイルドカードやあいまい検索に多く依存するシナリオに最適です。

ワイルドカード クエリと正規表現クエリのスコアリング

Azure AI 検索 は、テキスト クエリで、頻度に基づいたスコアリング (BM25) を使用します。 ただし、用語のスコープが広くなる可能性があるワイルドカード クエリと正規表現クエリでは、出現頻度が低い用語の一致に対する優先度付けに偏りが発生するのを避けるために、頻度の係数は無視されます。 すべての一致は、ワイルドカード検索と正規表現検索で同等に扱われます。

特殊文字

場合によっては、"❤" のような絵文字や "€" のような記号などの特殊文字を検索することが必要です。 そのような場合は、使用しているアナライザーによってそれらの文字が除外されないことを確認します。標準アナライザーでは多くの特殊文字が無視され、インデックスから除外されます。

特殊文字をトークン化するアナライザーには、whitespace アナライザーが含まれ、ここでは、空白で区切られた任意の文字シーケンスがトークンとして考慮されます (したがって ❤ という文字列はトークンと見なされます)。 また、Microsoft English アナライザー ("en.microsoft") のような言語アナライザーでは、"€" という文字列がトークンとして見なされます。 アナライザーをテストして、特定のクエリに対して生成されるトークンを確認できます。

Unicode 文字を使用する場合は、クエリ URL でシンボルが適切にエスケープされていることを確認します (たとえば、❤ の場合は、エスケープ シーケンス %E2%9D%A4+ を使用します)。 一部の REST クライアントでは、この変換が自動的に行われます。

優先順位 (グループ化)

かっこを使用して、クエリのどの部分をまとめて評価するかを制御します。 たとえば、motel AND (wifi OR luxury)motelとかっこ内の用語のうち少なくとも 1 つ (wifiまたはluxury) が必要です。

1 つのフィールドでグループ全体を検索するには、かっこで分類されたグループの前にフィールド プレフィックスを配置します。 たとえば、hotelAmenities:(wifi OR pool)は、wifi フィールドでのみpoolまたはhotelAmenitiesを検索します。

括弧は、AND と OR の組み合わせ方を制御します。 単語を隣り合わせて表示したり、特定の順序で表示したりする必要はありません。 その動作には引用符を使用します。 グループをブーストするには、 hotelAmenities:(wifi OR pool)^2のように、閉じかっこの後にキャレットを配置します。 詳細については、「 ブースト スコープ」を参照してください。

クエリ サイズの上限

Azure AI 検索 では、無制限のクエリによって Search Service が不安定になるおそれがあるため、クエリのサイズと構成に制限が適用されます。 クエリのサイズと構成 (句の数) には制限があります。 制限は、プレフィックス検索の長さと、正規表現検索およびワイルドカード検索の複雑さにもあります。 アプリケーションがプログラムで検索クエリを生成する場合は、無制限のサイズのクエリが生成されないように設計することをお勧めします。

クエリの制限の詳細については、「API 要求の制限」を参照してください。

こちらも参照ください

• 単純な検索のクエリ例
• 完全な Lucene 検索のクエリの例
• ドキュメントを検索する
• フィルターと並べ替え向け OData 式の構文
• Azure AI 検索 の単純なクエリ構文