Search...Direct(3pm)

📦

version 6.81 · 3 versions

6.81 · ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
6.81 · ubuntu jammy
6.81 · debian bookworm, debian trixie

, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Search::Elasticsearch::Client::1_0::Direct — the manual, but make it cute 💖

okay bestie, gather round, because we're about to read Search...Direct(3pm) together and honestly? it's giving very useful. it's from the User Contributed Perl Documentation, section 3pm. let's get into it 🫶

✨ NAME ✨

Search::Elasticsearch::Client::1_0::Direct — a thin client with full support for Elasticsearch 1.x APIs. thin as in no unnecessary drama, but fully booked and ready for every API, periodt 💅

🌈 VERSION 🌈

version 6.81 — yes, that's the one, no cap.

🎀 SYNOPSIS 🎀

okay so first things first, you make yourself a client:

use Search::Elasticsearch;
my $e = Search::Elasticsearch->new(
    client => '1_0::Direct'
);

boom. icon behavior. now you can do stuff with $e 🦋

Index a doc — put a document in there:

$e->index(
    index   => 'my_index',
    type    => 'blog_post',
    id      => 123,
    body    => {
        title   => "Elasticsearch clients",
        content => "Interesting content...",
        date    => "2013-09-23"
    }
);

Get a doc — pull it back out:

$e->get(
    index   => 'my_index',
    type    => 'my_type',
    id      => 123
);

Search for docs — the main character move:

$results = $e->search(
    index   => 'my_index',
    body    => {
        query => {
            match => {
                title => "elasticsearch"
            }
        }
    }
);

Index-level requests — managing whole indices, slay:

$e->indices->create( index => 'my_index' );
$e->indices->delete( index => 'my_index' )

Cluster-level requests — checking on the whole cluster's vibe:

$health = $e->cluster->health;

Node-level requests — peeking at individual nodes:

$info  = $e->nodes->info;
$stats = $e->nodes->stats;

Snapshot and restore — backups, because we're responsible queens:

$e->snapshot->create_repository(
    repository => 'my_backups',
    type       => 'fs',
    settings   => {
        location => '/mnt/backups'
    }
);

$e->snapshot->create(
    repository => 'my_backups',
    snapshot   => 'backup_2014'
);

cat debugging — when you just want readable text, not JSON:

say $e->cat->allocation;
say $e->cat->health;

💜 DESCRIPTION 💜

so the Search::Elasticsearch::Client::1_0::Direct class gives you the Elasticsearch 1.x compatible client — it's the one you get back when you do this:

$e = Search::Elasticsearch->new( cxn => '1_0::Direct' );

the whole goal here? be as close as humanly possible to the native REST API that Elasticsearch itself uses. like, the way that you can literally look at the Elasticsearch reference documentation <http://www.elasticsearch/guide> for any API and translate it straight across into this client? obsessed. effortless. iconic.

this class is the one holding down the methods for document CRUD, bulk document CRUD, and search. it also hands you the clients for managing indices and the cluster. a multitasking legend, fr fr.

🧚 CONVENTIONS 🧚

🌸 Parameter passing 🌸

you can pass params to any request method as a list or as a hash reference. these two lines are literally the same thing, no difference, zero:

$e->search( size => 10 );
$e->search({size => 10});

🦋 Path parameters 🦋

any values that belong in the URL path — think stuff like "/{index}/{type}" — get passed as top level parameters:

$e->search( index => 'my_index', type => 'my_type' );

or, if you're feeling direct, you can specify a path parameter yourself:

$e->search( path => '/my_index/my_type' );

⭐ Query-string parameters ⭐

anything that belongs in the query string? also top level parameters, bestie:

$e->search( size => 10 );

now here's a lil curveball: if you pass in a \%params hash, it gets dropped into the query string parameters with zero error checking. so this:

$e->search( size => 10, params => { from => 5, size => 5 })

would give you this query string:

?from=5&size=10

(yeah, size => 10 wins over the size => 5 in the hash. noted. 📝)

🎀 Body parameter 🎀

the request body goes in the body key:

$e->search(
    body => {
        query => {...}
    }
);

the body can also be a UTF8-decoded string, in which case it gets converted into UTF-8 bytes and passed as is:

$e->indices->analyze( body => "The quick brown fox");

💖 Filter path parameter 💖

any API that returns a JSON body accepts a filter_path parameter, which filters the JSON down to only the paths you specify. so say you're running a search request and you only want the total hits plus the _source field for each hit (and NOT the _id, _index, etc) — you'd do:

