Azure AI 検索でフルテキストクエリを作成する

フルテキスト検索のクエリを作成する場合、この記事では要求を設定するための手順について説明します。また、クエリ構造の概要を示し、フィールド属性と言語アナライザーによってクエリ結果がどのような影響を受けるかについても説明します。

前提条件

Azure AI Search サービス (任意のレベル)。サービスの作成または既存のものを見。
searchable の属性が付けられた文字列フィールドを使用した検索インデックス。クエリ要求のエンドポイントとしてインデックスエイリアスを使用することもできます。
インデックスに対してクエリを実行するアクセス許可:
- キーベースの認証: あなたの検索サービス用クエリ API キー。
- ロールベースの認証: インデックスデータ閲覧者ロールを検索します。
SDK 開発の場合は、Azure Search クライアントライブラリをインストールします。
- Python: Azure-search-documents
- .NET: Azure。Search.Documents
- JavaScript: @Azure/search-documents
- Java: Azure-search-documents

ヒント

簡単なコード例については、「フルテキストクエリ要求の例」に進みます。

フルテキストクエリ要求の例

Azure AI 検索では、クエリは 1 つの検索インデックスのドキュメントコレクションに対する読み取り専用の要求であり、クエリの実行を通知し、応答が返されるようにするパラメーターを指定します。

フルテキストクエリはパラメーターで指定され、語句、引用符で囲まれたフレーズ、および演算子で構成されます。他のパラメーターを使用すると、要求に定義が追加されます。

次の Search POST REST API 呼び出しは、およびその他のパラメーターを使用したクエリ要求を示しています。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2025-09-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "top": 10,
    "count": true
}

リファレンス:POST の検索

重要なポイント

には一致条件を指定します。通常は用語全体またはフレーズですが、演算子が伴う場合も伴わない場合もあります。インデックススキーマで検索可能として属性付けされたフィールドは、検索操作のスコープ内にあります。
パーサーを設定します: 「単純」または「フル」。既定のシンプルなクエリパーサーは、フルテキスト検索に最適です。 Lucene の完全なクエリパーサーは、正規表現、近接検索、ファジー検索、ワイルドカード検索などの高度なクエリコンストラクトに適しています。このパラメーターは、クエリ応答での高度なセマンティックモデリングのためのセマンティックランク付け用に "semantic" に設定することもできます。
指定された式において、一致が「すべての条件」に基づくか（精度を優先）、もしくは「いずれかの条件」に基づくか（リコールを優先）を指定します。既定値は any です。大きなテキストブロック (コンテンツフィールドや長い記述) が含まれるインデックスでブール演算子の多用が懸念される場合は、パラメーターを使用してクエリをテストし、その設定がブール検索に与える影響を評価してください。
は、クエリの実行を特定の検索可能なフィールドに制限します。開発時には、選択と検索に同じフィールドリストを使用すると便利です。そうしないと、一致が結果に表示されないフィールド値に基づく可能性があり、ドキュメントが返された理由に対して不確実性が生じます。

応答を形成するために使用するパラメーター:

: 応答で返すフィールドを指定します。 select ステートメントでは、インデックスで "取得可能" とマークされたフィールドのみを使用できます。
: 指定した数の最もよく一致するドキュメントを返します。この例では、10 個のヒットのみが返されます。 top と skip (ここには非表示) を使用して、結果のページを移動することができます。
: すべてのインデックス全体で一致するドキュメントの数を示します。これは、返されるものよりも大きくなる可能性があります。有効な値は "true" または "false" です。既定値は "false" です。インデックスが安定している場合、カウントは正確であるものの、追加、更新、または削除が行われているドキュメントに対しては過少または過大報告されることがあります。ドキュメントなしでカウントのみを取得する場合は、$top=0 を使用できます。
: 評価や場所などの値によって結果を並べ替える場合に使用します。それ以外の場合、既定では、関連性スコアを使用して結果が順位付けされます。このパラメーターの候補となるには、このフィールドに "並べ替え可能" の属性が必要です。

クライアントを選択する

早期開発と概念実証テストの場合は、Azure portalまたは REST クライアントまたはJupyter Notebookから開始します。これらのアプローチは対話型であり、対象を絞ったテストに役立ち、コードを記述しなくてもさまざまなプロパティの効果を評価するのに役立ちます。

