Async SOQL Running Async SOQL Queries
Running Async SOQL Queries
Learn how to run Async SOQL queries on your objects and check on the status of your query using the Chatter REST API.
Formulating Your Async SOQL Query
To use Async SOQL effectively, it’s helpful to understand its key component and other related concepts. Each query is formulated in the
POST request as a JSON-encoded list of three or four key-value pairs.
Request body for POST
Name Type
query operation
String
String targetObject
String targetFieldMap
Map<String,
String>
Description Required or
Optional
Required Specifies the parameters for the SOQL query you want to execute.
Specify whether the query is an insert or upsert. If the record doesn’t exist, an upsert behaves like an insert.
Optional
Note: Upsert is not supported for big objects
A standard object, custom object, external object, or big object into which to insert the results of the query.
Required
Defines how to map the fields in the query result to the fields in the target object.
Required
Note: When defining the targetFieldMap
parameter, make sure that the field type mappings are consistent. If the source and target fields don’t match, these considerations apply.
•
Any source field can be mapped onto a target text field.
•
If the source and target fields are both numerical, the target field must have the same or greater number of decimal places than the source field. If not, the request fails. This behavior is to ensure that no data is lost in the conversion.
•
If a field in the query result is mapped more than once, even if mapped to different fields in the target object, only the last mapping is used.
Available
Version
35.0
39.0
35.0
35.0
15
Async SOQL Running Async SOQL Queries
Name Type
targetValueMap
Map<String,
String> targetExternalIdField
String
Description Required or
Optional
Defines how to map static strings to fields in the target object. Any field or alias can be used as the
TargetValueMap
value in the SELECT clause of a query.
You can map the special value, $JOB_ID, to a field in the target object. The target field must be a lookup to the Background Operation standard object. In this case, the ID of the Background
Operation object representing the Async SOQL query is inserted. If the target field is a text field, it must be at least 15–18 characters long.
Optional
You can also include any field or alias in the SELECT clause of the
TargetValueMap
. They can be combined together to concatenate a value to be used.
The ID of the target sObject. Required for upsert operations.
Optional
Available
Version
37.0
39.0
This simple Async SOQL example queries
SourceObject__c
, a source custom object, and directs the result to
TargetObject__c
, another custom object. You can easily map the fields in the source object to the fields of the target object in which you want to write the results.
Example URI
https://yourInstance.salesforce.com/services/data/v38.0/async-queries/
Example POST request body
{
"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",
"operation": "insert",
"targetObject": "TargetObject__c",
"targetFieldMap": {"firstField__c":"firstFieldTarget__c",
"secondField__c":"secondFieldTarget__c"
},
"targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",
"Copy fields from source to target":"BackgroundOperationDescription__c"
}
}
The response of an Async SOQL query includes the elements of the initial POST request.
Response body for POST
16
Async SOQL Running Async SOQL Queries
Property Name
jobId message operation
Type
String
String
String
Description Filter Group and
Version
The ID of the Async SOQL query. This ID corresponds to an entry in the Background
Operation standard object. It matches the
ID that is used in the targetValueMap when $JOB_ID is used. To get the status of an async query job, use this ID in an Async
Query, Status request
(
/async-queries/
jobId
).
Big, 35.0
Available Version
35.0
A text message that provides information regarding the query, such as an error message if the query failed.
Big, 37.0
Specify whether the query is an insert or upsert. If the record doesn’t exist, an upsert behaves like an insert.
Big, 39.0
Note: Upsert is not supported for big objects
37.0
.39.0
35.0
query status
String
String
Specifies the parameters for the SOQL query you want to execute.
Big, 35.0
Status of an async query job.
•
Canceled
—The job was canceled before it could be run.
•
Success
—The job was successfully completed.
•
Failed
—The job failed after the system submitted it or because the request exceeded the Async SOQL limits. The message field provides details on the reason for failure.
•
Running
—The job is running successfully, and the org hasn’t exceeded any limits.
•
Scheduled
—The new job has been created and scheduled, but is not yet running.
Big, 35.0
targetExternalIdField
String The ID of the target sObject. Required for upsert operations.
Big, 39.0
targetFieldMap
Map<String, String> Defines how to map the fields in the query result to the fields in the target object.
Big, 35.0
Note: When defining the targetFieldMap
parameter,
35.0
39.0
35.0
17
Async SOQL Running Async SOQL Queries
Property Name Type Description Filter Group and
Version
Available Version
make sure that the field type mappings are consistent. If the source and target fields don’t match, these considerations apply.
•
Any source field can be mapped onto a target text field.
•
If the source and target fields are both numerical, the target field must have the same or greater number of decimal places than the source field. If not, the request fails. This behavior is to ensure that no data is lost in the conversion.
•
If a field in the query result is mapped more than once, even if mapped to different fields in the target object, only the last mapping is used.
targetValueMap
Map<String, String> Defines how to map static strings to fields in the target object. Any field or alias can be used as the
TargetValueMap
value in the SELECT clause of a query.
Big, 37.0
You can map the special value, $JOB_ID, to a field in the target object. The target field must be a lookup to the Background
Operation standard object. In this case, the
ID of the Background Operation object representing the Async SOQL query is inserted. If the target field is a text field, it must be at least 15–18 characters long.
You can also include any field or alias in the
SELECT clause of the
TargetValueMap
.
They can be combined together to concatenate a value to be used.
targetObject
String A standard object, custom object, external object, or big object into which to insert the results of the query.
Big, 35.0
37.0
35.0
18
Async SOQL Running Async SOQL Queries
Example POST response body
{
"jobId": "08PD000000003kiT",
"message": "",
"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",
"status": "New",
"targetObject": "TargetObject__c",
"targetFieldMap": {"firstField__c":"firstFieldTarget__c",
"secondField__c":"secondFieldTarget__c"
},
"targetValueMap": {"$JOB_ID":"BackgroundOperationLookup__c",
"Copy fields from source to target":"BackgroundOperationDescription__c"
}
}
Tracking the Status of Your Query
To track the status of a query, specify its jobID with an HTTP GET request.
https://yourInstance.salesforce.com/services/data/v38.0/async-queries/<jobID>
The response is similar to the initial POST response but with updated status and message fields to reflect the status.
Example GET response body
{
"jobId": "08PD000000000001",
"message": "",
"query": "SELECT firstField__c, secondField__c FROM SourceObject__c",
"status": "Complete",
"targetObject": "TargetObject__c",
"targetFieldMap": {"firstField__c":"firstFieldTarget__c",
"secondField__c":"secondFieldTarget__c" }
}
You can get status information for all queries with the following HTTP GET request.
https://yourInstance.salesforce.com/services/data/v38.0/async-queries/
Example GET response body
{
"asyncQueries" : [ {
"jobId" : "08PD00000000002",
"message" : "",
"query" : "SELECT String__c FROM test__b",
"status" : "Running",
19