$e->search(
    query => {...},
    filter_path => [ 'hits.total', 'hits.hits._source' ]
);

this parameter was added in Elasticsearch 1.6.0. so if you're on something older, it's not gonna know what you're talking about 🥲

🌈 Ignore parameter 🌈

usually, any HTTP status code outside the 200-299 range means an error gets thrown. but if you want to suppress those errors, you tell it which status codes to ignore via the ignore parameter:

$e->indices->delete(
    index  => 'my_index',
    ignore => 404
);

this is most useful for Missing errors — those are the ones triggered by a 404 status code when some requested resource just... doesn't exist. RIP to that resource 🪦

multiple error codes? pass an array:

$e->indices->delete(
    index  => 'my_index',
    ignore => [404,409]
);

💅 CONFIGURATION 💅

`"bulk_helper_class"`

the class to use for the bulk_helper() method. defaults to Search::Elasticsearch::Client::1_0::Bulk.

`"scroll_helper_class"`

the class to use for the scroll_helper() method. defaults to Search::Elasticsearch::Scroll.

👑 GENERAL METHODS 👑

`"info()"`

$info = $e->info

returns info about the version of Elasticsearch that the responding node is running. cute lil intel 🕵️

`"ping()"`

$e->ping

pings a node in the cluster and returns 1 if it gets a 200 response back. otherwise? it throws an error, sorry bestie 😭

`"indices()"`

$indices_client = $e->indices;

returns a Search::Elasticsearch::Client::1_0::Direct::Indices object, which you use for managing indices — creating them, deleting them, managing mapping, index settings, all of it ✨

`"cluster()"`

$cluster_client = $e->cluster;

returns a Search::Elasticsearch::Client::1_0::Direct::Cluster object, for managing the cluster — cluster-wide settings, cluster health, that whole thing 🩺

`"nodes()"`

$node_client = $e->nodes;

returns a Search::Elasticsearch::Client::1_0::Direct::Nodes object, which you use to retrieve node info and stats 📊

`"snapshot()"`

$snapshot_client = $e->snapshot;

returns a Search::Elasticsearch::Client::1_0::Direct::Snapshot object, used for managing backup repositories and creating and restoring snapshots 💾

`"cat()"`

$cat_client = $e->cat;

returns a Search::Elasticsearch::Client::1_0::Direct::Cat object, which gives you simple to read text info for debugging and monitoring an Elasticsearch cluster 🐱

and that's part 1, bestie — there's more coming, so don't go anywhere 💖

📝 DOCUMENT CRUD METHODS 📝

okay bestie, this is where it gets fun. These methods let you do the create / index / update / delete thing for one single document at a time. Single. One. No group projects here 💅

`index()`

$response = $e->index(
    index   => 'index_name',        # required
    type    => 'type_name',         # required
    id      => 'doc_id',            # optional, otherwise auto-generated

    body    => { document }         # required
);

So index() is your girl for indexing a brand-new document, or reindexing one that already exists. Either way she eats. ✨

Query string parameters, fr fr:

consistency
op_type
parent
refresh
replication
routing
timeout
timestamp
ttl
version
version_type

For the tea, the actual index docs live here: http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html 🔥

`create()`

$response = $e->create(
    index   => 'index_name',        # required
    type    => 'type_name',         # required
    id      => 'doc_id',            # optional, otherwise auto-generated

    body    => { document }         # required
);

ngl create() is literally the same girl as index(), except — and this is the whole personality — she will throw a Conflict error if a document with that same index, type and id is already out here existing. She does not do duplicates. periodt. 💀

Query string parameters:

consistency
op_type
parent
refresh
replication
routing
timeout
timestamp
ttl
version
version_type

create docs, if you want the receipts: http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-create.html 🫶

`get()`

$response = $e->get(
    index   => 'index_name',        # required
    type    => 'type_name',         # required
    id      => 'doc_id',            # required
);

get() goes and fetches the document matching your index, type and id. And if she can't find it? She throws a Missing error. no cap, she will make it a whole thing 😭

Query string parameters:

_source
_source_exclude
_source_include
fields
parent
preference
realtime
refresh
routing
version
version_type

get docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html 🌸

`get_source()`

$response = $e->get_source(
    index   => 'index_name',        # required
    type    => 'type_name',         # required
    id      => 'doc_id',            # required
);

