Query

Executes the specified SOQL query.

If the query results are too large, the response contains the first batch of results and a query identifier in the nextRecordsUrl field of the response. The identifier can be used in an additional request to retrieve the next batch.

URI

/vXX.X/query/?q=SOQL query

For retrieving query performance feedback without executing the query:

/vXX.X/query/?explain=SOQL query

For retrieving additional query results if the initial results are too large:

/vXX.X/query/query identifier

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

Parameter	Description
q	A SOQL query. Note that you will need to replace spaces with “+” characters in your query string to create a valid URI. An example query parameter string might look like: “SELECT+Name+FROM+MyObject”
explain	A SOQL query to get performance feedback on. Use explain instead of q to get a response that details how Salesforce will process your query. You can use this feedback to further optimize your queries. The explain parameter is available in API version 30.0 and later. Using explain with the REST API query resource is a pilot feature. There is no support associated with this pilot feature. For more information, contact salesforce.com, inc. Note

Response body

For a query using the q parameter, the response contains an array of query result records. For a query using the explain parameter, the response contains one or more query plans that can be used to execute the query, sorted from most optimal to least optimal. Each plan has the following information:

Name	Type	Description
cardinality	number	The estimated number of records the query would return, based on index fields, if any.
fields	string[]	The index fields used for the query, if the leading operation type is Index, otherwise null.
leadingOperationType	string	The primary operation type that will be used to optimize the query. This can be one of these values: Index—The query will use an index on the query object. Other—The query will use optimizations internal to Salesforce. Sharing—The query will use an index based on the user’s sharing rules. If there are sharing rules that limit which records are visible to the current user, those rules can be used to optimize the query. TableScan—The query will scan all records for the query object, and won’t use an index.
relativeCost	number	The cost of this query compared to the SOQL selective query threshold. A value greater than 1.0 means the query won’t be selective. See “More Efficient SOQL Queries” in the Apex Code Developer’s Guide for more information on selective queries.
sobjectCardinality	number	The approximate count of all records in your organization for the query object.
sobjectType	string	The name of the query object, such as Merchandise__c.

Example

For an example of making a query and retrieving additional query results using the query identifier, see Execute a SOQL Query.

For an example using the explain parameter to get feedback on a query, see Get Feedback on Query Performance.

For more information on SOQL see the Force.com SOQL and SOSL Reference. For more information on query batch sizes, see Changing the Batch Size in Queries in the SOAP API Developer's Guide.