PK Chunking Header

Use the PK Chunking request header to enable automatic primary key (PK) chunking for a bulk query. PK chunking splits bulk queries on very large tables into chunks based on the record IDs, or primary keys, of the queried records. Each chunk is processed as a separate batch that counts toward your daily batch limit, and its results must be downloaded separately. PK chunking is supported for the following objects: Account, Campaign, CampaignMember, Case, Contact, Lead, LoginHistory, Opportunity, Task, User, and custom objects.

PK chunking works by adding record ID boundaries to the query with a WHERE clause, limiting the query results to a smaller chunk of the total results. The remaining results are fetched with additional queries that contain successive boundaries. The number of records within the ID boundaries of each chunk is referred to as the chunk size. The first query retrieves records between a specified starting ID and the starting ID plus the chunk size, the next query retrieves the next chunk of records, and so on.

1SELECT Name FROM Account

1SELECT Name FROM Account WHERE Id >= 001300000000000 AND Id < 00130000000132G
2SELECT Name FROM Account WHERE Id >= 00130000000132G AND Id < 00130000000264W
3SELECT Name FROM Account WHERE Id >= 00130000000264W AND Id < 00130000000396m
4...
5SELECT Name FROM Account WHERE Id >= 00130000000euQ4 AND Id < 00130000000fxSK

PK chunking is designed for extracting data from entire tables, but you can also use it for filtered queries. Because records might be filtered from each query’s results, the number of returned results for each chunk may be fewer than the chunk size.

The default chunk size is 100,000, and the maximum is 250,000. The default starting ID is the first record in the table. However, you can specify a different starting ID to restart a job that failed between chunked batches.

When a query is successfully chunked, the original batch’s status shows as NOT_PROCESSED, and the results are returned after the successive batches are processed. If the chunking fails, the original batch’s status shows as FAILED, but any chunked batches that were successfully queued during the chunking attempt are processed as normal.

Salesforce recommends that you enable PK chunking when querying tables with more than 10 million records or when a bulk query consistently times out. However, the effectiveness of PK chunking depends on the specifics of the query and the queried data.

Header Field Name and Values

Field name

Sforce-Enable-PKChunking

Field values

• TRUE—Enables PK chunking with the default chunk size, starting from the first record ID in the queried table.
• FALSE—Disables PK chunking. If the header isn’t provided in the request, this is the default value.
• chunkSize—Specifies the number of records within the ID boundaries for each chunk. The default is 100,000, and the maximum is 250,000. If the query contains filters, the number of returned results for each chunk might be fewer than the chunk size.
• parent—Specifies the parent object when you’re enabling PK chunking for queries on sharing objects. The chunks are based on the parent object’s records rather than the sharing object’s records. For example, when querying on AccountShare, specify Account as the parent object. PK chunking is supported for sharing objects as long as the parent object is supported.
• startRow—Specifies the 15-character or 18-character record ID to be used as the lower boundary for the first chunk. Use this parameter to specify a starting ID when restarting a job that failed between batches.

Example

Sforce-Enable-PKChunking: chunkSize=50000; startRow=00130000000xEftMGH