Azure AI Search での単純なクエリ構文

フルテキスト検索シナリオの場合、Azure AI Search は 2 つの Lucene ベースのクエリ言語を実装します。それぞれがクエリ パーサーにアラインされます。 単純なクエリ パーサーが規定です。 完全に構成されていない場合でも、一般的なユース ケースと要求に対応して解釈の試行を行います。 もう 1 つのパーサーは Lucene クエリ パーサーであり、より高度なクエリ構築をサポートしています。

この記事は、単純なクエリ パーサーのクエリ構文リファレンスです。

どちらのパーサーも、クエリ要求の search パラメーターで渡されるクエリ式に適用されます。同じ要求内の filter および orderby 式に使用される構文とルールを持つ OData 構文と混同しないでください。

単純なパーサーは Apache Lucene Simple Query Parser クラスに基づいていますが、Azure AI Search における実装では、あいまい検索が除外されています。 あいまい検索を使用する必要がある場合は、代わりに代替の完全な Lucene クエリ構文をお勧めします。

例 (単純な構文)

この例は、"queryType": "simple" と有効な構文で区別される単純なクエリを示しています。 クエリの種類は下に設定されていますが、これは既定値であり、代替の型から元に戻す場合を除き、省略できます。 次の例は、一致するすべてのドキュメントに "pool" が含まれていることを要件とした、独立した用語の検索です。

POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2024-07-01
{
  "queryType": "simple",
  "search": "budget hotel +pool",
  "searchMode": "all"
}

searchMode パラメーターは、この例で関連しています。 クエリにブール演算子があるときは、通常 searchMode=all を設定して、すべての条件が確実に一致するようにします。 それ以外の場合は、精度を超える再現率を優先する既定の searchMode=any を使用できます。

その他の例については、単純なクエリ構文の例に関する記事をご覧ください。 クエリ要求とパラメーターの詳細については、「ドキュメントの検索 (REST API)」をご覧ください。

用語と語句のキーワード検索

search パラメーターに渡される文字列には、サポートされている任意の言語の用語や語句、ブール演算子、優先順位演算子、"次で始まる" クエリに対するワイルドカードまたはプレフィックス文字、エスケープ文字、URL エンコード文字を含めることができます。 search パラメーターは省略可能です。 指定されていない場合、search (search=* または search=" ") は、上位 50 のドキュメントを任意の (ランク付けされていない) 順序で返します。

• 用語検索は、1 つ以上の用語のクエリで、いずれかの用語が一致と見なされます。

• 語句検索は引用符 " " で囲まれた完全に一致する語句です。 たとえば、Roach Motel (引用符なし) では、Roach と Motel (またはそのいずれか) を含むドキュメントが検索されます。その場合、語句が指定されている場所と順序は関係ありません。一方、"Roach Motel" (引用符あり) では、その語句全体を一緒に、その順序で含むドキュメントだけに一致します (字句解析は適用されます)。

検索クライアントによっては、語句検索で引用符をエスケープすることが必要になる場合があります。 たとえば、POST 要求では、要求本文内の "Roach Motel" での語句検索が "\"Roach Motel\"" として指定される場合があります。 Azure SDK を使用している場合、検索クライアントは検索テキストをシリアル化するときに引用符をエスケープします。 検索語句は "Roach Motel" として送信できます。

既定では、search パラメーターで渡されるすべての用語または語句は字句解析を受けます。 使用しているアナライザーのトークン化動作を理解していることを確認してください。 多くの場合、クエリ結果が予期しないものであるときには、クエリ時に用語をトークン化した方法にまで、その理由をトレースできます。 特定の文字列でトークン化をテストして、出力を確認できます。

1 つ以上の用語を含むテキスト入力はすべて、クエリ実行の有効な開始ポイントと見なされます。 Azure AI Search は、テキストの分析中に検出されたバリエーションを含め、それらの用語の一部またはすべてを含むドキュメントと一致します。

