Iterators

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 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.