Ace::Iterator(3pm)

💖 Ace::Iterator — the Ace::Iterator(3pm) manual, bestie edition 💖

okay so you found Ace::Iterator, a Perl module living its best life in the User Contributed Perl Documentation section, and honestly? it's giving cursor energy. let's get into it 🦋

---

✨ NAME ✨

Ace::Iterator — iterate across an ACEDB query. yes that's the whole name, short and iconic 💅

---

🌸 SYNOPSIS 🌸

use Ace;
$db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                   -port => 20000100);

$i  = $db->fetch_many(Sequence=>'*');  # fetch a cursor
while ($obj = $i->next) {
   print $obj->asTable;
}

like, look at that. connect, grab a cursor, loop it, print it. no notes. 👑

---

🎀 DESCRIPTION 🎀

The Ace::Iterator class implements a persistent query on an Ace database. fr fr. you can have multiple simultaneous queries going at once and pull objects out of each one independently of the others — they do not talk to each other, they do not gossip, they mind their business 🙈

and why do you care? bc this is the move when a query is expected to return more objects than can easily fit into memory. no cap. the iterator is essentially a database "cursor," so it just... holds your place and hands you one thing at a time. main character energy but make it polite ✨

🌈 new() Method 🌈

$iterator = Ace::Iterator->new(-db        => $db,
                               -query     => $query,
                               -filled    => $filled,
                               -chunksize => $chunksize);

so an Ace::Iterator is returned by the Ace accessor's object's fetch_many() method. you usually will not have cause to call the new() method directly, bestie — let fetch_many() do it for you. but if you do call it yourself, here's the tea on the parameters:

• -db — the Ace database accessor object to use. that's it, that's the whole vibe.
• -query — a query, written in Ace query language, to pass to the database. this query should return a list of objects. lowercase list, big deal list, either way 📋
• -filled — if true, then retrieve complete objects from the database, rather than empty object stubs. retrieving filled objects uses more memory and network bandwidth than retrieving unfilled objects, but it's recommended if you know in advance that you will be accessing most or all of the objects' fields — for example, for the purposes of displaying the objects. basically: if you're gonna read the whole thing anyway, just get the whole thing 💖
• -chunksize — the iterator will fetch objects from the database in chunks controlled by this argument. the default is 40. you may want to tune the chunksize to optimize the retrieval for your application. it's giving ✨tunable✨

🦋 next() method 🦋

$object = $iterator->next;

this method retrieves the next object from the query, performing whatever database accesses it needs along the way. after the last object has been fetched, next() will return undef. usually you will call next() inside a loop like this:

while (my $object = $iterator->next) {
   # do something with $object
}

and now the part where i have to be real with you 😭 because of the way that object caching works, next() will be most efficient if you are only looping over one iterator at a time. although parallel access will work correctly, it will be less efficient than serial access. so if possible, avoid this type of code:

my $iterator1 = $db->fetch_many(-query=>$query1);
my $iterator2 = $db->fetch_many(-query=>$query2);
do {
   my $object1 = $iterator1->next;
   my $object2 = $iterator2->next;
} while $object1 && $object2;

warning bestie 💀 it works, it's just slower. don't come for me, come for the object cache.

---

👑 SEE ALSO 👑

• Ace
• Ace::Model
• Ace::Object

go read those too, they're all in the same friend group 🫶

---

💜 AUTHOR 💜

Lincoln Stein <lstein@cshl.org> with extensive help from Jean Thierry-Mieg <mieg@kaa.crbm.cnrs-mop.fr> — legends, honestly ⭐

Copyright (c) 1997-1998 Cold Spring Harbor Laboratory

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.

---

that's the whole page, no crumbs left 🍓 this was perl v5.42.3, dated 2026-08-19, and the page is Ace::Iterator(3pm). slay, go loop responsibly 💅✨