Use listing group filters in batch jobs

Page Summary

• Batch jobs with listing group filters are split into atomic sub-batches based on filter type, target group, and operation order.

• Consecutive AssetGroupListingGroupFilterOperation and AdGroupCriterionOperation operations targeting the same group are treated atomically in sub-batches.

• There are limits on the number of listing group filter operations allowed in a single batch targeting the same group.

• Failures in batch jobs with listing group filters can propagate, requiring a review of all status messages to find the root cause.

When you work with listing group filters in the context of an AdGroupCriterion.listing_group or an AssetGroupListingGroupFilter, take the following considerations into account when designing your integration.

Batch splitting

Key Point: We recommend adding AssetGroupListingGroupFilterOperation operations (create, update, and remove) targeting the same AssetGroup, and AdGroupCriterionOperation operations (create, update, and remove) for LISTING_GROUP criteria (AdGroupCriterion.listing_group) targeting the same AdGroup, to a batch job consecutively, so that the set of operations is treated atomically during batch splitting.

If there are any operations in a batch job that contain ad group criteria or asset group listing group filters, the operations in the batch job are split into multiple sub-batches when received by the Google Ads API server. Unlike standard operations in a batch job, each sub-batch containing listing group filter operations is treated atomically.

The way in which batch jobs containing listing group filters are split into sub-batches is determined by the following factors:

1. Type of listing group filter
2. The AdGroup or AssetGroup the listing group filter is targeting
3. Order of operations

Consider how operations are grouped:

• All consecutive AssetGroupListingGroupFilterOperation operations (create, update, and remove) targeting the same AssetGroup are grouped together in an atomic sub-batch (no partial failure behavior).
• All consecutive AdGroupCriterionOperation operations (create, update, and remove) for LISTING_GROUP criteria (AdGroupCriterion.listing_group) targeting the same AdGroup are grouped together in an atomic sub-batch (no partial failure behavior).
• All other consecutive operations are grouped together in non-atomic sub-batches (partial failure behavior).

Note: If you are also creating the AssetGroup in the same batch job, place any prerequisite AssetOperation (create) operations for new Asset resources before the AssetGroupOperation (create), followed immediately by its AssetGroupAssetOperation (create) operations (which execute together in a preceding atomic sub-batch), and then the consecutive AssetGroupListingGroupFilterOperation operations (which execute in the next atomic sub-batch). Because these form two separate sub-batches, a failure in the AssetGroupListingGroupFilterOperation sub-batch rolls back the listing group filters without rolling back the newly created AssetGroup and AssetGroupAsset resources.

Key Term: Consecutive refers to the order of the operations in the batch job. If operations targeting the same AdGroup or AssetGroup are interleaved with operations targeting a different group, they are split into separate sub-batches and are no longer processed as a single atomic transaction.

The following diagram illustrates this concept. Each of the gray boxes represents a batch job as submitted using the Google Ads API. Within the gray boxes, the individual operations are grouped by color to represent the sub-batches that the Google Ads API server creates. The order of the operations in each of the gray boxes corresponds to the order in which the operations would have been added to the batch job.

Limitations

When working with listing group filters in the context of batch jobs, the following limitations apply:

• A single atomic sub-batch of consecutive AdGroupCriterionOperation operations (create, update, and remove) for LISTING_GROUP criteria (AdGroupCriterion.listing_group) targeting the same AdGroup cannot exceed 20,000 operations in length. However, it is recommended not to exceed 10,000 operations. Because each AddBatchJobOperationsRequest is capped at 10,000 operations, an AdGroup sub-batch of 10,001 to 20,000 operations must be uploaded across at least two consecutive AddBatchJobOperations requests.
• A single atomic sub-batch of consecutive AssetGroupListingGroupFilterOperation operations (create, update, and remove) targeting the same AssetGroup cannot exceed 10,000 operations.
• Violating either of these operation count limits (or exceeding the server's internal serialized byte size limit for a single sub-batch) aborts the batch job at that sub-batch: any earlier sub-batches that already completed remain committed, while all operations in the offending sub-batch and any subsequent sub-batches fail with InternalError.INTERNAL_ERROR.

Troubleshooting

Listing group filter operations in a batch job are processed as one transaction, which can lead to scenarios where many operations fail due to a small number of erroneous operations. Further, because of the way BatchJob operations are processed, the root cause of the failures may appear at an index before or after the downstream failures.

For example, when processing a response from ListBatchJobResults:

• For AdGroupCriterionOperation listing groups, you may find that consecutive operations targeting the same AdGroup failed with CriterionError.LISTING_GROUP_ERROR_IN_ANOTHER_OPERATION (Product group operations are atomic within the same ad group. This operation failed because another operation targeting the same ad group ID was invalid.).
• For AssetGroupListingGroupFilterOperation operations, you may find that consecutive operations targeting the same AssetGroup failed with BatchJobError.ASSET_GROUP_LISTING_GROUP_FILTER_TRANSACTION_FAILURE.

These errors indicate that the operation at that index was rolled back because another operation in the same atomic sub-batch failed. To identify the root cause of the issue, iterate through the status messages in each BatchJobResult—before and after the operation_index of the transaction error—for operations sharing the same AdGroup or AssetGroup ID.