Search...Direct(3pm)

📦 version 6.81, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Search::Elasticsearch::Client::2_0::Direct — the manual page, but make it make sense 💖

User Contributed Perl Documentation · Search...Direct(3pm)

okay bestie, welcome to the thin client that's got full support for Elasticsearch 2.x APIs. she's giving interface, she's giving REST, she's giving "let me hold your hand through the whole thing." 🫶

✨ NAME ✨

Search::Elasticsearch::Client::2_0::Direct — Thin client with full support for Elasticsearch 2.x APIs. periodt. 💅

🌸 VERSION 🌸

version 6.81 — yes that's the number, don't @ me. ⭐

🦋 SYNOPSIS 🦋

so like. first things first, you gotta create a client:

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

Index a doc — put a lil something into the world:

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

Get a doc — go fetch it back:

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

Search for docs — the main character moment:

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

Index-level requests — running the whole index, no biggie:

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

Cluster-level requests — the big picture energy:

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

Node-level requests — zooming in on the individual girlies:

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

Snapshot and restore — bestie we are backing up, we are being responsible:

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

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

Task management — keeping tabs on what's happening:

$e->tasks->list;

cat debugging — the iconic say-it-out-loud era:

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

👑 DESCRIPTION 👑

The Search::Elasticsearch::Client::2_0::Direct class provides the Elasticsearch 2.x compatible client returned by:

$e = Search::Elasticsearch->new(
    client => "2_0::Direct"
);

It is intended to be as close as possible to the native REST API that Elasticsearch uses, so that it is easy to translate the Elasticsearch reference documentation <http://www.elasticsearch/guide> for an API to the equivalent in this client. no cap, the whole point is that translating is easy. 🧚

This class provides the methods for document CRUD, bulk document CRUD and search. It also provides access to clients for managing indices and the cluster. she does it all, honestly. 💜

💅 CONVENTIONS 💅

🎀 Parameter passing

Parameters can be passed to any request method as a list or as a hash reference. The following two statements are equivalent:

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

both ate, pick your fighter. ✨

🎀 Path parameters

Any values that should be included in the URL path, eg "/{index}/{type}" should be passed as top level parameters:

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

Alternatively, you can specify a "path" parameter directly:

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

🎀 Query-string parameters

Any values that should be included in the query string should be passed as top level parameters:

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

If you pass in a "\%params" hash, then it will be included in the query string parameters without any error checking. The following:

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

would result in this query string:

?from=5&size=10

okay notice how size came out as 10 and not 5 — that's the no-error-checking thing doing its thing, iykyk. 💀

🎀 Body parameter

The request body should be passed in the "body" key:

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

The body can also be a UTF8-decoded string, which will be converted into UTF-8 bytes and passed as is:

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

🎀 Filter path parameter

Any API which returns a JSON body accepts a "filter_path" parameter which will filter the JSON down to only the specified paths. For instance, if you are running a search request and only want the "total" hits and the "_source" field for each hit (without the "_id", "_index" etc), you can do:

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

trimming the noise, we love a minimal queen. 🦋

🎀 Ignore parameter

Normally, any HTTP status code outside the 200-299 range will result in an error being thrown. To suppress these errors, you can specify which status codes to ignore in the "ignore" parameter.

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

This is most useful for Missing errors, which are triggered by a 404 status code when some requested resource does not exist.

Multiple error codes can be specified with 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::2_0::Bulk.

🎀 `"scroll_helper_class"`

The class to use for the "scroll_helper()" method. Defaults to Search::Elasticsearch::Client::2_0::Scroll.

⭐ GENERAL METHODS ⭐

🎀 `"info()"`

$info = $e->info

Returns information about the version of Elasticsearch that the responding node is running. who are you, what version are you running, spill.

🎀 `"ping()"`

$e->ping

Pings a node in the cluster and returns 1 if it receives a 200 response, otherwise it throws an error. 💀

🎀 `"indices()"`

$indices_client = $e->indices;

Returns an Search::Elasticsearch::Client::2_0::Direct::Indices object which can be used for managing indices, eg creating, deleting indices, managing mapping, index settings etc. the whole index admin situation. 👑

