Query

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

クエリ結果が大きすぎる場合、応答には、結果の最初のバッチと応答の nextRecordsUrl 項目のクエリ識別子が含まれます。識別子は、追加の要求で次のバッチを取得するために使用できます。

URI

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

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

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

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

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

最初の結果が大きすぎる場合、以降のクエリ結果は次のように取得します。

/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 を使用します。このフィードバックを使用して、クエリをさらに最適化できます。また、クエリ文字列の代わりにレポートまたはリストビューの ID を使用して、Salesforce でのレポートまたはリストビューの処理方法に関するフィードバックを取得することもできます。 explain パラメータは、API バージョン 30.0 以降で使用できます。 REST API クエリリソースでの explain の使用は、ベータ機能です。このベータ機能に関連するサポートはありません。詳細は、Salesforce にお問い合わせください。 メモ SOQL クエリ文字列が無効な場合、MALFORMED_QUERY 応答が返されます。レポートまたはリストビューの ID が無効な場合、INVALID_ID 応答が返されます。

レスポンスボディ

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

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

例

クエリの作成と、クエリ識別子を使用した以降のクエリ結果の取得の例は、「SOQL クエリを実行する」を参照してください。

explain パラメータを使用してクエリおよびレポートでフィードバックを取得する例は、「クエリのパフォーマンスに関するフィードバックを取得する」を参照してください。

SOQL についての詳細は、『SOQL および SOSL リファレンス』を参照してください。クエリのバッチサイズについての詳細は、『SOAP API 開発者ガイド』の「クエリのバッチサイズの変更」を参照してください。