Apex Reference Guide
jQueryHandle Class
Tracks the runtime execution state of a Data 360 SQL query as it progresses through submission, execution, and result retrieval. Use QueryHandle to resume a previously submitted query from a saved query ID in a new SqlRowIterator or a new SqlQueueable job.
Namespace
Usage
QueryHandle doesn't expose getters to subscribers. All internal state—query ID, data space, workload name, offset, and lifecycle flags—is managed by SqlRowIterator and SqlQueueable. Use SqlRowIterator.getQueryId() or SqlQueueable.getQueryId() to retrieve the query ID. When you resume from a saved query ID, call withOffset() to tell the framework how many rows were already processed so it resumes from the correct position.
Example
Resume a previously submitted query:
1sfsqlquery.QueryHandle handle = sfsqlquery.QueryHandle.create('my-query-id-123', 'default')
2 .withWorkloadName('my_workload')
3 .withOffset(500);
4
5sfsqlquery.SqlRowIterator iterator = new sfsqlquery.SqlRowIterator(handle);
6for (sfsqlquery.Row row : iterator) {
7 System.debug(row.getString('Name__c'));
8}QueryHandle Methods
The following are methods for QueryHandle.
create(queryId, dataspace)
Creates a QueryHandle from a previously submitted query ID and data space name. Use this method to resume fetching results for a query that was submitted in an earlier transaction.
Signature
public static sfsqlquery.QueryHandle create(String queryId, String dataspace)
Parameters
withOffset(offset)
Sets the row offset at which to begin fetching results and returns the same QueryHandle instance for method chaining. Use this when resuming a query to skip rows that were already processed.
Signature
public sfsqlquery.QueryHandle withOffset(Long offset)
Parameters
- offset
- Type: Long
- 0-based row offset at which to begin fetching results.
Example
Resume processing after 500 rows were already processed:
1// In a previous transaction, you processed 500 rows and saved the query ID
2Integer rowsProcessed = 500;
3String savedQueryId = 'my-query-id-123';
4
5// In a later transaction, resume from where you left off
6sfsqlquery.QueryHandle handle = sfsqlquery.QueryHandle.create(savedQueryId, 'default')
7 .withOffset(rowsProcessed); // Skip the 500 rows already processed
8
9sfsqlquery.SqlRowIterator iterator = new sfsqlquery.SqlRowIterator(handle);
10while (iterator.hasNext()) {
11 sfsqlquery.Row row = iterator.next();
12 // Continue processing from row 501 onward
13 rowsProcessed++;
14}withWorkloadName(name)
Sets the workload name to use when fetching results and returns the same QueryHandle instance for method chaining.
Signature
public sfsqlquery.QueryHandle withWorkloadName(String name)
Parameters
- name
- Type: String
- Custom workload name to associate with result fetch requests. Set this value to help Salesforce Customer Support assist you with debugging issues