Query

Executes the specified SOQL query.

When a SOQL query is executed, up to 2,000 records can be returned at a time in a synchronous request. If the number of results exceeds this limit, the response contains only the first set of results and a query locator, contained in the response’s nextRecordsUrl field. The locator can be used in another request to retrieve the next batch of records.

URI

/services/data/vXX.X/query/?q=SOQL_query

For retrieving query performance feedback without executing the query (beta):

/services/data/vXX.X/query/?explain=SOQL_query

For retrieving query performance feedback on a report or list view (beta):

/services/data/vXX.X/query/?explain=report_or_list_view_ID

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

/services/data/vXX.X/query/query_locator

Formats

JSON, XML

HTTP Method

GET

Authentication

Authorization: Bearer token

Parameters

Parameter	Description
q	A SOQL query. To create a valid URI, replace spaces with a plus sign + in the query string. For example: SELECT+Name+FROM+MyObject. If the SOQL query string is invalid, a MALFORMED_QUERY response is returned.
explain	A SOQL query to get performance feedback. Use explain instead of q to get a response that details how Salesforce processes your query. Use this feedback to further optimize your queries. To get feedback on how Salesforce processes a report or list view, use a report or list view ID in place of the query string. The explain parameter is available in API version 30.0 and later. This feature is a Beta Service. Customer may opt to try such Beta Service in its sole discretion. Any use of the Beta Service is subject to the applicable Beta Services Terms provided at Agreements and Terms. Note If the SOQL query string is invalid, a MALFORMED_QUERY response is returned. If the report or list view ID is invalid, an INVALID_ID response is returned.

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, report, or list view. The plans are 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[]	If the leading operation type is Index, these values are the index fields used for the query. Otherwise, the value is null.
leadingOperationType	string	The primary operation type that can use to optimize the query. This type can be one of these values: Index—The query uses an index on the query object. Other—The query uses optimizations internal to Salesforce. Sharing—The query uses 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 optimize the query. TableScan—The query scans all records for the query object, and doesn’t use an index.
notes	feedback note[]	An array of one or more feedback notes. Each note contains: description— A detailed description of a part of the optimization. This description can include information on optimizations that can’t be used and why they can’t used. fields— An array of one or more fields used for the optimization. tableEnumOrId— The table name for the fields used for the optimization. This response field is available in API version 33.0 and later.
relativeCost	number	The cost of this query compared to the SOQL selective query threshold. A value greater than 1.0 means the query isn’t selective. For more information on selective queries, see Working with Very Large SOQL Queries in the Apex Developer Guide.
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.