Bulk API Developer's Guide

Introduction
Quick Start
Planning Bulk Data Loads
Preparing Data Files
Loading Binary Attachments
Request Basics
Working with Jobs
Working with Batches
Bulk Query
Reference
Sample Client Application Using Java
Sample Bulk Query Using cURL
Walk Through the Bulk Query Sample
Mapping Data Fields
Glossary
PDF

Newer Version Available

This content describes an older version of this product. View Latest

Walk Through the Bulk Query Sample

Create a Job

The following example shows how to use bulk query from the command line using cURL.

  1. Create a file called create-job.xml containing the following text:
    1<?xml version="1.0" encoding="UTF-8"?>
2<jobInfo
3    xmlns="http://www.force.com/2009/06/asyncapi/dataload">
4  <operation>query</operation>
5  <object>Account</object>
6  <concurrencyMode>Parallel</concurrencyMode>
7  <contentType>CSV</contentType>
8</jobInfo>
  2. Using a command-line window, execute the following cURL command to create a job:

    curl -H "X-SFDC-Session: sessionId" -H "Content-Type: application/xml; charset=UTF-8" -d @create-job.xml https://instance.salesforce.com/services/async/34.0/job

    instance is the portion of the <serverUrl> element and sessionId is the <sessionId> element that you noted in the login response.

    Salesforce returns an XML response with data such as the following:

    1<?xml version="1.0" encoding="UTF-8"?>
2<jobInfo
3    xmlns="http://www.force.com/2009/06/asyncapi/dataload">
4  <id>750x000000009tvAAA</id>
5  <operation>query</operation>
6  <object>Account</object>
7  <createdById>005x0000001WR0lAAG</createdById>
8  <createdDate>2011-03-10T00:53:19.000Z</createdDate>
9  <systemModstamp>2011-03-10T00:53:19.000Z</systemModstamp>
10  <state>Open</state>
11  <concurrencyMode>Parallel</concurrencyMode>
12  <contentType>CSV</contentType>
13  <numberBatchesQueued>0</numberBatchesQueued>
14  <numberBatchesInProgress>0</numberBatchesInProgress>
15  <numberBatchesCompleted>0</numberBatchesCompleted>
16  <numberBatchesFailed>0</numberBatchesFailed>
17  <numberBatchesTotal>0</numberBatchesTotal>
18  <numberRecordsProcessed>0</numberRecordsProcessed>
19  <numberRetries>0</numberRetries>
20  <apiVersion>21.0</apiVersion>
21  <numberRecordsFailed>0</numberRecordsFailed>
22  <totalProcessingTime>0</totalProcessingTime>
23  <apiActiveProcessingTime>0</apiActiveProcessingTime>
24  <apexProcessingTime>0</apexProcessingTime>
25</jobInfo>

Add the Job to a Batch

  1. Create a file called query.txt to contain the SOQL query statement.
    1SELECT Id, Name FROM Account LIMIT 10
  2. Using a command-line window, execute the following cURL command to add the job to a batch:

    curl —d @query.txt -H "X-SFDC-Session: sessionId" -H "Content-Type: text/csv; charset=UTF-8” https://instance.salesforce.com/services/async/34.0/job/jobId/batch

    jobId is the job ID returned in the response to the job createion.

    Salesforce returns an XML response with data such as the following:

    1<?xml version="1.0" encoding="UTF-8"?>
2<batchInfo
3    xmlns="http://www.force.com/2009/06/asyncapi/dataload">
4  <id>751x000000009vwAAA</id>
5  <jobId>750x000000009tvAAA</jobId>
6  <state>Queued</state>
7  <createdDate>2011-03-10T00:59:47.000Z</createdDate>
8  <systemModstamp>2011-03-10T00:59:47.000Z</systemModstamp>
9  <numberRecordsProcessed>0</numberRecordsProcessed>
10  <numberRecordsFailed>0</numberRecordsFailed>
11  <totalProcessingTime>0</totalProcessingTime>
12  <apiActiveProcessingTime>0</apiActiveProcessingTime>
13  <apexProcessingTime>0</apexProcessingTime>
14</batchInfo>

    When adding a batch to a bulk query job, the Content-Type in the header for the request must be either text/csv or application/xml, depending on the content type specified when the job was created. The actual SOQL statement supplied for the batch will be in plain text format.

    Note