アプリ内から検索を呼び出すには、.NET、Java、JavaScript、Python 用の Azure SDK の Azure.Document.Search クライアントライブラリを使用します。

Azure portalでは、インデックスを開くときに、フィールド属性を簡単にaccessできるように、インデックス JSON 定義と共に検索エクスプローラーをサイドバイサイドタブで操作できます。 Fields テーブルを確認して、クエリのテスト中に、検索可能、並べ替え可能、フィルター可能、およびファセット可能なフィールドがどれかを確認します。

Azure portalにサインインし、search serviceを確認します。
サービスで、[インデックス] を選択し、インデックスを一つ選びます。
インデックスが [Search エクスプローラー] タブに開き、すぐに検索できます。 [JSON ビュー] に切り替えて、クエリ構文を指定します。

hotels-sample インデックスに対して機能するフルテキスト検索クエリ式を次に示します。
```
   {
       "search": "pool spa +airport",
       "queryType": "simple",
       "searchMode": "any",
       "searchFields": "Description, Tags",
       "select": "HotelName, Description, Tags",
       "top": 10,
       "count": true
   }
```
リファレンス:POST の検索

次のスクリーンショットはクエリと応答の例を示したものです。

フルテキストクエリが含まれている Search Explorer のスクリーンショット。

GET を使用して呼び出された場合、要求 URL の長さは 8 KB を超えることはできません。この長さは、ほとんどのアプリケーションで十分です。ただし、一部のアプリケーションでは、特に OData フィルター式が使用されている場合に、大規模なクエリが生成されます。これらのアプリケーションでは、HTTP POST は GET よりも大きなフィルターを許可するため、より優れた選択肢です。

POST では、POST の要求サイズ制限が約 16 MB であるため、フィルター内の句の数は制限要因であり、未加工のフィルター文字列のサイズではありません。 POST 要求サイズの制限が大きい場合でも、フィルター式を任意に複雑にすることはできません。フィルターの複雑さの制限の詳細については、「 OData 式の構文」を参照してください。

REST クライアントを使用して要求を設定します。始める際にヘルプが必要な場合は、「Quickstart: REST を使用したフルテキスト検索」を参照してください。

次の例では、フルテキスト検索の REST API を呼び出しています。

POST https://[service name].search.windows.net/indexes/hotels-sample/docs/search?api-version=2025-09-01
{
    "search": "NY +view",
    "queryType": "simple",
    "searchMode": "all",
    "searchFields": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "select": "HotelName, Description, Address/City, Address/StateProvince, Tags",
    "count": true
}

リファレンス:POST の検索

部分検索応答の継続

Azure AI 検索は、要求されたすべての結果を 1 つの検索応答で返さない場合があります。部分的な応答は、$topを指定しないか、大きすぎる $ top の値を指定することによって、クエリが返すドキュメントが多すぎる場合など、さまざまな理由で発生する可能性があります。このような場合、Azure AI 検索は応答本文に @odata.nextLink 注釈を含め、POST 要求の場合は @search.nextPageParametersも含めます。これらの注釈の値を使用して、別の検索要求を作成し、検索応答の次の部分を取得できます。この動作は、元の検索要求の継続と呼ばれ、注釈は継続トークンと呼ばれます。これらの注釈の構文と、それらが応答本文に表示される場所の詳細については、「応答」セクションの例を参照してください。

Azure AI 検索が継続トークンを返す理由は実装固有であり、変更される可能性があります。堅牢なクライアントは、予想よりも少ないドキュメントが返され、ドキュメントの取得を続行するために継続トークンが含まれている場合に常に対応できる状態にする必要があります。また、続行するには、元の要求と同じ HTTP メソッドを使用する必要があることにも注意してください。たとえば、GET 要求を送信した場合、送信するすべての継続要求でも GET を使用する必要があります (POST の場合も同様です)。

注

との目的は、ページングの一般的なメカニズムを提供せず、多すぎる結果を要求するクエリからサービスを保護することです。結果をページングする場合は、$topと$skipを一緒に使用します。たとえば、サイズが 10 のページが必要な場合、最初の要求には $top=10、$skip=0、2 番目の要求には $top=10、$skip=10、3 番目の要求には $top=10、$skip=20 などが必要です。

