QueryExpression を使用してデータを照会する

QueryExpression クラスは、Microsoft.Xrm.Sdk.Query 名前空間の他のクラスと共に、IOrganizationService.RetrieveMultiple メソッドを使用して Dataverse からレコードを取得する複雑なクエリを作成するオブジェクト モデルを提供します。 SDK for .NET を使用してデータをクエリする際のオプションを比較する

クエリを作成する

QueryExpressionを使用して動的クエリを作成し、FetchXml の使用時に文字列または XML 操作を必要とせずに変更できます。

すべてのクエリは単一のテーブルに基づいています。 QueryExpression クラスを使用して、クエリがデータを取得するテーブルを選択します。

オブジェクト初期化スタイル

次の例は、QueryExpression クエリを表しており、オブジェクト初期化子を使用して、Account テーブルの最初の5行のName列を返すように単一の割り当てでクエリが定義されます。

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[]) コンストラクター に渡すことによって、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.ColumnSet を設定し、 ColumnSet.AddColumn 算出方法 を使用して列名を追加することで、返される列を指定します。 列の選択について詳しくは、こちらをご覧ください。
• オブジェクト初期化後に QueryExpression.TopCount プロパティを設定して返されるレコードの数を制限します。

このドキュメントの例では、オブジェクトの初期化とプロパティの割り当てスタイルの組み合わせを使用します。 クエリが複雑になるにつれて、オブジェクトの初期化スタイルが扱いにくくなる可能性があります。 クエリ プロパティをいつでも個別に定義し、プロパティを設定するか、使用可能な算出方法を使用してクエリに追加できます。

行数の制限

返される行数を制限するには、QueryExpression.TopCount プロパティを使用します。 TopCount プロパティを設定しない場合、Dataverse は標準テーブルの場合は最大 5,000 行、エラスティック テーブルの場合は 500 行を返します。

または、ページングを使用して返すレコードの数を指定します。 データのページを要求するときは、TopCount プロパティを使用しないでください。 ページングされた結果を要求する方法について説明します。

TopCount プロパティを使用して行数を要求する場合は、 プロパティを使用できません。 行をカウントする方法について説明します。

明確な結果を返します

クエリの結果に重複する値が含まれないようにするには、QueryExpression.Distinct プロパティ を使用します。

Distinct プロパティを使用する場合は、ページングの一貫性を保つために、少なくとも 1 つの OrderExpression を QueryExpression.Orders プロパティ に追加する必要があります。

Distinct プロパティを使用すると、返される結果に各レコードの主キー値は含まれません。これは、主キー値がすべての個別の値の集計を表すためです。

データの取得

SDK for .NET を使用したクエリ データの説明に従って、QueryExpressionは QueryBase クラスから派生した 3 種類のうちの 1 つです。 これを IOrganizationService.RetrieveMultiple メソッドに渡して、結果を含むEntityCollectionを取得できます。

EntityCollection results = service.RetrieveMultiple(query);

RetrieveMultipleRequest クラスを使用して、クエリを RetrieveMultipleRequest.Query プロパティに設定することもできます。 次に、 IOrganizationService.Execute メソッドを使用して要求を送信します。

RetrieveMultipleRequest request = new()
{
      Query = query
};
var response = (RetrieveMultipleResponse)service.Execute(request);

EntityCollection results = response.EntityCollection;

次のような場合、RetrieveMultipleRequest クラス を使用します。

• 要求とともにオプション パラメーターを送信する
• ExecuteMultipleRequest クラスまたは ExecuteTransactionRequest クラスを使用して、操作をバッチの一部として含めます。

クエリを絞り込む

クエリを開始するテーブルを選択した後、クエリを調整して必要なデータを取得します。 次の記事では、クエリを完了する方法について説明します。

制限

FetchXml は、QueryExpression がサポートしていないいくつかの機能をサポートしています。

• Dataverse Web API を使用してデータを取得します。 一部の Web API 操作では QueryExpression パラメーターが有効になりますが、 QueryExpression を使用して Web API を使用してデータを取得してクエリを作成することはできません。

• 集計の制限事項には、QueryExpressionを使用した集計に関する次の制限事項が示されています。

  • CountColumn で一意の数値を取得する
  • 日付でグループ化する場合のタイム ゾーン
  • 行の集計
  • クエリごとの制限

• テーブル間の列比較を実行します。 QueryExpression は、同じ行の列値のフィルタリングをサポートしていますが、同じテーブル内にある必要があります。

• 選択列の既定の並べ替え順序をオーバーライドすることはできません。

• Late Materialize クエリ パフォーマンス最適化は使用できません。

コミュニティ ツール

XrmToolBoxFetchXMLBuilder は、FetchXml 要求を作成してテストするための無料のツールです。 また、同じデザイナー エクスペリエンスを使用して QueryExpression クエリのコードも生成します。

QueryExpression をメッセージ パラメーターとして使用する

次のメッセージなど、dataverse 操作のパラメーターとして QueryExpression を使用することもできます。

次の手順

列を選択する方法について説明します。

いくつかのクエリを試してください。