get_source() = get() but she only gives you the _source field back. You know, that's literally the value of the body parameter you handed to index(). What you do NOT get is the document metadata — so no _index, no _type, none of that. Just the source, minimal, main character, unbothered. 👑

Query string parameters:

_source
_source_exclude
_source_include
parent
preference
realtime
refresh
routing
version
version_type

get_source docs (same link, she shares): http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html 💖

`exists()`

$response = $e->exists(
    index   => 'index_name',        # required
    type    => 'type_name',         # required
    id      => 'doc_id',            # required
);

exists() returns 1 if a document with that index, type and id is out here living, or an empty string if she isn't. that's it. yes/no. vibe check complete. ✅

Query string parameters:

parent
preference
realtime
refresh
routing

exists docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html 🌈

`delete()`

$response = $e->delete(
    index   => 'index_name',        # required
    type    => 'type_name',         # required
    id      => 'doc_id',            # required
);

delete() removes the document with your index, type and id. But bestie — if she can't find it, she throws a Missing error. she's dramatic like that, and honestly? valid. 💅

Query string parameters:

consistency
parent
refresh
replication
routing
timeout
version
version_type

delete docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete.html 🦋

`update()`

$response = $e->update(
    index   => 'index_name',        # required
    type    => 'type_name',         # required
    id      => 'doc_id',            # required

    body    => { update }           # required
);

update() updates the document matching index, type and id, but ONLY if she exists. And you've got two whole ways to do this update, pick your fighter:

toss in a partial document and she'll merge it into the existing one:

$response = $e->update(
    ...,
    body => {
        doc => { new_field => 'new_value'},
    }
);

or do it with a script:

$response = $e->update(
    ...,
    body => {
        script => "ctx._source.counter += incr",
        params => { incr => 5 }
    }
);

Query string parameters:

consistency
fields
lang
parent
realtime
refresh
replication
retry_on_conflict
routing
script
script_id
scripted_upsert
timeout
timestamp
ttl
version
version_type

update docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update.html ⭐

`termvectors()`

$results = $e->termvectors(
    index   => $index,          # required
    type    => $type,           # required

    id      => $id,             # optional
    body    => {...}            # optional
)

termvectors() pulls term and field statistics, positions, offsets and payloads for the document you point her at — assuming termvectors have been enabled for it. iykyk 🧚

Query string parameters:

dfs
field_statistics
fields
offsets
parent
payloads
positions
preference
realtime
routing
term_statistics
version
version_type

termvector docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-termvectors.html 🍓

🦋 BULK DOCUMENT CRUD METHODS 🦋

Okay bestie, this is the glow-up section. The bulk document CRUD methods are literally how you run multiple CRUD actions inside a single request. And because you're cutting down the number of network requests you gotta make, bulk requests greatly improve performance. It's giving efficiency, it's giving main character energy, it's giving fewer round trips. 💅

💖 `bulk()`

$response = $e->bulk(
    index   => 'index_name',        # required if type specified
    type    => 'type_name',         # optional

    body    => [ actions ]          # required
);

Check out Search::Elasticsearch::Client::1_0::Bulk and "bulk_helper()" for a helper module that makes bulk indexing way simpler to use. iykyk

The bulk() method can perform multiple index(), create(), delete() or update() actions with a single request. The body parameter expects an array containing the list of actions to perform.

An action is made of an initial metadata hash ref containing the action type, plus the associated metadata, eg:

{ delete => { _index => 'index', _type => 'type', _id => 123 }}

The index and create actions then expect a hashref containing the document itself:

{ create => { _index => 'index', _type => 'type', _id => 123 }},
{ title => "A newly created document" }

And the update action expects a hashref containing the update commands, eg:

{ update => { _index => 'index', _type => 'type', _id => 123 }},
{ script => "ctx._source.counter+=1" }

Every single action can include the same parameters that you'd pass to the equivalent index(), create(), delete() or update() request — EXCEPT that _index, _type and _id must be specified with the preceding underscore. All the other parameters? You can write them with or without the underscore, girl, your call. 🫶

For instance:

$response = $e->bulk(
    index   => 'index_name',        # default index name
    type    => 'type_name',         # default type name
    body    => [

        # create action
        { create => {
            _index => 'not_the_default_index',
            _type  => 'not_the_default_type',
            _id    => 123
        }},
        { title => 'Foo' },

        # index action
        { index => { _id => 124 }},
        { title => 'Foo' },

        # delete action
        { delete => { _id => 125 }},

        # update action
        { update => { _id => 126 }},
        { script => "ctx._source.counter+1" }
    ]
);