次の例では、Azure SDK を使用してフルテキストクエリを実行する方法を示します。

Python

from azure.core.credentials import AzureKeyCredential
from azure.search.documents import SearchClient

# Set up the client
service_name = "<your-search-service-name>"
index_name = "hotels-sample"
api_key = "<your-query-api-key>"

endpoint = f"https://{service_name}.search.windows.net"
credential = AzureKeyCredential(api_key)
client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)

# Run a full-text search query
results = client.search(
    search_text="NY +view",
    search_mode="all",
    search_fields=["HotelName", "Description", "Address/City", "Tags"],
    select=["HotelName", "Description", "Address/City", "Tags"],
    top=10,
    include_total_count=True
)

print(f"Total documents matching query: {results.get_count()}")
for result in results:
    print(f"Hotel: {result['HotelName']}")

Reference:SearchClient, search

C#

using Azure;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;

// Set up the client
string serviceName = "<your-search-service-name>";
string indexName = "hotels-sample";
string apiKey = "<your-query-api-key>";

Uri endpoint = new Uri($"https://{serviceName}.search.windows.net");
AzureKeyCredential credential = new AzureKeyCredential(apiKey);
SearchClient searchClient = new SearchClient(endpoint, indexName, credential);

// Run a full-text search query
SearchOptions options = new SearchOptions
{
    SearchMode = SearchMode.All,
    IncludeTotalCount = true,
    Size = 10
};
options.SearchFields.Add("HotelName");
options.SearchFields.Add("Description");
options.Select.Add("HotelName");
options.Select.Add("Description");

SearchResults<SearchDocument> response = await searchClient.SearchAsync<SearchDocument>("NY +view", options);

Console.WriteLine($"Total documents matching query: {response.TotalCount}");
await foreach (SearchResult<SearchDocument> result in response.GetResultsAsync())
{
    Console.WriteLine($"Hotel: {result.Document["HotelName"]}");
}

Reference:SearchClient, SearchAsync, SearchOptions

その他の SDK リソース

Azure SDK	クライアント	例一覧
.NET	SearchClient	DotNetHowTo
Java	SearchClient	SearchForDynamicDocumentsExample.java
JavaScript	SearchClient	SDK の例
Python	SearchClient	sample_simple_query.py

クエリの種類を選択する: simple | full

クエリがフルテキスト検索の場合、検索語句やフレーズとして渡されたテキストを処理するためにクエリパーサーが使用されます。 Azure AI 検索には、2 つのクエリパーサーが用意されています。

単純なパーサーは、単純なクエリ構文を認識します。このパーサーは、自由形式のテキストクエリの速度と有効性により既定で選択されています。この構文では、用語検索と語句検索に共通の検索演算子 (AND、OR、NOT) とプレフィックス () 検索をサポートしています (Seattle や Seaside に対するなど)。一般的には、最初に単純なパーサーを試してから、アプリケーションの要件でより強力なクエリが必要になる場合に完全なパーサーに移行することをお勧めします。
完全な Lucene クエリ構文は、を要求に追加したときに有効になり、Apache Lucene パーサーに基づいています。

完全な構文と単純な構文は、両方が同じプレフィックスとブール演算をサポートしているという点で重複しますが、完全な構文のほうがより多くの演算子を用意しています。完全では、ブール式の演算子や、あいまい検索、ワイルドカード検索、近接検索、正規表現などの高度なクエリ用の演算子が多数用意されています。

クエリメソッドを選択する

検索は基本的にユーザー主導の動作であり、検索ボックスから、またはページでのクリックイベントから、用語や語句が収集されます。次の表は、予想される検索エクスペリエンスと共にユーザー入力を収集するためのメカニズムをまとめたものです。