Check the Status of the Job and Batch

  1. Using a command-line window, execute the following cURL command to check the job status:

    curl -H "X-SFDC-Session: sessionId" https://instance.salesforce.com/services/async/34.0/job/jobId

    Salesforce returns an XML response with data such as the following:

    1<?xml version="1.0" encoding="UTF-8"?>
2<jobInfo
3    xmlns="http://www.force.com/2009/06/asyncapi/dataload">
4  <id>750x000000009tvAAA</id>
5  <operation>query</operation>
6  <object>Account</object>
7  <createdById>005x0000001WR0lAAG</createdById>
8  <createdDate>2011-03-10T00:53:19.000Z</createdDate>
9  <systemModstamp>2011-03-10T00:53:19.000Z</systemModstamp>
10  <state>Open</state>
11  <concurrencyMode>Parallel</concurrencyMode>
12  <contentType>CSV</contentType>
13  <numberBatchesQueued>0</numberBatchesQueued>
14  <numberBatchesInProgress>0</numberBatchesInProgress>
15  <numberBatchesCompleted>1</numberBatchesCompleted>
16  <numberBatchesFailed>0</numberBatchesFailed>
17  <numberBatchesTotal>1</numberBatchesTotal>
18  <numberRecordsProcessed>10</numberRecordsProcessed>
19  <numberRetries>0</numberRetries>
20  <apiVersion>21.0</apiVersion>
21  <numberRecordsFailed>0</numberRecordsFailed>
22  <totalProcessingTime>0</totalProcessingTime>
23  <apiActiveProcessingTime>0</apiActiveProcessingTime>
24  <apexProcessingTime>0</apexProcessingTime>
25</jobInfo>
  2. Using a command-line window, execute the following cURL command to check the batch status:

    curl -H "X-SFDC-Session: sessionId" https://instance.salesforce.com/services/async/34.0/job/jobId/batch/batchId

    batchId is the batch ID in the response to the batch creation.

    Salesforce returns an XML response with data such as the following:

    1<?xml version="1.0" encoding="UTF-8"?>
2<batchInfo
3    xmlns="http://www.force.com/2009/06/asyncapi/dataload">
4  <id>751x000000009vwAAA</id>
5  <jobId>750x000000009tvAAA</jobId>
6  <state>Completed</state>
7  <createdDate>2011-03-10T00:59:47.000Z</createdDate>
8  <systemModstamp>2011-03-10T01:00:19.000Z</systemModstamp>
9  <numberRecordsProcessed>10</numberRecordsProcessed>
10  <numberRecordsFailed>0</numberRecordsFailed>
11  <totalProcessingTime>0</totalProcessingTime>
12  <apiActiveProcessingTime>0</apiActiveProcessingTime>
13  <apexProcessingTime>0</apexProcessingTime>
14</batchInfo>

Retrieve the Results

  1. Using the command-line window, execute the following cURL command to retrieve the batch result list:

    curl -H "X-SFDC-Session: sessionId" https://instance.salesforce.com/services/async/34.0/job/jobId/batch/batchId/result

    Salesforce returns an XML response with data such as the following:

    1<?xml version="1.0" encoding="UTF-8"?>
2<result-list xmlns="http://www.force.com/2009/06/asyncapi/dataload">
3  <result>752x00000004CJE</result>
4</result-list>
  2. Using the command-line window, execute the following cURL command to retrieve the results of the query:

    curl -H "X-SFDC-Session: sessionId" https://instance.salesforce.com/services/async/34.0/job/jobId/batch/batchId/result/resultId

    resultId is the result ID in the response to the batch result list request.

    Salesforce returns an XML response with data such as the following:

    1"Id","Name"
2"001x000xxx4TU4JAAW","name161268--1296595660659"
3"001x000xxx4TU4KAAW","name161269--1296595660659"
4"001x000xxx4TU4LAAW","name161270--1296595660659"
5"001x000xxx4TU4MAAW","name161271--1296595660659"
6"001x000xxx4TU4NAAW","name161272--1296595660659"
7"001x000xxx4TU4OAAW","name161273--1296595660659"
8"001x000xxx4TU4PAAW","name161274--1296595660659"
9"001x000xxx4TU4QAAW","name161275--1296595660659"
10"001x000xxx4TU4RAAW","name161276--1296595660659"
11"001x000xxx4TU4SAAW","name161277--1296595660659"