Each action is performed separately. So if one action flops, it will not cause the others to fail as well. Resilient queen behavior, honestly. 💀

Query string parameters:

"consistency"
"refresh"
"replication"
"timeout"

See the bulk docs at http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html for more info. 📚

🌸 `bulk_helper()`

$bulk_helper = $e->bulk_helper( @args );

Returns a new instance of the class specified in the bulk_helper_class, which defaults to Search::Elasticsearch::Client::1_0::Bulk. ✨

🎀 `mget()`

$results = $e->mget(
    index   => 'default_index',     # optional, required when type specified
    type    => 'default_type',      # optional

    body    => { docs or ids }      # required
);

The mget() method will retrieve multiple documents with a single request. The body consists of an array of documents to retrieve:

$results = $e->mget(
    index   => 'default_index',
    type    => 'default_type',
    body    => {
        docs => [
            { _id => 1},
            { _id => 2, _type => 'not_the_default_type' }
        ]
    }
);

You can also pass any of the other parameters that the get() request accepts. Flexible much?

If you've specified an index and type, you can just include the ids of the documents to retrieve:

$results = $e->mget(
    index   => 'default_index',
    type    => 'default_type',
    body    => {
        ids => [ 1, 2, 3]
    }
);

Query string parameters:

"_source"
"_source_exclude"
"_source_include"
"fields"
"preference"
"realtime"
"refresh"

See the mget docs at http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html for more. 🌈

🦋 `delete_by_query()`

$result = $e->delete_by_query(
    index => 'index' | \@indices,   # required
    type  => 'type'  | \@types,     # optional

    body  => { query }              # required

);

The delete_by_query() method deletes all documents which match the query. For instance, to delete all documents from 2012:

$result = $e->delete_by_query(
    body  => {
        query => {
            range => {
                date => {
                    gte => '2012-01-01',
                    lt  => '2013-01-01'
                }
            }
        }
    }
);

Be careful with this one bestie, it really does delete everything that matches. 😭

Query string parameters:

"allow_no_indices"
"analyzer"
"consistency"
"default_operator"
"df"
"expand_wildcards"
"ignore_unavailable"
"q"
"replication"
"routing"
"timeout"

See the delete_by_query docs at http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html for more. 🍓

🧚 `mtermvectors()`

$results = $e->mtermvectors(
    index   => $index,          # required if type specified
    type    => $type,           # optional

    body    => { }              # optional
)

Runs multiple termvector() requests in a single request, eg:

$results = $e->mtermvectors(
    index   => 'test',
    body    => {
        docs => [
            { _type => 'test', _id => 1, fields => ['text'] },
            { _type => 'test', _id => 2, payloads => 1 },
        ]
    }
);

Query string parameters:

"field_statistics"
"fields"
"ids"
"offsets"
"parent"
"payloads"
"positions"
"preference"
"realtime"
"routing"
"term_statistics"
"version"
"version_type"

See the mtermvectors docs at http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-termvectors.html for more. 👑

✨ SEARCH METHODS ✨

The search methods are used for querying documents in one, more or all indices and of one, more or all types. This is the part everyone actually came for, let's be honest. 💅

🔥 `search()`

$results = $e->search(
    index   => 'index' | \@indices,     # optional
    type    => 'type'  | \@types,       # optional

    body    => { search params }        # optional
);

The search() method searches for matching documents in one or more indices. It is just as easy to search a single index as it is to search all the indices in your cluster. It can also return aggregations (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html), highlighted snippets (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-highlighting.html) and did-you-mean (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-phrase.html) or search-as-you-type (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-completion.html) suggestions. Obsessed. 😍

The lite version of search (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-uri-request.html) lets you specify a query string in the q parameter, using the Lucene query string syntax:

$results = $e->search( q => 'title:(elasticsearch clients)');

However, the preferred way to search is by using the Query DSL (http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html) to create a query, and passing that query in the request body (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html):

$results = $e->search(
    body => {
        query => {
            match => { title => 'Elasticsearch clients'}
        }
    }
);

Query string parameters:

"_source"
"_source_exclude"
"_source_include"
"allow_no_indices"
"analyze_wildcard"
"analyzer"
"default_operator"
"df"
"expand_wildcards"
"explain"
"fielddata_fields"
"fields"
"from"
"ignore_unavailable"
"lenient"
"lowercase_expanded_terms"
"preference"
"q"
"query_cache"
"routing"
"scroll"
"search_type"
"size"
"sort"
"stats"
"suggest_field"
"suggest_mode"
"suggest_size"
"suggest_text"
"terminate_after"
"timeout"
"track_scores"
"version"

See the search reference (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html) for more.

Also see "send_get_body_as" in Search::Elasticsearch::Transport. 🫶

💜 `search_exists()`

The search_exists() method is a quick version of search which can be used to find out whether there are matching search results or not. It doesn't return any results itself. It's like a vibe check but for your query.

$results = $e->search_exists(
    index   => 'index' | \@indices,     # optional
    type    => 'type'  | \@types,       # optional

    body    => { search params }        # optional
);

Query string parameters:

"allow_no_indices"
"analyze_wildcard"
"analyzer"
"default_operator"
"df"
"expand_wildcards"
"ignore_unavailable"
"lenient"
"lowercase_expanded_terms"
"min_score"
"preference"
"q"
"routing"