入力	エクスペリエンス
検索メソッド	ユーザーは、演算子の有無にかかわらず検索ボックスに用語または語句を入力し、[検索] をクリックして要求を送信します。検索は同じ要求でフィルターと共に使用できますが、オートコンプリートや提案と共には使用できません。
オートコンプリートメソッド	ユーザーがいくつかの文字を入力すると、新しい文字が入力されるたびにクエリが開始されます。応答は、インデックスからの完成した文字列になります。指定された文字列が有効な場合、ユーザーは [検索] をクリックしてそのクエリをサービスに送信します。
提案メソッド	オートコンプリートと同様に、ユーザーがいくつかの文字を入力すると、増分クエリが生成されます。応答は一致したドキュメントのドロップダウンリストであり、通常はいくつかの一意または説明のフィールドで表されます。いずれかの選択が有効な場合、ユーザーが 1 つを選択すると、一致したドキュメントが返されます。
ファセットナビゲーション	ページには、クリック可能なナビゲーションリンクまたは階層リンクが表示され、検索範囲を絞り込むことができます。ファセットナビゲーション構造は、初期クエリに基づいて動的に構成されます。たとえば、可能なすべてのカテゴリから構成されるファセットナビゲーションツリーを生成します。ファセットナビゲーション構造はクエリ応答から作成されますが、次のクエリを表現するためのメカニズムでもあります。 REST API リファレンスでは、は、ドキュメントの検索操作のクエリパラメーターとして記述されていますが、パラメーターを指定せずに使用できます。
フィルターメソッド	フィルターは、結果を絞り込むためにファセットと共に使用されます。また、ページの背後にフィルターを実装することもでき、たとえば、言語固有のフィールドでページを初期化することができます。 REST API リファレンスでは、はドキュメントの検索操作のクエリパラメーターとして記述されていますが、パラメーターを指定せずに使用できます。

クエリでのフィールド属性の影響

クエリの種類と構成に詳しい場合、クエリ要求のパラメーターはインデックスのフィールド属性に依存することをご存じかもしれません。たとえば、"検索可能" か "取得可能" のマークが付いているフィールドのみクエリと検索結果で使用できます。リクエスト内で , , パラメーターを設定する際に、予想外の結果を避けるために、属性を確認してください。

次のスクリーンショットに示す hotels-sample インデックスでは、最後の 2 つのフィールドである LastRenovationDate と Rating のみが並べ替え可能で、これは「only」句で使用するための要件です。

ホテルサンプルのインデックス定義を示すスクリーンショット。

フィールド属性の定義については、「Create Index (REST API)」を参照してください。

クエリに対するトークンの影響

インデックス作成中、検索エンジンでは、文字列にテキストアナライザーを使用し、クエリ時に一致を見つける可能性を最大化します。少なくとも文字列は小文字に変換されますが、アナライザーによっては、レンマ化とストップワードの削除も行われる可能性があります。通常、長い文字列や複合語は、空白、ハイフン、またはダッシュによって分割され、個別のトークンとしてインデックスが付けられます。

重要なポイントは、インデックスに含まれていると思われるものと、実際に何が含まれているかは異なる可能性があるということです。クエリで予想された結果が返されない場合は、分析テキスト (REST API) を通じてアナライザーによって作成されたトークンを検査できます。トークン化とクエリへの影響の詳細については、「部分的な用語検索と特殊文字を含むパターン」をご覧ください。

クエリのトラブルシューティング

次の表に、クエリに関する一般的な問題とその解決方法を示します。

問題点	原因	解決策
空の結果	クエリ用語と一致するドキュメントはありません。	フィールドがスキーマで検索可能とマークされていることを確認します。テキスト分析 API を使用してトークン化を確認します。
予期しない結果	本来意図していないフィールドとクエリが一致しています。	を使用して、検索するフィールドを制限します。
結果が多すぎます	クエリの範囲が広すぎます。	フィルターを追加したり、を使用したり、演算子で必要な用語を追加したりできます。
結果が期待どおりにランク付けされない	関連性スコアリングが期待値と一致しません。	スコアリングプロファイルまたはセマンティックランク付けを検討してください。
部分的な一致が見つからない	アナライザーのトークン化方法が想定とは異なります。	Analyze Text API でワイルドカード () サフィックスを使用するか、アナライザーの動作を確認します。
フィルターが機能しない	フィールドはフィルター可能とマークされていません。	フィールドにを設定するようにインデックススキーマを更新します。

これで、クエリ要求のしくみについての理解が深まったので、次のクイックスタートで実際に体験してみてください。

検索エクスプローラー
クイックスタート: フルテキスト検索
単純なクエリ構文
Full Lucene クエリ構文
OData フィルター構文

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-05

次の方法で共有

Azure AI 検索でフルテキスト クエリを作成する