QueryExpression を使用したデータのクエリ
QueryExpression クラス は、 Microsoft.Xrm.Sdk.Query 名前空間 の他のクラスとともに、 IOrganizationService.RetrieveMultiple 算出方法 を使用して Dataverse からレコードを取得するための複雑なクエリを作成するためのオブジェクト モデルを提供します。 SDK for .NET を使用してデータをクエリする際のオプションを比較する
クエリを作成する
QueryExpression
を使用して、FetchXml を使用して 文字列/XML 操作を必要とせずに変更できる動的クエリを作成します。
すべてのクエリは単一のテーブルに基づいています。 QueryExpression
クラスを使用して、クエリがデータを取得するテーブルを選択します。
オブジェクト初期化スタイル
次の例は、クエリは 1 つの割り当てで定義されるよう、オブジェクト初期化子を使用して、Account テーブルの最初の 5 行の Name 列を返す単純な QueryExpression
クエリを表しています。ます。
public static EntityCollection SimpleExample(IOrganizationService service) {
QueryExpression query = new("account")
{
ColumnSet = new ColumnSet("name"),
TopCount = 5
};
return service.RetrieveMultiple(query);
}
クエリ インスタンスが初期化されると、次のことが可能になります。
- QueryExpression(String) コンストラクター を使用して、 QueryExpression.EntityName プロパティとしてテーブルを指定します。
- 新しい ColumnSet をインスタンス化して 1 つ以上の列 LogicalName 値を[「ColumnSet(String[])」 コンストラクター ](/dotnet/api/microsoft.xrm.sdk.query.columnset.-ctor#microsoft-xrm-sdk-query-columnset-ctor(system-string() に渡すことによって、QueryExpression.ColumnSet プロパティを設定して、返される列を指定します。 列の選択に関する詳細情報
- QueryExpression.TopCount プロパティを設定して返されるレコードの数を制限します
プロパティ割り当てスタイル
QueryExpression(String) コンストラクター またはオブジェクト初期化スタイルを使用せずに同じクエリを作成し、次の例に示すように、インスタンス化されたインスタンスにプロパティを設定することもできます。
public static EntityCollection SimpleExample(IOrganizationService service)
{
QueryExpression query = new();
query.EntityName = "account";
query.ColumnSet.AddColumn("name");
query.TopCount = 5;
return service.RetrieveMultiple(query);
}
このサンプルは、次の操作方法を示します。
- デフォルト コンストラクターを使用して
QueryExpression
インスタンスを初期化した直後に、テーブルを QueryExpression.EntityName プロパティとして指定します。 - QueryExpression.ColumnSet を設定し、 ColumnSet.AddColumn 算出方法 を使用して列名を追加することで、返される列を指定します。 列の選択に関する詳細情報
- オブジェクト初期化後に QueryExpression.TopCount プロパティを設定して返されるレコードの数を制限します。
このドキュメントの例では、オブジェクトの初期化とプロパティの割り当てスタイルの組み合わせを使用します。 クエリが複雑になるにつれて、オブジェクトの初期化スタイルが扱いにくくなる可能性があります。 クエリ プロパティをいつでも個別に定義し、プロパティを設定するか、使用可能な算出方法を使用してクエリに追加できます。
行数の制限
返される行数を制限するには、QueryExpression.TopCount プロパティを使用します。 TopCount
プロパティを設定しないと、Dataverse が最大 5,000 行を返します。
または、ページングを使用して、返すレコードの数を指定します。 データのページを要求するときは、TopCount
プロパティを使用しないでください。 ページングされた結果をリクエストする方法を解説します
PagingInfo.ReturnTotalRecordCount プロパティ を使用して行数を要求する場合、TopCount
プロパティは使用できません。 行の計測方法について説明します。
明確な結果を返します
クエリの結果に重複する値が含まれないようにするには、QueryExpression.Distinct プロパティ を使用します。
Distinct
プロパティを使用する場合は、ページングの一貫性を保つために、少なくとも 1 つの OrderExpression を QueryExpression.Orders プロパティ に追加する必要があります。
Distinct
プロパティを使用すると、返される結果に各レコードの主キー値は含まれません。これは、主キー値がすべての個別の値の集計を表すためです。
データの取得
SDK for .NET を使用してデータをクエリする で説明したように、 QueryExpression
は QueryBase クラス から派生する 3 つのタイプの 1 つであるため、それを IOrganizationService.RetrieveMultiple 算出方法 に渡して、結果を含む EntityCollection を取得できます。
EntityCollection results = service.RetrieveMultiple(query);
ヒント
QueryExpression サンプル コード を使って、この算出方法を使用してみてください。
また、RetrieveMultipleRequest クラス を使って、クエリを RetrieveMultipleRequest.Query プロパティ に設定し、IOrganizationService.Execute 算出方法を使って要求を送信することもできます。
RetrieveMultipleRequest request = new()
{
Query = query
};
var response = (RetrieveMultipleResponse)service.Execute(request);
EntityCollection results = response.EntityCollection;
次のような場合、RetrieveMultipleRequest クラス を使用します。
- 要求とともにオプション パラメーターを送信する
- ExecuteMultipleRequest または ExecuteTransactionRequest クラスを使用して、操作をバッチの一部として含めます。
クエリを絞り込む
クエリを開始するテーブルを選択した後、クエリを調整して必要なデータを取得します。 次の記事では、クエリを完了する方法について説明します。
記事 | Task |
---|---|
列を選択する | 返すデータの列を指定します。 |
テーブルの結合 | 結果としてどの関連テーブルを返すかを指定します。 |
行を並べ替える | 返す行の並べ替え順を指定します。 |
行のフィルター | 返すデータの行を指定します。 |
ページの結果 | 各リクエストで返すデータの行数を指定します。 |
データの集計 | 返されたデータのグループ化と集計を行う方法。 |
行数をカウントする | 返された行数を取得する方法。 |
パフォーマンスの最適化 | パフォーマンスを最適化する方法 |
制限
FetchXml を使用して実行できるが、QueryExpression
がサポートしていない操作がいくつかあります。
Dataverse Web API を使用してデータを取得します。
QueryExpression
パラメーターを有効化する Web API 操作がいくつかありますが、Web API を使用してデータを取得するためにQueryExpression
を使用したクエリを作成することはできません。集計の制限 では、
QueryExpression
を使用した集計の次の制限を示します。テーブル間の列比較を実行します。
QueryExpression
は、同じ行の列値のフィルタリングをサポートしていますが、同じテーブル内にある必要があります。Late Materialize クエリ パフォーマンス最適化は使用できません。
重要
FetchXmlToQueryExpression
メッセージを SDK FetchXmlToQueryExpressionRequest クラス または Web API FetchXmlToQueryExpression 関数のいずれかで使用すると、QueryExpression
でサポートされていない機能は適用されず、エラーは発生しません。
コミュニティ ツール
XrmToolBox FetchXMLBuilder は、FetchXml 要求を作成してテストするための無料ツールですが、同じデザイナー エクスペリエンスを使用して、QueryExpression
クエリのコードも生成します。
注意
コミュニティによって作成されたツールは、Microsoft によってサポートされていません。 コミュニティ ツールに関する質問や問題は、ツールの公開元にお問い合わせください。
QueryExpression をメッセージ パラメーターとして使用する
また、QueryExpression
は、次のメッセージなど Dataverse 操作のパラメーターとしても使用します。
メッセージ名 | SDK for .NET リクエスト クラス | Web API 操作 |
---|---|---|
BackgroundSendEmail |
BackgroundSendEmailRequest | BackgroundSendEmail アクション |
BulkDetectDuplicates |
BulkDetectDuplicatesRequest | BulkDetectDuplicates アクション |
BulkDelete |
BulkDeleteRequest | BulkDelete アクション |
FullTextSearchKnowledgeArticle |
FullTextSearchKnowledgeArticleRequest | FullTextSearchKnowledgeArticle アクション |
QueryExpressionToFetchXml |
QueryExpressionToFetchXmlRequest | QueryExpressionToFetchXml アクション |
SendBulkMail |
SendBulkMailRequest | SendBulkMail アクション |
SyncBulkOperation |
SyncBulkOperationRequest | SyncBulkOperation action |
Rollup |
RollupRequest | ロールアップ機能 |
注意
BulkDelete、SyncBulkOperation、 QueryExpressionToFetchXml アクション 以外の Web API 操作では、 FetchExpression 複合型を介して FetchXml を使用できます。 Web API には、QueryExpression、ColumnSet、FilterExpression 複合型などの QueryExpression
を使用してクエリを作成するための構造が含まれていますが、現在、FetchXml のように、これらを使うことで Web API を使用して QueryExpression
でデータを取得する方法はありません。 つまり、Web API を使用してパラメーターとして送信するクエリの結果をテストすることはできません。
次の手順
列を選択する方法について説明します。
いくつかのクエリを試してください。