🎀 `"cluster()"`

$cluster_client = $e->cluster;

Returns an Search::Elasticsearch::Client::2_0::Direct::Cluster object which can be used for managing the cluster, eg cluster-wide settings and cluster health. big-picture energy fr fr. 🔥

🎀 `"nodes()"`

$node_client = $e->nodes;

Returns an Search::Elasticsearch::Client::2_0::Direct::Nodes object which can be used to retrieve node info and stats. 🍓

🎀 `"snapshot()"`

$snapshot_client = $e->snapshot;

Returns an Search::Elasticsearch::Client::2_0::Direct::Snapshot object which is used for managing backup repositories and creating and restoring snapshots. backups are self-care. 💖

🎀 `"tasks()"`

$tasks_client = $e->tasks;

Returns an Search::Elasticsearch::Client::2_0::Direct::Tasks object which is used for accessing the task management API. 🌸

🎀 `"cat()"`

$cat_client = $e->cat;

Returns an Search::Elasticsearch::Client::2_0::Direct::Cat object which can be used to retrieve simple to read text info for debugging and monitoring an Elasticsearch cluster. literally the cutest debugging tool, no notes. 🐱✨

💖 DOCUMENT CRUD METHODS 💖

okay bestie, this is where it gets good — these methods let you do the create, index, update and delete requests for single documents. one doc at a time, full main-character treatment, no cap. 🎀

`index()` ✨

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

    body    => { document }         # required
);

The index() method is your go-to for indexing a brand new document, or for reindexing one that already exists. either way, it slays. 💅

Query string parameters:

consistency
op_type
parent
refresh
routing
timeout
timestamp
ttl
version
version_type

See the index docs at http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html for more information.

`create()` 🦋

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

    body    => { document }         # required
);

The create() method works exactly like index(), with one little twist: it will throw a Conflict error if a document with the same index, type and id already exists. so basically it's index() but it's not about to let you clobber somebody else's doc. 😭 iconic behaviour honestly.

Query string parameters:

consistency
op_type
parent
refresh
routing
timeout
timestamp
ttl
version
version_type

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

`get()` 🔍

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

The get() method will retrieve the document with the specified index, type and id — or it will throw a Missing error if it's not there. no doc, no vibes. 💀

Query string parameters:

_source
_source_exclude
_source_include
fields
parent
preference
realtime
refresh
routing
version
version_type

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

`get_source()` 🌸

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

The get_source() method works just like get() except it returns just the _source field — that's the value of the body parameter you passed to index() — instead of handing you the _source field plus the document metadata, i.e. the _index, _type etc. so like… the doc itself without the whole entourage. 🫶

Query string parameters:

_source
_source_exclude
_source_include
parent
preference
realtime
refresh
routing
version
version_type

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

`exists()` 👑

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

The exists() method returns 1 if a document with the specified index, type and id exists, or an empty string if it doesn't. that's it, that's the whole vibe check. ✨

Query string parameters:

parent
preference
realtime
refresh
routing

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

`delete()` 💀

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

The delete() method will delete the document with the specified index, type and id — or it will throw a Missing error. it's giving ghosting, but make it official. 🙈

Query string parameters:

consistency
parent
refresh
routing
timeout
version
version_type

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

`update()` 🌈

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

    body    => { update }           # required
);

The update() method updates a document with the corresponding index, type and id — but only if it exists. and bestie, you have options for how you update it:

providing a partial document to be merged in to the existing document:

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

with an inline script:

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

⚠️ Make sure you enable dynamic scripting at https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#enable-dynamic-scripting and know its implications. like, actually know them. don't just click and hope. 😭

with an indexed script:

$response = $e->update(
    ...,
    body => {
        script => {
            id     => $id,
            params => { incr => 5 }
        }
    }
);

See indexed scripts at https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts for more information.

with a script stored as a file:

$response = $e->update(
    ...,
    body => {
        script => {
            file   => 'counter',
            lang   => 'groovy',
            params => { incr => 5 }
        }
    }
);

