フルテキスト検索のシナリオでは、Azure AI 検索は 2 つの Lucene ベースのクエリ言語を実装します。各言語はクエリ パーサーにアラインされています。 Simple Query Parser が既定です。 完全に構成されていない場合でも、一般的なユース ケースと要求の解釈の試行について説明します。 もう 1 つのパーサーは Lucene クエリ パーサー であり、より高度なクエリ構築をサポートしています。
この記事は、単純なクエリ パーサーのクエリ構文リファレンスです。
両方のパーサーのクエリ構文は、クエリ要求のsearch パラメーターで渡されるクエリ式に適用されます。OData 構文と混同しないでください。また、同じ要求内のfilter式とorderby式に対する独自の構文と規則を使用します。
単純パーサーは Apache Lucene Simple Query Parser クラスに基づいていますが、Azure AI 検索でのその実装ではあいまい検索は除外されます。 あいまい検索が必要な場合は、代わりに完全な Lucene クエリ構文を検討してください。
例 (単純な構文)
この例では、 "queryType": "simple" と有効な構文によって区別される単純なクエリを示します。 クエリの種類は以下に設定しますが、これは既定値であり、別の型から戻さない限り省略できます。 次の例は、一致するすべてのドキュメントに "pool" が含まれている必要がある、独立した用語を検索する例です。
POST https://{{service-name}}.search.windows.net/indexes/hotel-rooms-sample/docs/search?api-version=2025-09-01
{
"queryType": "simple",
"search": "budget hotel +pool",
"searchMode": "all"
}
この例では、 searchMode パラメーターが関連しています。 ブール演算子がクエリ上にある場合は常に、searchMode=all条件が一致するようにを設定する必要があります。 それ以外の場合は、精度よりも再現率を優先する既定の searchMode=any を使用できます。
その他の例については、 単純なクエリ構文の例を参照してください。 クエリ要求とパラメーターの詳細については、「ドキュメントの 検索 (REST API)」を参照してください。
用語および語句のキーワード検索
search パラメーターに渡される文字列は、サポートされている任意の言語の用語または語句、ブール演算子、優先順位演算子、「で始まる」クエリ用のワイルドカードまたはプレフィックス文字、エスケープ文字、そして URL エンコード文字を含むことができます。
search パラメーターは省略可能です。 指定されていない検索 (search=* または search=" ") は、任意の (ランクなし) 順序で上位 50 個のドキュメントを返します。
用語検索は 1 つ以上の用語のクエリであり、どの用語も一致と見なされます。
語句検索は、
" "引用符で囲まれた正確な語句です。 たとえば、Roach Motel(引用符なし) では、任意の順序でRoachやMotelを含むドキュメントを検索しますが、"Roach Motel"(引用符付き) は、その語句全体を含むドキュメントのみをその順序で照合します (字句分析は引き続き適用されます)。
検索クライアントによっては、語句検索で引用符をエスケープすることが必要になる場合があります。 たとえば、POST 要求では、要求本文の "Roach Motel" に対するフレーズ検索を "\"Roach Motel\""として指定できます。 Azure SDKを使用している場合、検索クライアントは検索テキストをシリアル化するときに引用符をエスケープします。 検索語句は"Roach Motel" として送信できます。
既定では、 search パラメーターで渡されるすべての文字列は字句解析を受けます。 使用しているアナライザーのトークン化動作を理解していることを確認します。 多くの場合、クエリ結果が予期しない場合、理由はクエリ時に用語がどのようにトークン化されるかまでトレースできます。 特定の 文字列でトークン化をテスト して、出力を確認できます。
1 つ以上の用語を含むテキスト入力は、クエリ実行の有効な開始点と見なされます。 Azure AI 検索は、テキストの分析中に見つかったバリエーションを含め、用語のいずれかまたはすべてを含むドキュメントを見つけることができます。
このように簡単に言えば、Azure AI 検索にはクエリ実行の 1 つの側面があり、mightは、入力文字列に追加される用語や演算子が増えるにつれて検索結果を減らすのではなく、増加し、予期しない結果を生成します。 この拡張が実際に発生するかどうかは、NOT 演算子の組み込みと、searchModeまたはAND動作の観点から NOT がどのように解釈されるかを決定するOR パラメーター設定と組み合わせることによって異なります。 詳細については、「ブール演算子」の「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=allではなくsearchMode=anyを使用することを検討してください。また、ユーザーが検索で - 演算子を頻繁に使用する場合は、検索の精度を最適化する必要があります。
searchMode設定を決定するときは、さまざまなアプリケーションのクエリのユーザー操作パターンを検討してください。 情報を検索しているユーザーは、より組み込みのナビゲーション構造を持つ e コマース サイトではなく、クエリに演算子を含める可能性が高くなります。 |
プレフィックス クエリ
"starts with" クエリの場合は、用語の残りの部分を表すプレースホルダーとしてサフィックス演算子 (*) を追加します。 プレフィックス クエリは、サフィックス演算子を追加する前に、少なくとも 1 つのプレーン テキスト文字で始まる必要があります。
| 文字 | 例 | 使用 |
|---|---|---|
* |
lingui* は「linguistic」または「linguini」と一致します |
アスタリスク (*) は、大文字小文字を区別せずに、任意の長さの 1 文字以上の文字を表します。 |
フィルターと同様に、プレフィックス クエリは完全一致を検索します。 そのため、関連性スコアはありません (すべての結果に 1.0 の検索スコアが表示されます)。 特にインデックスが大きく、プレフィックスが少数の文字で構成されている場合は、プレフィックス クエリが遅くなる可能性があることに注意してください。 エッジ n グラムトークン化などの代替手法の方が、パフォーマンスが向上する場合があります。 プレフィックス検索を使用する用語は、1,000 文字を超えることはできません。
単純な構文では、プレフィックスの一致のみがサポートされます。 用語の末尾または中間に対してサフィックスまたはインフィックスの照合を行うには、 ワイルドカード検索に完全な Lucene 構文を使用します。
検索演算子のエスケープ
単純な構文では、検索演算子には次の文字が含まれます。 + | " ( ) ' \
これらの文字のいずれかがインデックス内のトークンの一部である場合は、クエリで単一の円記号 (\) を先頭に付けてエスケープします。 たとえば、用語トークン化全体にカスタム アナライザーを使用し、インデックスに文字列 "Luxury+Hotel" が含まれているとします。 このトークンで完全一致を取得するには、エスケープ文字 ( search=luxury\+hotel) を挿入します。
より一般的なケースで簡単にするために、エスケープが必要ないこの規則には 2 つの例外があります。
NOT 演算子
-は、空白文字の後の最初の文字である場合にのみエスケープする必要があります。-が中央 (たとえば、3352CDD0-EF30-4A2E-A512-3B30AF40F3FD) に表示される場合は、エスケープをスキップできます。サフィックス演算子
*は、空白文字の前の最後の文字である場合にのみエスケープする必要があります。*が中央 (たとえば、4*4=16) に表示される場合、エスケープは必要ありません。
メモ
既定では、標準アナライザーは字句解析中にハイフン、空白文字、アンパサンド、その他の文字を削除したり、区切ったりして単語を処理します。 クエリ文字列に特殊文字を残す必要がある場合は、インデックスに保持するアナライザーが必要な場合があります。 一部の選択肢には、Microsoft自然な言語アナライザーが含まれます。ハイフンで区切られた単語が保持されます。また、より複雑なパターンの場合はカスタム アナライザーが使用されます。 詳細については、「 部分用語、パターン、および特殊文字」を参照してください。
URL での安全でない文字と予約文字のエンコード
すべての安全でない文字と予約文字が URL でエンコードされていることを確認します。 たとえば、'#' は URL のフラグメント/アンカー識別子であるため、安全でない文字です。 URL で使用する場合は、文字を %23 にエンコードする必要があります。 '&' と '=' は、パラメーターを区切り、Azure AI 検索で値を指定する予約文字の例です。 詳細については、「 RFC1738: Uniform Resource Locators (URL)」を参照してください。
安全でない文字が " ` < > # % { } | \ ^ ~ [ ]。 予約文字は ; / ? : @ = + &。
特殊文字
特殊文字の範囲は、'$' や '€' などの通貨記号から絵文字までです。 既定の標準アナライザーを含む多くのアナライザーでは、インデックス作成中に特殊文字が除外されます。つまり、特殊文字はインデックスで表されません。
特殊文字表現が必要な場合は、それらを保持するアナライザーを割り当てることができます。
空白アナライザーは、空白で区切られた文字シーケンスをトークンと見なします (そのため、'❤' 絵文字はトークンと見なされます)。
言語アナライザー (Microsoft 英語アナライザー (
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内の句の最大数 (AND または OR で区切られた式) は 1024 です。 - 検索語句の最大サイズは、 プレフィックス検索の場合は 1000 文字です。
- また、クエリ内の個々の用語のサイズには約 32 KB の制限があります。
クエリの制限の詳細については、「 API 要求の制限」を参照してください。
次の手順
プログラムでクエリを作成する場合は、Azure AI 検索 での全文検索を確認し、クエリ処理の段階とテキスト分析の影響を理解してください。
クエリの構築の詳細については、次の記事を参照してください。