Search...Scroll(3pm)

📦 version 7.715, in ubuntu jammy

💖 Search::Elasticsearch::Client::7_0::Scroll — bestie edition 💖

okay so welcome to Search::Elasticsearch::Client::7_0::Scroll, a lil helper module (from the User Contributed Perl Documentation, hi) that makes scrolled searches soooo much easier. version 7.715, no cap. 🦋

✨ VERSION ✨

version 7.715 — yes bestie, that's the one. 💅

🌸 SYNOPSIS 🌸

use Search::Elasticsearch;

my $es     = Search::Elasticsearch->new;

my $scroll = $es->scroll_helper(
    index       => 'my_index',
    body => {
        query   => {...},
        size    => 1000,
        sort    => '_doc'
    }
);

say "Total hits: ". $scroll->total;

while (my $doc = $scroll->next) {
    # do something
}

like. look at that. it's giving effortless. ✨

🎀 DESCRIPTION 🎀

So a scrolled search is a search that lets you keep pulling results until there are literally no more matching results left. it's basically a cursor in an SQL database but make it Elasticsearch. 💖

And here's the tea: unlike paginating through results (that's with the from parameter in search()), a scrolled search takes a snapshot of the current state of the index. so even if you keep adding new documents to the index, or updating existing ones, the scrolled search will only ever see the index as it was when the search began. it's frozen in time, main character energy. ❄️👑

This module is a helper utility that wraps the functionality of the search() and scroll() methods to make them easier to use. bestie behaviour, honestly. 🫶

This class does Search::Elasticsearch::Client::7_0::Role::Scroll and Search::Elasticsearch::Role::Is_Sync. periodt.

🌈 USE CASES 🌈

There are two primary use cases, and they're both lowkey iconic:

💜 Pulling enough results

Maybe you wanna group your results by some field, and you don't know exactly how many results you'll need to return 10 grouped results. with a scrolled search you can just keep pulling more until you have enough. no stress. for instance, you can search emails in a mailing list and return results grouped by thread_id:

my (%groups,@results);

my $scroll = $es->scroll_helper(
    index => 'my_emails',
    type  => 'email',
    body  => { query => {... some query ... }}
);

my $doc;
while (@results < 10 and $doc = $scroll->next) {

    my $thread = $doc->{_source}{thread_id};

    unless ($groups{$thread}) {
        $groups{$thread} = [];
        push @results, $groups{$thread};
    }
    push @{$groups{$thread}},$doc;

}

see how it just keeps going until @results < 10 is a no? chef's kiss. 👩‍🍳💋

🦋 Extracting all documents

Often you'll want to extract all (or a subset of) documents in an index. like, if you wanna change your type mappings you're gonna need to reindex all your data. or maybe you wanna move a subset of the data in one index into a new dedicated index. in these cases you don't care about sort order, you just want to retrieve all documents which match a query and do something with them. for instance, to retrieve all the docs for a particular client_id:

my $scroll = $es->scroll_helper(
    index       => 'my_index',
    size        => 1000,
    body        => {
        query => {
            match => {
                client_id => 123
            }
        },
        sort => '_doc'
    }
);

while (my $doc = $scroll->next) {
    # do something
}

and very often, the something you'll wanna do with these results involves bulk-indexing them into a new index. the easiest way to do that is to use the built-in reindex() in Search::Elasticsearch::Client::7_0::Direct functionality provided by Elasticsearch. slay. 🔥

💅 METHODS 💅

💖 `new()`

use Search::Elasticsearch;

my $es = Search::Elasticsearch->new(...);
my $scroll = $es->scroll_helper(
    scroll         => '1m',            # optional
    %search_params
);

The scroll_helper() in Search::Elasticsearch::Client::7_0::Direct method loads the Search::Elasticsearch::Client::7_0::Scroll class and calls new(), passing in any arguments. so it's all handled for you, bestie. 🫶