See scripting docs at https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html for more information.

Query string parameters:

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

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

`termvectors()` 🧚

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

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

The termvectors() method retrieves term and field statistics, positions, offsets and payloads for the specified document — assuming termvectors have been enabled, so clock that. ⭐

Query string parameters:

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

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

💥 BULK DOCUMENT CRUD METHODS 💥

The bulk document CRUD methods are for running multiple CRUD actions inside a single request. And bestie, that's the whole point: fewer network round-trips = way better performance. It's giving efficiency queen. 👑

`bulk()`

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

    body    => [ actions ]          # required
);

See Search::Elasticsearch::Client::2_0::Bulk and "bulk_helper()" for a helper module that makes bulk indexing simpler to use. 🫶

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 consists 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" }

Each action can include the same parameters that you would pass to the equivalent index(), create(), delete() or update() request — except that _index, _type and _id must be specified with the preceding underscore. All other parameters can be specified with or without the underscore. (Yes, the underscore ones are non-negotiable, she's built different. 💅)

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. One failed action will not cause the others to fail as well. Independent queens only. ✨

Query string parameters:

consistency
fields
refresh
routing
timeout

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

`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::2_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.

If you have 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 <http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html> for more information.

`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 <http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-termvectors.html> for more information.

🔍 SEARCH METHODS 🔍

The search methods are used for querying documents in one, more or all indices and of one, more or all types. It's giving "where is it, I need it, I need it now". 🕵️‍♀️

`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. So many talents, honestly obsessed. 🌈

The lite version of search <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-uri-request.html> allows you to 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
request_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 information.

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. Just a vibe check: yes or no. 💀

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

`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' }
        }
    }
);

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 count docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-count.html> for more information.

`search_template()`

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

    body    => { search params }        # optional
);

Perform a search by specifying a template (either predefined or defined within the body) and parameters to use with the template, eg:

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

like,,, the template does the whole {{mustache}} thing and you just hand it the vibes (params) it needs to fill in. iconic tbh 🎀

Peep the search template docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html> for the full tea 💖

Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable, preference, scroll, search_type

🌸 `render_search_template()` 🌸

           $response = $e->render_search_template(
               id   => 'id',           # optional
               body => { template }    # optional
           );

Renders the template, fills in whatever params you passed, and hands you back the resulting JSON. No cap, that's it. eg:

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

Peep the search template docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html> for more 🦋

💅 `scroll()` 💅

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

Once you've done a search() with the scroll param, scroll() lets you keep pulling more results until they're all gone. it's giving endless scroll but for real data 🌀

NOTE: you will almost always wanna set the search_type to scan in your original search() request. fr fr, don't skip this.

Peep scroll_helper() and Search::Elasticsearch::Client::2_0::Scroll for a helper utility that makes managing scroll requests way easier. lowkey a lifesaver 💖

Query string parameters: scroll, scroll_id

Peep 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> for more 🫶

✨ `clear_scroll()` ✨

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

Or:

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

The clear_scroll() method can clear unfinished scroll requests, freeing up resources on the server. like closing tabs you forgot about but it's ✨responsible✨ 🧚

🦋 `scroll_helper()` 🦋

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

Returns a new instance of the class specified in the scroll_helper_class, which defaults to Search::Elasticsearch::Client::2_0::Scroll. slay 💖

🌈 `msearch()` 🌈

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

               body    => [ searches ]                     # required
           );

The msearch() method lets you do a whole bunch of searches in a single request. Similar to the bulk() request, each search request in the body consists of two hashes: the metadata hash then the search request hash (the same data you'd specify 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 => {} }}
               ]
           );

see how it's pairs?? meta then query, meta then query. two at a time, that's the vibe 💅

Query string parameters: search_type

Peep the msearch docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html> for more 🌸

👑 `explain()` 👑

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

               body    => { search }   # required
           );

The explain() method explains why the specified document did or did not match a query, and how the relevance score was calculated. it's the "bestie why did this show up" API fr. For instance:

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