See the search exists reference (http://www.elastic.co/guide/en/elasticsearch/reference/current/search-exists.html) for more. ⭐

🌈 `count()`

$results = $e->count(
    index   => 'index' | \@indices,     # optional
    type    => 'type'  | \@types,       # optional

    body    => { query }                # optional
)

The count() method returns the total count of all documents matching the query:

$results = $e->count(
    body => {
        query => {
            match => { title => 'Elasticsearch clients' }
        }
    }
);

Just the number, no drama, no extra payload. Iconic. 🎀

...and the query string params it vibes with are:

"allow_no_indices"
"analyze_wildcard"
"analyzer"
"default_operator"
"df"
"expand_wildcards"
"ignore_unavailable"
"lenient"
"lowercase_expanded_terms"
"min_score"
"preference"
"q"
"routing"

No cap bestie, if you need the lore on any of those, the count docs are right here: http://www.elastic.co/guide/en/elasticsearch/reference/current/search-count.html 🫶

🎀 `search_template()`

$results = $e->search_template(
    index   => 'index' | \@indices,     # optional
    type    => 'type'  | \@types,       # optional

    body    => { search params }        # optional
);

okay so this one is literally a search, but make it a template ✨. You hand it a template (either one that's already predefined, or one you define yourself inside the body) plus the parameters to plug into it. Like, the query is a lil fill-in-the-blank situation and you're supplying the blanks, and honestly? iconic.

$results = $e->search_template(
    body => {
        template => {
            query => {
                match => {
                    "{{my_field}}" => "{{my_value}}"
                }
            },
            size => "{{my_size}}"
        },
        params => {
            my_field => 'foo',
            my_value => 'bar',
            my_size  => 5
        }
    }
);

Wanna go deeper? The search template docs are here 💜 http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html

Query string params she accepts:

"allow_no_indices"
"expand_wildcards"
"ignore_unavailable"
"preference"
"scroll"
"search_type"

🌸 `scroll()`

$results = $e->scroll(
    scroll      => '1m',
    scroll_id   => $id
);

So when you've done a search() with the scroll param, this is your girl. You call scroll() and she keeps pulling more results for you, again and again, until there's literally nothing left to pull. Endless scrolling but for data, periodt. 🌀

NOTE: you will almost always wanna set the search_type to "scan" in your original search() request. Like, that's the move, fr fr.

Go peep "scroll_helper()" and Search::Elasticsearch::Scroll if you want a helper utility that makes managing scroll requests so much easier — she does all the tedious stuff for you, main character energy only. 👑

Query string params:

"scroll"
"scroll_id"

The scroll docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-scroll.html And the search_type docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/search.html/search-request-search-type.html

💫 `clear_scroll()`

$response = $e->clear_scroll(
    scroll_id => $id | \@ids    # required
);

$response = $e->clear_scroll(
    body => $id
);

Y'all, clear_scroll() is the cleanup queen 🧹. She can clear out any scroll requests that never got finished, which frees up resources on the server. Basically the "thanks for coming, now go home" of scroll requests. Respect.

🦋 `scroll_helper()`

$scroll_helper = $e->scroll_helper( @args );

Returns a whole new instance of whatever class you set in "scroll_helper_class", which just defaults to Search::Elasticsearch::Scroll. Cute, right? ✨

🌈 `msearch()`

$results = $e->msearch(
    index   => 'default_index' | \@indices,     # optional
    type    => 'default_type'  | \@types,       # optional

    body    => [ searches ]                     # required
);

The "msearch()" method is the multitasker 🫶 — she does multiple searches in a single request. It's giving "bulk()" energy: every single search request in the body is actually two hashes, the metadata hash and then the search request hash (like, the exact same data you'd put in the body of a "search()" request). For instance:

$results = $e->msearch(
    index   => 'default_index',
    type    => ['default_type_1', 'default_type_2'],
    body => [
        # uses defaults
        {},
        { query => { match_all => {} }},

        # uses a custom index
        { index => 'not_the_default_index' },
        { query => { match_all => {} }}
    ]
);

Query string params she takes:

"search_type"

More deets in the msearch docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html

🔍 `explain()`

$response = $e->explain(
    index   => 'my_index',  # required
    type    => 'my_type',   # required
    id      => 123,         # required

    body    => { search }   # required
);

The "explain()" method is the nosy bestie who spills all the tea ☕ — she explains why the specified document either matched a query or didn't, and exactly how the relevance score got calculated. Receipts only, no cap.

$response = $e->explain(
    index   => 'my_index',
    type    => 'my_type',
    id      => 123,
    body    => {
        query => {
            match => { title => 'Elasticsearch clients' }
        }
    }
);

Query string params:

"_source"
"_source_exclude"
"_source_include"
"analyze_wildcard"
"analyzer"
"default_operator"
"df"
"fields"
"lenient"
"lowercase_expanded_terms"
"parent"
"preference"
"q"
"routing"

The explain docs are over here: http://www.elastic.co/guide/en/elasticsearch/reference/current/search-explain.html

📊 `field_stats()`

$response = $e->field_stats(
    index   => 'index'   | \@indices,   # optional
    fields  => 'field'   | \@fields,    # optional
    level   => 'cluster' | 'indices',   # optional
);

The "field-stats" API serves statistical properties of a field (think min and max values and whatnot) — and the slay part? She does it without running a whole search. Efficiency icon. ⭐

Query string params:

"allow_no_indices"
"expand_wildcards"
"fields"
"ignore_unavailable"
"level"

field-stats docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/search-field-stats.html

🧚 `search_shards()`

$response = $e->search_shards(
    index   => 'index' | \@indices,     # optional
    type    => 'type'  | \@types,       # optional
)

The "search_shards()" method gives you the intel on which shards on which nodes are gonna execute a search request. It's the "who's actually doing the work behind the scenes" reveal, and honestly the gossip is juicy. 👀

Query string params:

"allow_no_indices"
"expand_wildcards"
"ignore_unavailable"
"local"
"preference"
"routing"

The search-shards docs, bestie: http://www.elastic.co/guide/en/elasticsearch/reference/current/search-shards.html 💖

💫 PERCOLATION METHODS

okay bestie this next bit is so cool, it's percolation and it's literally search but backwards 🔄

🌀 `percolate()`

$results = $e->percolate(
    index   => 'my_index',      # required
    type    => 'my_type',       # required

    body    => { percolation }  # required
);

So here's the vibe: percolation is search inverted ✨ Instead of "hey, which docs match this query?", it's "hey, which queries match this doc?" 🙃 iconic. You use it for alert-me-when stuff — like "ping me the second a doc shows up that looks like this".

The percolate() method runs a percolation request to find the queries matching a particular document. And listen, in the body you gotta pass the _source field of the document, tucked under the doc key 👇

$results = $e->percolate(
    index   => 'my_index',
    type    => 'my_type',
    body    => {
        doc => {
            title => 'Elasticsearch rocks'
        }
    }
);

Query string parameters, the whole lil roster:

allow_no_indices
expand_wildcards
ignore_unavailable
percolate_format
percolate_index
percolate_preference
percolate_routing
percolate_type
preference
routing
version
version_type

See the percolate docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-percolate.html> for more information. 💅

🌀 `count_percolate()`

$results = $e->count_percolate(
    index   => 'my_index',      # required
    type    => 'my_type',       # required

    body    => { percolation }  # required
);

The count_percolate() request works just like the percolate() request 🫶 except — plot twist — it returns a count of all the matching queries instead of the queries themselves. Just the number, no names. Very mysterious of it.

$results = $e->count_percolate(
    index   => 'my_index',
    type    => 'my_type',
    body    => {
        doc => {
            title => 'Elasticsearch rocks'
        }
    }
);

Query string parameters:

allow_no_indices
expand_wildcards
ignore_unavailable
percolate_index
percolate_type
preference
routing
version
version_type

See the percolate docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-percolate.html> for more information. 🌸

🌀 `mpercolate()`

$results = $e->mpercolate(
    index   => 'my_index',               # required if type
    type    => 'my_type',                # optional

    body    => [ percolation requests ]  # required
);

Multi-percolation!! ✨ It lets you run a whole bunch of percolate() requests inside a single request. Efficiency queen 👑

$results = $e->mpercolate(
    index   => 'my_index',
    type    => 'my_type',
    body    => [
        # first request
        { percolate => {
            index => 'twitter',
            type  => 'tweet'
        }},
        { doc => {message => 'some_text' }},

        # second request
        { percolate => {
            index => 'twitter',
            type  => 'tweet',
            id    => 1
        }},
        {},
    ]
);

Query string parameters:

allow_no_indices
expand_wildcards
ignore_unavailable

See the mpercolate docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-percolate.html> for more information. 💜

🌀 `suggest()`

$results = $e->suggest(
    index   => 'index' | \@indices,     # optional

    body    => { suggest request }      # required
);

The suggest() method is the one you call for did-you-mean <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesteres-phrase.html> or search-as-you-type <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-completion.html> suggestion requests 🦋 and fun fact, you can also run these as part of a search() request. Options, we love options.

$results = $e->suggest(
    index   => 'my_index',
    body    => {
        my_suggestions => {
            phrase  => {
                text    => 'johnny walker',
                field   => 'title'
            }
        }
    }
);

Query string parameters:

allow_no_indices
expand_wildcards
ignore_unavailable
preference
routing

🌀 `mlt()`

$results = $e->mlt(
    index   => 'my_index',  # required
    type    => 'my_type',   # required
    id      => 123,         # required

    body    => { search }   # optional
);

The mlt() method runs a more-like-this query <http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-mlt-query.html> to find other documents that are similar to the one you specified 🫶 it's giving "you might also like" energy, fr fr.

Query string parameters:

boost_terms
max_doc_freq
max_query_terms
max_word_length
min_doc_freq
min_term_freq
min_word_length
mlt_fields
percent_terms_to_match
routing
search_from
search_indices
search_scroll
search_size
search_source
search_type
search_types
stop_words

See the mlt docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-more-like-this.html> for more information. 🌟

📜 INDEXED SCRIPT METHODS

Okay so if dynamic scripting is enabled, Elasticsearch lets you store scripts in an internal index known as .scripts and then reference them by id 👑 The methods to manage those indexed scripts go like this:

🎀 `put_script()`

$result  = $e->put_script(
    lang => 'lang',     # required
    id   => 'id',       # required
    body => { script }  # required
);

The put_script() method is how you store a script in the .scripts index. For instance:

$result  = $e->put_scripts(
    lang => 'groovy',
    id   => 'hello_world',
    body => {
      script => q(return "hello world");
    }
);

heads up bestie: the example above literally says put_scripts with an s — that's what the page says, so that's what you get 🤷 no cap, don't come for me.

Query string parameters:

op_type
version
version_type

See the indexed scripts docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts> for more. 💖

🎀 `get_script()`

$script = $e->get_script(
    lang => 'lang',     # required
    id   => 'id',       # required
);

Retrieve the indexed script from the .scripts index. Simple as that, gorj ✨

Query string parameters:

version
version_type

See the indexed scripts docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts> for more. 🌈

🎀 `delete_script()`

$script = $e->delete_script(
    lang => 'lang',     # required
    id   => 'id',       # required
);

Delete the indexed script from the .scripts index 🗑️ bye bye script, you served.

Query string parameters:

version
version_type

See the indexed scripts docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts> for more. 💀

🌼 INDEXED SEARCH TEMPLATE METHODS

Mustache templates can be used to create search requests 🥸 These templates can be stored in the .scripts index and pulled back out by ID. The methods to manage indexed scripts are as follows (yes bestie, that's exactly how the page words it, the template section just borrowed the script section's closing line, iconic behaviour 😭):

🧚 `put_template()`

$result  = $e->put_template(
    id   => 'id',                       # required
    body => { template } || "template"  # required
);

The put_template() method is used to store a template in the .scripts index. For instance:

$result  = $e->put_template(
    id   => 'hello_world',
    body => {
      template => {
        query => {
          match => {
            title => "hello world"
          }
        }
      }
  }
);

Query string parameters: None 🎀

See the indexed search template docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html#_pre_registered_template> for more. ⭐

🧚 `get_template()`

$script = $e->get_template(
    id   => 'id',       # required
);

Retrieve the indexed template from the .scripts index. Come get your template, bestie 🫶

Query string parameters:

version
version_type

See the indexed search template docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html#_pre_registered_template> for more. 🍓

🧚 `delete_template()`

$script = $e->delete_template(
    id   => 'id',       # required
);

Delete the indexed template from the .scripts index. Gone, gone, gone 💅

Query string parameters: None 🌸

See the indexed search template docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html#_pre_registered_template> for more. ✨

👑 AUTHOR

Enrico Zimuel <enrico.zimuel@elastic.co>

📄 COPYRIGHT AND LICENSE

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

and that's the whole page, we did it!! 🎉🥳 every single option, every single section, all of it survived the vibe check. this one's perl v5.36.0, dated 2022-08-28, and it's the Search...Direct(3pm) page from the perl docs (user contributed, obvs 💖). go forth and percolate responsibly, bestie 🦋💜

📦 where this page comes from

ubuntu noble: libsearch-elasticsearch-client-1-0-perl 6.81-2 · Apache-2.0
ubuntu resolute: libsearch-elasticsearch-client-1-0-perl 6.81-2 · Apache-2.0
ubuntu stonking: libsearch-elasticsearch-client-1-0-perl 6.81-2 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

Search...Direct(3pm)

💖 Search::Elasticsearch::Client::1_0::Direct — the manual, but make it cute 💖

✨ NAME ✨

🌈 VERSION 🌈

🎀 SYNOPSIS 🎀

💜 DESCRIPTION 💜

🧚 CONVENTIONS 🧚

🌸 Parameter passing 🌸

🦋 Path parameters 🦋

⭐ Query-string parameters ⭐

🎀 Body parameter 🎀

💖 Filter path parameter 💖

🌈 Ignore parameter 🌈

💅 CONFIGURATION 💅

"bulk_helper_class"

"scroll_helper_class"

👑 GENERAL METHODS 👑

"info()"

"ping()"

"indices()"

"cluster()"

"nodes()"

"snapshot()"

"cat()"

📝 DOCUMENT CRUD METHODS 📝

index()

create()

get()

get_source()

exists()

delete()

update()

termvectors()

🦋 BULK DOCUMENT CRUD METHODS 🦋

💖 bulk()

🌸 bulk_helper()

🎀 mget()

🦋 delete_by_query()

🧚 mtermvectors()

✨ SEARCH METHODS ✨

🔥 search()

💜 search_exists()

🌈 count()

🎀 search_template()

🌸 scroll()

💫 clear_scroll()

🦋 scroll_helper()

🌈 msearch()

🔍 explain()

📊 field_stats()

🧚 search_shards()

💫 PERCOLATION METHODS

🌀 percolate()

🌀 count_percolate()

🌀 mpercolate()

🌀 suggest()

🌀 mlt()

📜 INDEXED SCRIPT METHODS

🎀 put_script()

🎀 get_script()

🎀 delete_script()

🌼 INDEXED SEARCH TEMPLATE METHODS

🧚 put_template()

🧚 get_template()

🧚 delete_template()

👑 AUTHOR

📄 COPYRIGHT AND LICENSE

`"bulk_helper_class"`

`"scroll_helper_class"`

`"info()"`

`"ping()"`

`"indices()"`

`"cluster()"`

`"nodes()"`

`"snapshot()"`

`"cat()"`

`index()`

`create()`

`get()`

`get_source()`

`exists()`

`delete()`

`update()`

`termvectors()`

💖 `bulk()`

🌸 `bulk_helper()`

🎀 `mget()`

🦋 `delete_by_query()`

🧚 `mtermvectors()`

🔥 `search()`

💜 `search_exists()`

🌈 `count()`

🎀 `search_template()`

🌸 `scroll()`

💫 `clear_scroll()`

🦋 `scroll_helper()`

🌈 `msearch()`

🔍 `explain()`

📊 `field_stats()`

🧚 `search_shards()`

🌀 `percolate()`

🌀 `count_percolate()`

🌀 `mpercolate()`

🌀 `suggest()`

🌀 `mlt()`

🎀 `put_script()`

🎀 `get_script()`

🎀 `delete_script()`

🧚 `put_template()`

🧚 `get_template()`

🧚 `delete_template()`