You can specify a scroll duration (which defaults to 1m). any other parameters are passed directly to search() in Search::Elasticsearch::Client::7_0::Direct.

The scroll duration tells Elasticearch how long it should keep the scroll alive. > note: this duration doesn't need to be long enough to process all results — just long enough to process a single batch of results. the expiry gets renewed for another scroll period every time a new batch of results is retrieved from the cluster. it's self-renewing, it's giving immortal. ♻️✨

By default, the scroll_id is passed as the body to the scroll request.

The scroll request uses GET by default. to use POST instead, set send_get_body_as to POST.

💖 `next()`

$doc  = $scroll->next;
@docs = $scroll->next($num);

The next() method returns the next result, or the next $num results (pulling more results if required). if all results have been exhausted, it returns an empty list. that's it, that's the whole vibe. 🎀

💖 `drain_buffer()`

@docs = $scroll->drain_buffer;

The drain_buffer() method returns all of the documents currently in the buffer, without fetching any more from the cluster. just emptying the lil bucket you already got. 🍓

💖 `refill_buffer()`

$total = $scroll->refill_buffer;

The refill_buffer() method fetches the next batch of results from the cluster, stores them in the buffer, and returns the total number of docs currently in the buffer. top me up bestie. 🧚

💖 `buffer_size()`

$total = $scroll->buffer_size;

The buffer_size() method returns the total number of docs currently in the buffer. a lil peek, no fetching, no drama. 👀

💖 `finish()`

$scroll->finish;

The finish() method clears out the buffer, sets is_finished() to true and tries to clear the scroll_id on Elasticsearch. this API is only supported since v0.90.6, but the call to clear_scroll is wrapped in an eval so the finish() method can be safely called with any version of Elasticsearch. safe, no matter what. 💀➡️💖

When the $scroll instance goes out of scope, finish() is called automatically if required. so it cleans up after itself, unlike some people. 😭

💖 `is_finished()`

$bool = $scroll->is_finished;

A flag which returns true if all results have been processed or finish() has been called. a little yes/no bestie. ✅

👑 INFO ACCESSORS 👑

The information from the original search is returned via the following accessors — all the receipts from your original search, right here:

⭐ `total`

The total number of documents that matched your query.

⭐ `max_score`

The maximum score of any documents in your query.

⭐ `aggregations`

Any aggregations that were specified, or undef

⭐ `facets`

Any facets that were specified, or undef

⭐ `suggest`

Any suggestions that were specified, or undef

⭐ `took`

How long the original search took, in milliseconds

⭐ `took_total`

How long the original search plus all subsequent batches took, in milliseconds.

🌟 SEE ALSO 🌟

search() in Search::Elasticsearch::Client::7_0::Direct
scroll() in Search::Elasticsearch::Client::7_0::Direct
reindex() in Search::Elasticsearch::Client::7_0::Direct

go read those too, iykyk. 📚✨

🫶 AUTHOR 🫶

Enrico Zimuel <enrico.zimuel@elastic.co> — legend behaviour, honestly. 💜

📜 COPYRIGHT AND LICENSE 📜

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

okay that's the whole page bestie, you ate it up fr fr 💅✨ this was Search...Scroll(3pm), running on perl v5.32.1, dated 2021-10-23 — mwah, bye! 🎀🦋💖

📦 where this page comes from

ubuntu jammy: libsearch-elasticsearch-perl 7.715-1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Search...Scroll(3pm)

💖 Search::Elasticsearch::Client::7_0::Scroll — bestie edition 💖

✨ VERSION ✨

🌸 SYNOPSIS 🌸

🎀 DESCRIPTION 🎀

🌈 USE CASES 🌈

💜 Pulling enough results

🦋 Extracting all documents

💅 METHODS 💅

💖 new()

💖 next()

💖 drain_buffer()

💖 refill_buffer()

💖 buffer_size()

💖 finish()

💖 is_finished()