Listing group filters in batch jobs

AI-generated Key Takeaways

outlined_flag

• 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

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. Note that 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 AdGroupCriterion or AssetGroup the listing group filter is targeting
3. Order of operations

Consider how operations are grouped:

• All consecutive AssetGroupListingGroupFilterOperation operations targeting the same AssetGroup are grouped together in an atomic sub-batch (no partial failure behavior).
• All consecutive AdGroupCriterionOperation operations that contain a 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).

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.

Atomicity in Batch Splitting

The Google Ads API might split the operations in a submitted batch job into smaller sub-batches for processing. If you don't group related operations, such as listing group modifications within an AssetGroup and an AdGroup, consecutively within a batch job, the Google Ads API might split these operations into different sub-batches. This separation can either lead to the whole modification failing, or leaving the account in an inconsistent state.

Logical Grouping

AssetGroupListingGroupFilterOperation manages listing groups within an AssetGroup, which is common in Performance Max campaigns. AdGroupCriterionOperation manages listing groups within an AdGroup, which is common in standard Shopping campaigns. Both are used to define product targeting. If you make changes that affect the product targeting hierarchy across both contexts, group these operations consecutively in your batch job to ensure they are applied together.

Data Consistency

To maintain data consistency and prevent partial updates, add related listing group operations consecutively to your batch job. This ordering helps group them into atomic sub-batches by the API's batch splitting logic, which prevents your account from being left in an inconsistent state.

Limitations

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

• A single batch of AdGroupCriterionOperation operations containing a listing_group and targeting the same AdGroup cannot exceed 20,000 operations in length. However, it is recommended not to exceed 10,000 operations.
• A single batch of AssetGroupListingGroupFilterOperation operations targeting the same AssetGroup cannot exceed 10,000 operations.
• Violating either of these conditions results in the entire batch job failing.

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, you may find that several operations failed with a status message, Ad group is invalid due to the listing groups it contains. This message typically indicates that the operation at this index was cancelled because of a failed operation at a different index. To identify the root cause of the issue, we recommend iterating through all status messages in the BatchJobResult—before and after the index of the Ad group is invalid error message—in search of additional error information.