Iterators

  • Iterators are a programming pattern for traversing lists of objects, especially when the list size is unknown or loading the whole list is resource-intensive.

  • Iterators expose two methods: boolean hasNext() and Object next().

  • Google Ads scripts use the Iterator pattern for fetching Google Ads entities.

  • You can traverse an iterator using a while loop with hasNext() and next(), or using built-in JavaScript iteration.

  • Applying withLimit() to a selector does not change the result of totalNumEntities().

Iterators are a common programming pattern used for traversing a list of objects when

  • The size of the list may not be known from the start.
  • Loading the entire list into memory at once may prove overly resource intensive.

Iterators expose two methods: boolean hasNext() and Object next(). Google Ads scripts use the Iterator pattern for fetching Google Ads entities.

Functionally, iterators are not too different from regular arrays, and can make your code more concise. Compare the code that traverses an array:

for (var i = 0; i < myArray.length; i++) {
  let myObject = myArray[i];
}

with code that traverses an iterator:

while (myIterator.hasNext()) {
  let myObject = myIterator.next();
}

The following code demonstrates the usage of an iterator over all Search and Display campaigns in your account:

var campaignIterator = AdsApp.campaigns().get();

while (campaignIterator.hasNext()) {
  let campaign = campaignIterator.next();
  console.log(`${campaign.getName()}; active? ${campaign.isEnabled()}; ` +
      `budget=${campaign.getBudget().getAmount()}`);
}

You can also use built-in JavaScript iteration:

for (const campaign of AdsApp.campaigns()) {
  console.log(`${campaign.getName()}; active? ${campaign.isEnabled()}; ` +
      `budget=${campaign.getBudget().getAmount()}`);
}

Application of withLimit() to a selector does not change the value of totalNumEntities(). x and y in the following snippet will have the same value:

var x = AdsApp.keywords().get().totalNumEntities();
var y = AdsApp.keywords().withLimit(5).get().totalNumEntities();

In order to obtain an Iterator of Google Ads entities, you must construct a Selector first.