簡単に思われるかもしれませんが、Azure AI Search でのクエリ実行には、入力文字列に追加される用語および演算子が増えるにつれて、検索結果が減るのではなく増えるという、予期しない結果を生み出す 可能性がある 1 つの側面があります。 この拡張が実際に行われるかどうかは、NOT 演算子の組み込みと、AND または OR の動作の観点から NOT の解釈方法を決定する searchMode パラメーター設定の組み合わせで決まります。 詳細については、「ブール演算子」で NOT 演算子をご覧ください。

ブール演算子

照合の精度を向上させるために、クエリ文字列にブール演算子を埋め込むことができます。 単純な構文では、ブール演算子は文字ベースです。 テキスト演算子 (AND など) はサポートされていません。

文字	例	使用方法
+	pool + ocean	AND 演算子。 たとえば、pool + ocean は、ドキュメントに両方の用語が含まれている必要があることを規定します。
|	pool | ocean	OR 演算子は、いずれかの用語が見つかった場合に一致を検索します。 この例では、クエリ エンジンは、pool または ocean のいずれか、あるいはその両方を含むドキュメントに対して一致を返します。 OR は、既定の結合演算子のため、除外することもできます。たとえば、pool ocean は pool | ocean と同等です。
-	pool – ocean	NOT 演算子は、用語を除外するドキュメントに対して一致を返します。 クエリ要求の searchMode パラメーターによって、NOT 演算子を含む用語を、クエリ内の他の用語と AND 演算するか OR 演算するかが制御されます (他の用語にブール演算子がないと仮定します)。 有効な値は、any または all です。 searchMode=any にすると、より多くの結果を含めることによりクエリの再現率が増加し、既定で - は "OR NOT" と解釈されます。 たとえば、pool - ocean は、pool という用語を含むドキュメント、または ocean という用語を含まないもののどちらにも一致します。 searchMode=all にすると、より少ない結果を含めることによりクエリの精度が上がり、既定で - は "AND NOT" と解釈されます。 たとえば、searchMode=any を使用する場合、クエリ pool - ocean は "pool" という用語を含むドキュメントと、"ocean" という用語を含まないすべてのドキュメントと一致します。 これはほぼ間違いなく、- 演算子にとってより直感的な動作です。 したがって、再現率ではなく精度で検索を最適化し、"かつ" ユーザーが検索で - 演算子を頻繁に使用する場合は、searchMode=any よりも searchMode=all を選択することを検討してください。 searchMode 設定を決定するときは、さまざまなアプリケーションでのクエリのユーザー操作パターンを検討してください。 情報を検索するユーザーは、より多くの組み込みのナビゲーション構造を持つ eコマース サイトとは対照的に、クエリに演算子を含める可能性が高くなります。

プレフィックス クエリ

"次の文字で始まる" クエリの場合は、語句の残りの部分のプレースホルダーとしてサフィックス演算子 (*) を追加します。 プレフィックス クエリは、サフィックス演算子を追加する前に、少なくとも 1 つの英数字で始まる必要があります。

文字	例	使用方法
*	lingui* は、"linguistic" または "linguini" で照合します	アスタリスク (*) は、大文字と小文字を区別しない、任意の長さの 1 つまたは複数の文字を表します。

フィルターと同様に、プレフィックス クエリは完全一致を検索します。 そのため、関連性スコアリングは存在しません (すべての結果が 1.0 の検索スコアを受け取ります)。 プレフィックス クエリは、遅い場合があることに注意してください。インデックスが大きく、プレフィックスが少ない文字数で構成されている場合は特にそうです。 エッジ n-gram トークン化などの別の方法の方が、実行速度が速いことがあります。 プレフィックス検索を使用する用語は、1,000 文字以下にする必要があります。

単純な構文は、プレフィックスの照合のみをサポートします。 語句の末尾または中間に対するサフィックスや挿入辞の照合の場合は、ワイルドカード検索に対して完全な Lucene 構文を使用します。

検索演算子のエスケープ

単純な構文では、検索演算子には次の文字が含まれます: + | " ( ) ' \

これらの文字のいずれかがインデックスのトークンの一部として含まれている場合、クエリ内では、その文字の前に 1 つの円記号 (\) を付けてエスケープします。 たとえば、用語の完全なトークン化のためにカスタム アナライザーを使用し、インデックスに文字列 "Luxury+Hotel" が含まれているとします。 このトークンと完全に一致するものを取得するには、search=luxury\+hotel のようにエスケープ文字を挿入します。

