Bulk API 2.0 and Bulk API Developer Guide
jNewer Version Available
Use Bulk Query
When you add a batch to a bulk query job,
the Content-Type in the header for the request must be text/csv, application/xml, or application/json, depending on the content type specified when
the job was created. The actual SOQL statement supplied for the batch is in plain text
format.
- URI
- /services/async/APIversion/job/jobid/batch
- Bulk Query Request
-
1POST baseURI/job/750x00000000014/batch 2X-SFDC-Session: 4f1a00D30000000K7zB!ARUAQDqAHcM... 3Content-Type: [either text/csv, application/xml, or application/json depending on job] 4 5[plain text SOQL statement]Bulk API query supports both query and queryAll operations. The queryAll operation returns records that have been deleted because of a merge or delete. The queryAll operation also returns information about archived Task and Event records. For more information, see queryAll() in the SOAP API Developer Guide.
Relationship queries traverse parent-to-child and child-to-parent relationships between objects to filter and return results. You can use SOQL relationships in bulk queries. For more information about SOQL relationships, see Using Relationship Queries in the SOQL and SOSL Reference.
Requests, and Responses
These are example Bulk Query requests and responses.
- Create Bulk Query Batch HTTP Request
-
1POST baseURI/job/750x00000000014/batch 2X-SFDC-Session: 4f1a00D30000000K7zB!ARUAQDqAHcM... 3Content-Type: text/csv; charset=UTF-8 4 5SELECT Name, Description__c FROM Merchandise__c - Create Bulk Query Batch HTTP Response Body
-
1<?xmlversion="1.0" encoding="UTF-8"?> 2<batchInfo 3 xmlns="http://www.force.com/2009/06/asyncapi/dataload"> 4 <id>751x00000000079AAA</id> 5 <jobId>750x00000000014</jobId> 6 <state>Queued</state> 7 <createdDate>2009-09-01T17:44:45.000Z</createdDate> 8 <systemModstamp>2009-09-01T17:44:45.000Z</systemModstamp> 9 <numberRecordsProcessed>0</numberRecordsProcessed> 10 <numberRecordsFailed>0</numberRecordsFailed> 11 <totalProcessingTime>0</totalProcessingTime> 12 <apiActiveProcessingTime>0</apiActiveProcessingTime> 13 <apexProcessingTime>0</apexProcessingTime> 14</batchInfo> - Get Batch Information for All Batches in a Job HTTP Request (used when PK chunking is enabled)
-
1GET baseURI/job/750x00000000014/batch 2X-SFDC-Session: 4f1a00D30000000K7zB!ARUAQDqAHcM... - Get Batch Information for All Batches in a Job HTTP Response Body
-
1<?xml version="1.0" encoding="UTF-8"?><batchInfoList 2 xmlns="http://www.force.com/2009/06/asyncapi/dataload"> 3 <batchInfo> 4 <id>751D00000004YjwIAE</id> 5 <jobId>750D00000004T5OIAU</jobId> 6 <state>NotProcessed</state> 7 <createdDate>2011-03-10T00:59:47.000Z</createdDate> 8 <systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp> 9 <numberRecordsProcessed>0</numberRecordsProcessed> 10 <numberRecordsFailed>0</numberRecordsFailed> 11 <totalProcessingTime>0</totalProcessingTime> 12 <apiActiveProcessingTime>0</apiActiveProcessingTime> 13 <apexProcessingTime>0</apexProcessingTime> 14 </batchInfo> 15 <batchInfo> 16 <id>751D00000004Yk1IAE</id> 17 <jobId>750D00000004T5OIAU</jobId> 18 <state>Completed</state> 19 <createdDate>2011-03-10T00:59:47.000Z</createdDate> 20 <systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp> 21 <numberRecordsProcessed>100000</numberRecordsProcessed> 22 <numberRecordsFailed>0</numberRecordsFailed> 23 <totalProcessingTime>1000</totalProcessingTime> 24 <apiActiveProcessingTime>1000</apiActiveProcessingTime> 25 <apexProcessingTime>0</apexProcessingTime> 26 </batchInfo> 27 <batchInfo> 28 <id>751D00000004Yk2IAE</id> 29 <jobId>750D00000004T5OIAU</jobId> 30 <state>Completed</state> 31 <createdDate>2011-03-10T00:59:47.000Z</createdDate> 32 <systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp> 33 <numberRecordsProcessed>100000</numberRecordsProcessed> 34 <numberRecordsFailed>0</numberRecordsFailed> 35 <totalProcessingTime>1000</totalProcessingTime> 36 <apiActiveProcessingTime>1000</apiActiveProcessingTime> 37 <apexProcessingTime>0</apexProcessingTime> 38 </batchInfo> 39 <batchInfo> 40 <id>751D00000004Yk6IAE</id> 41 <jobId>750D00000004T5OIAU</jobId> 42 <state>Completed</state> 43 <createdDate>2011-03-10T00:59:47.000Z</createdDate> 44 <systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp> 45 <numberRecordsProcessed>100000</numberRecordsProcessed> 46 <numberRecordsFailed>0</numberRecordsFailed> 47 <totalProcessingTime>1000</totalProcessingTime> 48 <apiActiveProcessingTime>1000</apiActiveProcessingTime> 49 <apexProcessingTime>0</apexProcessingTime> 50 </batchInfo> 51 <batchInfo> 52 <id>751D00000004Yk7IAE</id> 53 <jobId>750D00000004T5OIAU</jobId> 54 <state>Completed</state> 55 <createdDate>2011-03-10T00:59:47.000Z</createdDate> 56 <systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp> 57 <numberRecordsProcessed>50000</numberRecordsProcessed> 58 <numberRecordsFailed>0</numberRecordsFailed> 59 <totalProcessingTime>500</totalProcessingTime> 60 <apiActiveProcessingTime>500</apiActiveProcessingTime> 61 <apexProcessingTime>0</apexProcessingTime> 62 </batchInfo> 63</batchInfoList> - Get Batch Results HTTP Request
-
1GET baseURI/job/750x00000000014/batch/751x00000000030/result 2X-SFDC-Session: 4f1a00D30000000K7zB!ARUAQDqAHcM... - Get Batch Results HTTP Response Body
-
1<result-list xmlns="http://www.force.com/2009/06/asyncapi/dataload"><result>752x000000000F1</result></result-list> - Get Bulk Query Results HTTP Request
-
1GET baseURI/job/750x00000000014/batch/751x00000000030/result/752x000000000F1 2X-SFDC-Session: 4f1a00D30000000K7zB!ARUAQDqAHcM... - Get Bulk Query Results HTTP Response Body
-
1"Name", "Description__c" 2"Merchandise1", "Description for merchandise 1" 3"Merchandise2", "Description for merchandise 2" - XML Responses for Queries that Include ID
- If you use XML for the ContentType of a Query Job, then a query that includes ID
returns the ID field twice in the XML response data. Similarly, a query that does not
include ID returns a single null ID field in the XML response data. For example, a query
for SELECT ID, FirstName, LastName FROM Contact might
return an XML response with records
like:This is expected behavior and something to be aware of if you are accessing the full XML response data and not using WSC to access the web service response. For more information, see Queries and the Partner WSDL in the SOAP API Developer Guide.
1<records xsi:type="sf:sObject" xmlns="urn:partner.soap.sforce.com"> 2 <sf:type>Contact</sf:type> 3 <sf:Id>0038000000FrjoBQRW</sf:Id> 4 <sf:Id>0038000000FrjoBQRW</sf:Id> 5 <sf:FirstName>John</sf:FirstName> 6 <sf:LastName>Smith</sf:LastName> 7</records>
Java Example Using WSC
This example logs in to an organization using the Partner API, then instantiates a BulkConnection object using the service endpoint from the Partner API login.
1public boolean login() {
2 boolean success = false;
3
4 String userId = getUserInput("UserID: ");
5 String passwd = getUserInput("Password: ");
6 String soapAuthEndPoint = "https://" + loginHost + soapService;
7 String bulkAuthEndPoint = "https://" + loginHost + bulkService;
8 try {
9 ConnectorConfig config = new ConnectorConfig();
10 config.setUsername(userId);
11 config.setPassword(passwd);
12 config.setAuthEndpoint(soapAuthEndPoint);
13 config.setCompression(true);
14 config.setTraceFile("traceLogs.txt");
15 config.setTraceMessage(true);
16 config.setPrettyPrintXml(true);
17 System.out.println("AuthEndpoint: " +
18 config.getRestEndpoint());
19 PartnerConnection connection = new PartnerConnection(config);
20 System.out.println("SessionID: " + config.getSessionId());
21 config.setRestEndpoint(bulkAuthEndPoint);
22 bulkConnection = new BulkConnection(config);
23 success = true;
24 } catch (AsyncApiException aae) {
25 aae.printStackTrace();
26 } catch (ConnectionException ce) {
27 ce.printStackTrace();
28 } catch (FileNotFoundException fnfe) {
29 fnfe.printStackTrace();
30 }
31 return success;
32 }
33
34 public void doBulkQuery() {
35 if ( ! login() ) {
36 return;
37 }
38 try {
39 JobInfo job = new JobInfo();
40 job.setObject("Merchandise__c");
41
42 job.setOperation(OperationEnum.query);
43 job.setConcurrencyMode(ConcurrencyMode.Parallel);
44 job.setContentType(ContentType.CSV);
45
46 job = bulkConnection.createJob(job);
47 assert job.getId() != null;
48
49 job = bulkConnection.getJobStatus(job.getId());
50
51 String query =
52 "SELECT Name, Id, Description__c FROM Merchandise__c";
53
54 long start = System.currentTimeMillis();
55
56 BatchInfo info = null;
57 ByteArrayInputStream bout =
58 new ByteArrayInputStream(query.getBytes());
59 info = bulkConnection.createBatchFromStream(job, bout);
60
61 String[] queryResults = null;
62
63 for(int i=0; i<10000; i++) {
64 Thread.sleep(30000); //30 sec
65 info = bulkConnection.getBatchInfo(job.getId(),
66 info.getId());
67
68 if (info.getState() == BatchStateEnum.Completed) {
69 QueryResultList list =
70 bulkConnection.getQueryResultList(job.getId(),
71 info.getId());
72 queryResults = list.getResult();
73 break;
74 } else if (info.getState() == BatchStateEnum.Failed) {
75 System.out.println("-------------- failed ----------"
76 + info);
77 break;
78 } else {
79 System.out.println("-------------- waiting ----------"
80 + info);
81 }
82 }
83
84 if (queryResults != null) {
85 for (String resultId : queryResults) {
86 bulkConnection.getQueryResultStream(job.getId(),
87 info.getId(), resultId);
88 }
89 }
90 } catch (AsyncApiException aae) {
91 aae.printStackTrace();
92 } catch (InterruptedException ie) {
93 ie.printStackTrace();
94 }
95 }