Query string parameters: _source, _source_exclude, _source_include, analyze_wildcard, analyzer, default_operator, df, fields, lenient, lowercase_expanded_terms, parent, preference, q, routing

Peep the explain docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-explain.html> for more 💜

🍓 `field_stats()` 🍓

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

The field-stats API returns statistical properties of a field (such as min and max values) without executing a search. so you get the numbers without the whole search song and dance 🎀

Query string parameters: allow_no_indices, expand_wildcards, fields, ignore_unavailable, level

Peep the field-stats docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-field-stats.html> for more ⭐

🧚 `search_shards()` 🧚

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

The search_shards() method returns information about which shards on which nodes will execute a search request. it's giving "who's doing the work behind the scenes" energy 🔥

Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable, local, preference, routing

Peep the search-shards docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-shards.html> for more 🌈

💖 CRUD-BY-QUERY METHODS 💖

okay so this whole section?? we're not touching docs one at a time anymore bestie, we're doing the whole operation by query. bulk energy only 😭✨

🌟 `delete_by_query()` 🌟

           $response = $e->delete_by_query(
               index   => 'index' | \@indices,     # optional
               type    => 'type'  | \@types,       # optional,
               body    => { delete-by-query }      # optional
           );

The delete_by_query() method (available with the delete-by-query plugin <https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugins-delete-by-query.html>) deletes all documents which match the specified query. all of them. gone. no cap 💀

Query string parameters: allow_no_indices, analyzer, default_operator, df, expand_wildcards, filter_path, ignore_unavailable, q, routing, timeout

Peep the delete-by-query docs <https://www.elastic.co/guide/en/elasticsearch/plugins/current/plugins-delete-by-query.html> for more 🫶

🌸 `reindex()` 🌸

           $response = $e->reindex(
               body => { reindex }     # required
           );

The reindex() API is used to index documents from one index or multiple indices to a new index. moving day but make it ✨data✨

Query string parameters: consistency, refresh, requests_per_second, timeout, wait_for_completion

Peep the reindex docs <https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html> for more 💜

🎀 `update_by_query()` 🎀

           $response = $e->update_by_query(
               index   => 'index' | \@indices,     # optional
               type    => 'type'  | \@types,       # optional,
               body    => { update-by-query }      # optional
           );

The update_by_query() API is used to bulk update documents from one index or multiple indices using a script. glow-up for your whole dataset at once 💅

Query string parameters: _source, _source_exclude, _source_include, allow_no_indices, analyze_wildcard, analyzer, conflicts, consistency, default_operator, df, expand_wildcards, explain, fielddata_fields, fields, from, ignore_unavailable, lenient, lowercase_expanded_terms, preference, q, refresh, request_cache, requests_per_second, routing, scroll, scroll_size, search_timeout, search_type, size, sort, stats, suggest_field, suggest_mode, suggest_size, suggest_text, terminate_after, timeout, track_scores, version, version_type, wait_for_completion

bestie that's a LOT of params and we listed every single one. no skipping, that's the rule 💖

Peep the update_by_query docs <https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html> for more 🌸

⭐ `reindex_rethrottle` ⭐

           $response = $e->reindex_rethrottle(
               task_id             => 'task_id',       # required
               requests_per_second => $req_per_second
           );

The reindex_rethrottle() API is used to dynamically update the throtting of an existing reindex request, identified by task_id. like turning the speed dial mid-reindex, real main character energy 🔥

Query string parameters: requests_per_second

Peep the reindex docs <https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html> for more 🦋

✨ PERCOLATION METHODS ✨

Okay bestie, percolation is literally search inverted — instead of finding docs that match a particular query, it finds queries that match a particular document, eg for alert-me-when functionality. It's giving main character energy, no cap. 💅

`percolate()`

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

    body    => { percolation }  # required
);

The percolate() method runs a percolation request to find the queries matching a particular document. In the body you should pass the _source field of the document under the doc key:

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

Query string parameters:

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 at 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 that it returns a count of all matching queries, instead of the queries themselves.

$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 at 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 allows multiple percolate() requests to be run in a single request. Obsessed.