より標準的なケースで操作を簡単にするために、この規則には、エスケープが不要な次の 2 つの例外があります。

• NOT 演算子 - のエスケープが必要なのは、スペースの後の最初の文字である場合のみです。 - が途中に現れる場合 (たとえば、3352CDD0-EF30-4A2E-A512-3B30AF40F3FD) は、エスケープをスキップできます。

• サフィックス演算子 * は、スペースの前の最後の文字である場合にのみ、エスケープする必要があります。 * が途中に現れる場合 (たとえば、4*4=16)、エスケープは必要ありません。

Note

標準のアナライザーでは、既定により、字句解析の際にハイフン、スペース、アンパサンド、およびその他の文字で単語が削除されたり、分割されたりします。 クエリ文字列内に特殊文字を残す必要がある場合は、それらをインデックス内に保持するアナライザーが必要になることがあります。 選択肢には、ハイフンでつながれた単語を保持する Microsoft 自然言語アナライザーや、より複雑なパターン用のカスタム アナライザーなどが含まれます。 詳細については、部分的な語句、パターン、特殊文字に関する記事を参照してください。

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

安全でない文字および予約文字はすべて、URL でエンコードするようにしてください。 たとえば、"#" は、URL ではフラグメント ID またはアンカー ID であるため、安全な文字ではありません。 この文字を URL で使用する場合は、%23 にエンコードする必要があります。 '&' と '=' は、Azure AI Search でパラメーターを区切り、値を指定する予約文字の例です。 詳細については、「 RFC1738: Uniform Resource Locators (URL)」を参照してください。

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

特殊文字

特殊文字の範囲は、"$" や "€" などの通貨記号から絵文字までです。 既定の標準アナライザーを含む多くのアナライザーでは、インデックス作成中に特殊文字が除外されます。つまり、インデックスで表されません。

特殊文字表現が必要な場合は、それらを保持するアナライザーを割り当てることができます。

• 空白アナライザーは、空白で区切られた文字シーケンスをトークンと見なします (そのため、'❤' 絵文字はトークンと見なされます)。

• Microsoft English アナライザー (en.microsoft) などの言語アナライザーでは、'$' や '€' という文字列がトークンとして見なされます。

確認のために、アナライザーをテスト して、特定の文字列に対して生成されるトークンを確認できます。 予想されるように、1 つのアナライザーから完全なトークン化を受け取らない場合があります。 回避策は、同じコンテンツを含む複数のフィールドを作成することですが、アナライザーの割り当てが異なります (たとえば、description_en、description_fr など)。

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

優先順位 (グループ化)

かっこを使用して、かっこで囲まれたステートメント内に演算子を含むサブクエリを作成できます。 たとえば、motel+(wifi|luxury) を指定すると、"motel" という用語と "wifi" または "luxury" (あるいはその両方) を含むドキュメントが検索されます。

クエリ サイズの上限

アプリケーションがプログラムで検索クエリを生成する場合は、無制限のサイズのクエリが生成されないように設計することをお勧めします。

• GET の場合、URL の長さは 8 KB を超えることはできません。

• POST (およびその他の要求) の場合で、要求の本文に search と、filter や orderby などの他のパラメーターが含まれている場合、最大サイズは 16 MB です。 追加の制限は次のとおりです。

  • 検索句の最大長は 100,000 文字です。
  • search 内の句の最大数は 1,024 個です (AND または OR で 区切られた式)。
  • プレフィックス検索における検索用語の最大サイズは、1,000 文字です。
  • クエリ内の個々の用語のサイズにも約 32 KB の制限があります。

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

次のステップ

プログラムを使用してクエリを作成する場合は、「 Azure AI Search でのフル テキスト検索 」を確認して、クエリ処理の段階とテキスト分析の影響について理解します。

また、クエリ構築の詳細について、次の記事をご覧ください。

• 単純な検索のクエリ例
• 完全な Lucene 検索のクエリの例
• Search Documents REST API
• Lucene クエリ構文
• (OData) 式構文のフィルター処理と選択