Stateless and Stateful Modes
AQuA supports a stateless mode and a stateful mode. In stateless mode, AQuA executes the queries as is. In stateful mode, AQuA establishes a continuous session among a series of requests.
Zuora highly recommends you use the stateless mode instead of the stateful mode to extract bulk data. See Bulk data extraction from Zuora using AQuA for best practices.
The AQuA Job Finder enables you to view all AQuA requests and results executed on your tenant up to the last 72 hours. AQuA results older than 72 hours are automatically purged from the system. Excessive usage of non statefull, full queries is not advised, and instead, stateful AQuA should be used.
Stateless and Stateful Modes
AQuA can be executed in the following modes:
| Mode | Description |
|---|---|
| Stateless |
In Stateless mode, queries are executed as is. When running in Stateless mode, all Export ZOQL and ZOQL queries supplied in the API input body are executed in a sequential order. All data which satisfies the query criteria is returned. AQuA queries are carried out in Stateless mode when the following occurs:
or
|
| Stateful |
In Stateful mode, AQuA establishes a continuous session across a series of requests. AQuA queries are executed in Stateful mode when the version is 1.1 and both You can specify a combination of Submit a request at Zuora Global Support to obtain a partner ID. The first request executes queries against all data in the database, and returns all data that satisfies the query criteria. Subsequent requests execute the queries against incremental data created or updated since the last AQuA session. Each request returns incremental data for only the object specified in the Note that if the last request of a stateful AQuA query was submitted more than 180 days ago, Zuora executes the query against all data in the database. The Stateful AQuA is best used for continuous data integration between Zuora and a target system. AQuA sessions with the same Tenant ID, Partner ID, and Project ID cannot run in parallel. When this occurs, they are executed sequentially in the order in which they were received. For example, if an AQuA job is running, and another AQuA job with same Tenant ID, Partner ID, and Project ID is submitted, the second job will not be executed until the first job is complete. |
Automatic Switch Between Full Load and Incremental Load
When you first call AQuA in stateful mode, AQuA uses the combination of partner and project as the unique identifier of a new session. The results file of the first call contains a full load of data for each of the requested queries. If you make subsequent calls with the same values of partner and project, either requesting the same queries or without any queries specified, the results file contains an incremental load of data for each query.
However, while you keep partner and project the same as previous calls, the results file will contain a full load of data for the query on which you make any of the following changes:
- You change the SQL of the query
- You introduce a deleted column into the query
- You drop a deleted column from the query
- You change the name or type of a deleted column in the query
If you introduce an additional query into the AQuA call while keeping partner and project the same, AQuA initially returns a full load of data for the new query.
In every AQuA job status response, the field full indicates whether the returned data for a query is a full load or an incremental load.
Time Offset for AQuA Stateful Queries
In stateful mode, by default Zuora returns data that were created or updated between the completion time of the previous stateful query and the current time. However, you can configure a time offset to control the end time of this interval using either of the following approaches:
For example, suppose that you set the AQuA API Stateful Mode Time Offset to 600 seconds. If you execute a query in stateful mode at 2:00 AM, Zuora returns data created or updated between the completion time of the previous stateful query and 1:50 AM.
If you use the offset parameter in the request body when submitting a query, the offset value in the request body will take effect rather than the value in the AQuA API Stateful Mode Time Offset setting.
Examples
Full Load for a New Query
For example, if you want to retrieve the data of two custom fields from Invoice object, that were not in the previous AQUA queries, you can add a new query "Select My_Custom1__c, My_Custom2__c From Invoice" in the AQUA queries. Stateful AQUA returns all records of Invoice object, containing these two custom fields.
Retrieve Deleted Data
The following use case provides an example of how to retrieve deleted data.
In addition to the query capabilities currently supported by ZOQL and Export ZOQL, AQUA can retrieve records that have been deleted. This capability is especially important if you use Stateful AQUA for continuous data integration.
JSON request:
{
"format":"gzip",
"version" : "1.1",
"encrypted" : "none",
"useQueryLabels" : "true",
"partner" : "salesforce",
"project" : "00170000011K3Ub",
"name" : "submit_002",
"queries" : [
{ "name" : "CreditBalanceAdjustment",
"type" : "zoql",
"query" : "select AccountId,AccountingCode,AdjustmentDate,Amount,CreatedDate,Id,Number,
SourceTransactionType,Status,Type,UpdatedDate from CreditBalanceAdjustment"
},
{ "name" : "AccountingPeriod",
"type" : "zoql",
"query" : "select Id,StartDate,EndDate,FiscalYear,Name,Status,UpdatedDate from AccountingPeriod"
},
{ "name" : "ProductRatePlan",
"type" : "zoql",
"query" : "select Id, Description, Name, CreatedDate, EffectiveEndDate,
EffectiveStartDate, ProductId, UpdatedDate from ProductRatePlan"
},
{ "name" : "InvoiceAdjustmentQuery" ,
"type" : "zoqlexport",
"query" : "select AccountingCode,CancelledOn,CreatedDate,Id,ImpactAmount, Invoice.Id,InvoiceNumber,AdjustmentNumber,AdjustmentDate,Amount,
Status,Account.Id,Type,ReasonCode,UpdatedDate from InvoiceAdjustment",
"deleted" : {
"column" : "MyDeletedColumn",
"format" : "Boolean" // Remember it is Boolean not boolean.
}
}
]
}
JSON response:
{
"partner" : "salesforce",
"project" : "00170000011K3Ub",
"batches" : [ {
"name" : "CreditBalanceAdjustment",
"query" : "select AccountId,AccountingCode,AdjustmentDate,Amount,CreatedDate,Id,Number,SourceTransactionType,Status,Type,UpdatedDate from CreditBalanceAdjustment",
"status" : "pending",
"recordCount" : 0,
"batchType" : "zoql",
"batchId" : "2c9083c346f3830d0146f3867cc1056a"
}, {
"name" : "AccountingPeriod",
"query" : "select Id,StartDate,EndDate,FiscalYear,Name,Status,UpdatedDate from AccountingPeriod",
"status" : "pending",
"recordCount" : 0,
"batchType" : "zoql",
"batchId" : "2c9083c346f3830d0146f3867cc3056b"
}, {
"name" : "ProductRatePlan",
"query" : "select Id, Description, Name, CreatedDate, EffectiveEndDate, EffectiveStartDate, ProductId, UpdatedDate from ProductRatePlan",
"status" : "pending",
"recordCount" : 0,
"batchType" : "zoql",
"batchId" : "2c9083c346f3830d0146f3867cc5056c"
}, {
"deleted" : {
"column" : "MyDeletedColumn",
"format" : "Boolean"
},
"full" : true,
"name" : "InvoiceAdjustmentQuery",
"query" : "select AccountingCode,CancelledOn,CreatedDate,Id,ImpactAmount,Invoice.Id,InvoiceNumber,
AdjustmentNumber,AdjustmentDate,Amount,Status,Account.Id,Type,ReasonCode,UpdatedDate from InvoiceAdjustment",
"status" : "pending",
"recordCount" : 0,
"batchType" : "zoqlexport",
"batchId" : "2c9083c346f3830d0146f3867cc7056d"
} ],
"name" : "submit_002",
"id" : "2c9083c346f3830d0146f3867ca90569",
"version" : "1.1",
"format" : "GZIP",
"status" : "submitted",
"encrypted" : "none"
}