$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 at 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 used to run did-you-mean or search-as-you-type suggestion requests, which can also be run as part of a search() request. The did-you-mean docs live at http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesteres-phrase.html and the search-as-you-type docs live at http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-completion.html. 🔥

$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

✨ INDEXED SCRIPT METHODS ✨

If dynamic scripting is enabled, Elasticsearch allows you to store scripts in an internal index known as .scripts and reference them by id. The methods to manage indexed scripts are as follows: 👑

`put_script()`

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

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

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

Query string parameters:

op_type
version
version_type

See the indexed scripts docs at 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.

Query string parameters:

version
version_type

See the indexed scripts docs at 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.

Query string parameters:

version
version_type

See the indexed scripts docs at 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 retrieved by ID. The methods to manage indexed scripts are as follows: 🧚

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

Query string parameters:

version
version_type

See the indexed search template docs at 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.

Query string parameters: None

See the indexed search template docs at 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

That's a wrap, bestie! This was Search...Direct(3pm) from perl v5.32.0, dated 2020-11-25. Stay slay, keep your queries percolating, and don't forget to vibe check your indices. Mwah 💋

📦 where this page comes from

debian bookworm: libsearch-elasticsearch-client-2-0-perl 6.81-1 · Apache-2.0
debian trixie: libsearch-elasticsearch-client-2-0-perl 6.81-1 · Apache-2.0
ubuntu jammy: libsearch-elasticsearch-client-2-0-perl 6.81-1 · Apache-2.0
ubuntu noble: libsearch-elasticsearch-client-2-0-perl 6.81-1 · Apache-2.0
ubuntu resolute: libsearch-elasticsearch-client-2-0-perl 6.81-1 · Apache-2.0
ubuntu stonking: libsearch-elasticsearch-client-2-0-perl 6.81-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...Direct(3pm)

💖 Search::Elasticsearch::Client::2_0::Direct — the manual page, but make it make sense 💖

✨ 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()"

🎀 "tasks()"

🎀 "cat()"

💖 DOCUMENT CRUD METHODS 💖

index() ✨

create() 🦋

get() 🔍

get_source() 🌸

exists() 👑

delete() 💀

update() 🌈

termvectors() 🧚

💥 BULK DOCUMENT CRUD METHODS 💥

bulk()

bulk_helper()

mget()

mtermvectors()

🔍 SEARCH METHODS 🔍

search()

search_exists()

count()

search_template()

🌸 render_search_template() 🌸

💅 scroll() 💅

✨ clear_scroll() ✨

🦋 scroll_helper() 🦋

🌈 msearch() 🌈

👑 explain() 👑

🍓 field_stats() 🍓

🧚 search_shards() 🧚

💖 CRUD-BY-QUERY METHODS 💖

🌟 delete_by_query() 🌟

🌸 reindex() 🌸

🎀 update_by_query() 🎀

⭐ reindex_rethrottle ⭐

✨ PERCOLATION METHODS ✨

percolate()

count_percolate()

mpercolate()

suggest()

✨ 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()"`

🎀 `"tasks()"`

🎀 `"cat()"`

`index()` ✨

`create()` 🦋

`get()` 🔍

`get_source()` 🌸

`exists()` 👑

`delete()` 💀

`update()` 🌈

`termvectors()` 🧚

`bulk()`

`bulk_helper()`

`mget()`

`mtermvectors()`

`search()`

`search_exists()`

`count()`

`search_template()`

🌸 `render_search_template()` 🌸

💅 `scroll()` 💅

✨ `clear_scroll()` ✨

🦋 `scroll_helper()` 🦋

🌈 `msearch()` 🌈

👑 `explain()` 👑

🍓 `field_stats()` 🍓

🧚 `search_shards()` 🧚

🌟 `delete_by_query()` 🌟

🌸 `reindex()` 🌸

🎀 `update_by_query()` 🎀

⭐ `reindex_rethrottle` ⭐

`percolate()`

`count_percolate()`

`mpercolate()`

`suggest()`

`put_script()`

`get_script()`

`delete_script()`

`put_template()`

`get_template()`

`delete_template()`