Use Bulk Query

When adding a batch to a bulk query job, the Content-Type in the header for the request must be either 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

https://instance_name—api.salesforce.com/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.

Bulk API does not support queries with any of the following:

GROUP BY, OFFSET, or TYPEOF clauses
Aggregate functions such as COUNT()
Date functions in GROUP BY clauses (date functions in WHERE clauses are supported)
Compound address fields or compound geolocations fields

Requests, and Responses

The following 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"

Java Example Using WSC

The following 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  }

Bulk API Developer Guide

Use Bulk Query

Requests, and Responses

Java Example Using WSC

See Also