Query

指定された SOQL クエリを実行します。

SOQL クエリが実行された場合、同期要求で一度に最大 2,000 個のレコードが返されます。結果数がこの制限を超える場合、応答には、最初の結果セットと応答の nextRecordsUrl 項目に含まれるクエリ識別子が含まれます。識別子は、次のバッチを取得するために別の要求で使用できます。

URI

/services/data/vXX.X/query/?q=SOQL クエリ

クエリを実行せずにクエリのパフォーマンスフィードバックを取得する場合:

/services/data/vXX.X/query/?explain=SOQL クエリ

レポートまたはリストビューに関するクエリのパフォーマンスフィードバックを取得する場合:

/services/data/vXX.X/query/?explain=レポートまたはリストビュー ID

最初の結果が多い場合、追加のクエリ結果は次のように取得します。

/services/data/vXX.X/query/クエリ識別子

形式

JSON、XML

HTTP メソッド

GET

認証

Authorization: Bearer token

パラメータ

パラメータ	説明
q	SOQL クエリ。有効な URI を作成するには、クエリ文字列ではスペースをプラス記号 + に置き換えます。たとえば、SELECT+Name+FROM+MyObject のようになります。SOQL クエリ文字列が無効な場合、MALFORMED_QUERY 応答が返されます。
explain	パフォーマンスフィードバックを取得する SOQL クエリ。Salesforce でのクエリの処理方法の詳細を示す応答を取得するには、q の代わりに explain を使用します。このフィードバックを使用して、クエリをさらに最適化します。Salesforce でレポートまたはリストビューがどのように処理されるかについてフィードバックを取得するには、クエリ文字列の代わりにレポート ID またはリストビュー ID を使用します。 explain パラメータは、API バージョン 30.0 以降で使用できます。 Query リソースでの explain の使用は、ベータ機能です。このベータ機能に関するサポートはありません。詳細は、Salesforce にお問い合わせください。 メモ SOQL クエリ文字列が無効な場合、MALFORMED_QUERY 応答が返されます。レポートまたはリストビューの ID が無効な場合、INVALID_ID 応答が返されます。

レスポンスボディ

q パラメータを使用するクエリでは、クエリ結果レコードの配列が応答に含まれます。explain パラメータを使用するクエリでは、クエリ、レポート、またはリストビューの実行に使用できる 1 つ以上のクエリ実行プランが応答に含まれます。プランは、最も最適なものから順に並び替えられます。各プランには次の情報が含まれます。

名前	型	説明
cardinality	number	インデックス項目に基づいてクエリから返されると予測されるレコード数 (存在する場合)。
fields	string[]	leadingOperationType が Index の場合、その値がクエリに使用されるインデックス項目となります。それ以外の場合、値は null です。
leadingOperationType	string	クエリを最適化するために使用できる主な操作種別。次のいずれかの値が有効です。 Index — クエリオブジェクトに関するインデックスがクエリで使用されます。 Other — Salesforce の内部的な最適化がクエリで使用されます。 Sharing — ユーザの共有ルールに基づいたインデックスがクエリで使用されます。現在のユーザに表示されるレコードが制限される共有ルールの場合、そのルールでクエリを最適化することができます。 TableScan — クエリオブジェクトのすべてのレコードがクエリでスキャンされ、インデックスは使用されません。
notes	feedback note[]	1 つ以上のフィードバックメモの配列。各メモに含まれる内容は、次のとおりです。 description — 最適化の一部に関する詳細な説明。この説明には、使用不可能な最適化についてと、その理由が含まれます。 fields — 最適化に使用される 1 つ以上の項目の配列。 tableEnumOrId — 最適化に使用される項目のテーブル名。 この応答項目は、API バージョン 33.0 以降で使用できます。
relativeCost	number	SOQL セレクティブクエリのしきい値と比較した、このクエリのコスト。1.0 を超える値は、クエリがセレクティブではないことを示します。セレクティブクエリについての詳細は、『Apex 開発者ガイド』の「非常に大きい SOQL クエリの処理」を参照してください。
sobjectCardinality	number	組織内にあるクエリオブジェクトの全レコードの概数。
sobjectType	string	クエリオブジェクトの名前 (Merchandise__c など)。