Search...Direct(3pm)

📦

version 8.12 · 4 versions

8.12 · debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking (latest)
8.12 · fedora 43
8.12 · fedora 44
8.00 · debian bookworm

, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

Search::Elasticsearch::Client::8_0::Direct 💖

aka Search...Direct(3pm) — User Contributed Perl Documentation, bestie. It's giving thin client, full support, Elasticsearch 8.x APIs. ✨

✨ NAME ✨

Search::Elasticsearch::Client::8_0::Direct — the thin client with full support for Elasticsearch 8.x APIs. 💅

🎀 VERSION 🎀

version 8.12 — yes, that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

Okay so first, make a client, it's so easy:

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

Index a doc 💖:

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

Get a doc 🫶:

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

Search for docs 🔍:

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

Index-level requests 👑:

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

Ingest pipeline requests 🍓:

$e->ingest->get_pipeline( id => 'apache-logs' );

Cluster-level requests 🌈:

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

Node-level requests ⭐:

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

Snapshot and restore 📸:

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

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

Task management 📝:

$e->tasks->list;

cat debugging 🐱 (say it, don't just call it — the vibes demand it):

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

Cross-cluster replication requests 🔁:

say $e->ccr->follow;

Index lifecycle management requests 🌱:

say $e->ilm->put_lifecycle;

💜 DESCRIPTION 💜

So like, the Search::Elasticsearch::Client::8_0::Direct class is the whole reason you're here: it gives you the Elasticsearch 8.x compatible client that comes back from this:

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

It's designed to be as close as possible to the native REST API that Elasticsearch itself uses — like, the goal is that translating the Elasticsearch reference documentation (http://www.elasticsearch/guide) for any API into this client is basically a straight-across vibe. No mental gymnastics, no cap. 🧚

This class hands you the methods for document CRUD, bulk document CRUD and search. It also gives you access to clients for managing indices and the cluster. Periodt. 💅

🌈 PREVIOUS VERSIONS OF ELASTICSEARCH 🌈

This version of the client supports the Elasticsearch 8.0 branch, and heads up — it is not backwards compatible with earlier branches. It said what it said. 💀

If you need to talk to a version of Elasticsearch before 8.0.0, please install one of these modules:

Search::Elasticsearch::Client::7_0
Search::Elasticsearch::Client::6_0
Search::Elasticsearch::Client::5_0
Search::Elasticsearch::Client::2_0
Search::Elasticsearch::Client::1_0
Search::Elasticsearch::Client::0_90

✨ CONVENTIONS ✨

🎀 Parameter passing 🎀

You can pass parameters to any request method as a list or as a hash reference. These two statements are literally the same thing:

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

🦋 Path parameters 🦋

Any values that should go in the URL path — like "/{index}/{type}" — get passed as top level parameters:

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

Or, if you're feeling main-character, you can specify a "path" parameter directly:

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

🌸 Query-string parameters 🌸

Any values that should go in the query string get passed as top level parameters:

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

If you pass in a \%params hash, it gets dropped into the query string parameters with no error checking whatsoever. So this:

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

would result in this query string:

?from=6&size=10

👀 Yeah, the size in params gets steamrolled. That's just how it is, bestie. Not my rules.

💖 Body parameter 💖

The request body goes 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");

⭐ Boolean parameters ⭐

Elasticsearch 7.0.0 and above no longer accepts truthy and falsey values for booleans. Nope. Instead it accepts only a JSON true or false, or the string equivalents "true" or "false". So picky. 🙈

In the Perl client, you can use these values:

True: "true", "\1", or a JSON::PP::Boolean object.
False: "false", "\0", or a JSON::PP::Boolean object.

🔍 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 named. So like, if you're running a search request and you only want the "total" hits and the "_source" field for each hit (without the "_id", "_index" etc), you do:

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

🙈 Ignore parameter 🙈

Normally, any HTTP status code outside the 200-299 range means an error gets thrown. To suppress those errors, you tell it 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 get triggered by a 404 status code when some requested resource doesn't exist. Been there. 😭

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::8_0::Bulk.

🌟 `"scroll_helper_class"` 🌟

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

👑 GENERAL METHODS 👑

💖 `info()`

$info = $e->info

Returns information about the version of Elasticsearch that the responding node is running.

💖 `ping()`

$e->ping

Pings a node in the cluster and returns 1 if it receives a 200 response. Otherwise? It throws an error. Dramatic, but fair. 💀

💖 `indices()`

$indices_client = $e->indices;

Returns a Search::Elasticsearch::Client::8_0::Direct::Indices object, which you can use for managing indices — creating, deleting indices, managing mapping, index settings, etc.

💖 `ingest()`

$ingest_client = $e->ingest;

Returns a Search::Elasticsearch::Client::8_0::Direct::Ingest object, which you can use for managing ingest pipelines.

💖 `cluster()`

$cluster_client = $e->cluster;

Returns a Search::Elasticsearch::Client::8_0::Direct::Cluster object, which you can use for managing the cluster — cluster-wide settings and cluster health, that kind of thing.

💖 `nodes()`

$node_client = $e->nodes;

Returns a Search::Elasticsearch::Client::8_0::Direct::Nodes object, which you can use to retrieve node info and stats.

💖 `snapshot()`

$snapshot_client = $e->snapshot;

Returns a Search::Elasticsearch::Client::8_0::Direct::Snapshot object, which is used for managing backup repositories and creating and restoring snapshots.

💖 `tasks()`

$tasks_client = $e->tasks;

Returns a Search::Elasticsearch::Client::8_0::Direct::Tasks object, which is used for accessing the task management API.

💖 `cat()`

$cat_client = $e->cat;

Returns a Search::Elasticsearch::Client::8_0::Direct::Cat object, which you can use to retrieve simple-to-read text info for debugging and monitoring an Elasticsearch cluster. 🐱✨

💖 `ccr()`

$ccr_client = $e->ccr;

Returns a Search::Elasticsearch::Client::8_0::Direct::CCR object, which you can use to handle cross-cluster replication requests.

💖 `ilm()`

$ilm_client = $e->ilm;

Returns a Search::Elasticsearch::Client::8_0::Direct::ILM object, which you can use to handle index lifecycle management requests.

🎀 DOCUMENT CRUD METHODS 🎀

okay bestie, this is the part where we actually do stuff to your docs. create, index, update, delete — the whole glow-up pipeline for single documents. let's get into it 💅

✨ `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 what you reach for when you wanna index a brand new document, or reindex one that already exists. it's giving "main character gets a makeover" energy. 🔥

Query string parameters:

"error_trace",
"human",
"if_primary_term",
"if_seq_no",
"op_type",
"parent",
"pipeline",
"refresh",
"routing",
"timeout",
"version",
"version_type",
"wait_for_active_shards"

See the index docs for more info: 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',            # required

    body    => { document }         # required
);

the create() method is literally the same vibe as the "index()" method — except 💀 it will throw a "Conflict" error if a document with the same "index", "type" and "id" already exists. so it's the "no duplicates allowed, periodt" version.

Query string parameters:

"consistency",
"error_trace",
"human",
"op_type",
"parent",
"refresh",
"routing",
"timeout",
"version",
"version_type"

See the create docs for more info: 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
);

the get() method pulls up the document with the "index", "type" and "id" you gave it. and if it can't find it? it will throw a "Missing" error. no doc, no peace 😭

Query string parameters:

"_source",
"_source_excludes",
"_source_includes",
"error_trace",
"human",
"parent",
"preference",
"realtime",
"refresh",
"routing",
"stored_fields",
"version",
"version_type"

See the get docs for more info: 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
);

the get_source() method works just like the "get()" method, EXCEPT it returns only the "_source" field (aka the value of the "body" parameter you passed to "index()") instead of returning the "_source" field plus all the document metadata — the "_index", "_type" etc. it's the stripped-down, no-extra-baggage version. lowkey minimalist queen. 🦋

Query string parameters:

"_source",
"_source_excludes",
"_source_includes",
"error_trace",
"human",
"parent",
"preference",
"realtime",
"refresh",
"routing",
"version",
"version_type"

See the get_source docs for more info: 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
);

the exists() method returns 1 if a document with that "index", "type" and "id" exists, or an empty string if it doesn't. simple. iconic. no drama. ✅

Query string parameters:

"_source",
"_source_excludes",
"_source_includes",
"error_trace",
"human",
"parent",
"preference",
"realtime",
"refresh",
"routing",
"version",
"version_type"

See the exists docs for more info: 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
);

the delete() method deletes the document with the specified "index", "type" and "id" — or it will throw a "Missing" error if it can't find it. gone. ghosted. it's giving "we don't talk anymore". 🫥

Query string parameters:

"error_trace",
"human",
"if_primary_term",
"if_seq_no",
"parent",
"refresh",
"routing",
"timeout",
"version",
"version_type",
"wait_for_active_shards"

See the delete docs for more info: 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
);

the update() method updates a document with the matching "index", "type" and "id" — but only if it exists. and bestie, there are SO many ways to do an update. pick your fighter: 👇

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 => {
            source => "ctx._source.counter += incr",
            params => { incr => 6 }
        }
    }
);

with an indexed script:

$response = $e->update(
    ...,
    body => {
        script => {
            id     => $id,
            lang   => 'painless',
            params => { incr => 6 }
        }
    }
);

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

with a script stored as a file:

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

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

Query string parameters:

"_source",
"_source_excludes",
"_source_includes",
"error_trace",
"fields",
"human",
"if_primary_term",
"if_seq_no",
"lang",
"parent",
"refresh",
"retry_on_conflict",
"routing",
"timeout",
"version",
"version_type",
"wait_for_active_shards"

See the update docs for more info: 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
)

the termvectors() method retrieves term and field statistics, positions, offsets and payloads for the specified document — assuming termvectors have been enabled. it's the deep-lore, behind-the-scenes info about your terms. iykyk. 🔍

Query string parameters:

"error_trace",
"field_statistics",
"fields",
"human",
"offsets",
"parent",
"payloads",
"positions",
"preference",
"realtime",
"routing",
"term_statistics",
"version",
"version_type"

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

💥 BULK DOCUMENT CRUD METHODS 💥

okay so bestie, the bulk CRUD methods are the ones you use when you wanna run multiple CRUD actions inside a single request. the whole point? fewer network round trips. and fewer network round trips = massively better performance. it's giving efficiency, it's giving slay. by reducing the number of network requests that need to be made, bulk requests greatly improve performance. periodt.

🎀 bulk()

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

    body    => [ actions ]          # required
);

go peep Search::Elasticsearch::Client::8_0::Bulk and bulk_helper() if you want a helper module that makes bulk indexing wayyy simpler to use. iykyk. ✨

so the bulk() method can do multiple index(), create(), delete() or update() actions all in one request. the body parameter wants an array with the list of actions to perform.

an action = an initial metadata hash ref holding the action type plus the associated metadata, like:

{ 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, like:

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

each action can include the same parameters 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 do them with or without the underscore, no biggie.

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 => 126 }},

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

every single action is performed separately. one failed action will not drag the others down with it. we love an independent queen. 👑

Query string parameters: "_source", "_source_excludes", "_source_includes", "error_trace", "fields", "human", "pipeline", "refresh", "routing", "timeout", "wait_for_active_shards"

see the bulk docs <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 brand new instance of the class specified in the bulk_helper_class, which defaults to Search::Elasticsearch::Client::8_0::Bulk. cute, right? 💖

🦋 mget()

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

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

the mget() method grabs multiple documents in a single request. the body is 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. no gatekeeping here.

and if you've already specified an index and type, you can literally just drop the ids of the documents you want:

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

Query string parameters: "_source", "_source_excludes", "_source_includes", "error_trace", "human", "preference", "realtime", "refresh", "routing", "stored_fields"

see the mget docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html> for more info.

🧚 mtermvectors()

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

    body    => { }              # optional
)

runs multiple termvector() requests in one single request, like:

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

Query string parameters: "error_trace", "field_statistics", "fields", "human", "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 info.

🔍 SEARCH METHODS 🔍

the search methods are for querying documents in one, more, or all the indices, and of one, more, or all types. main character energy fr fr.

⭐ search()

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

    body    => { search params }        # optional
);

the search() method hunts for matching documents in one or more indices. and ngl it's just as easy to search a single index as it is to search every index in your whole 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. versatile icon. 💅

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

but tbh 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, then 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_excludes", "_source_includes", "allow_no_indices", "allow_partial_search_results", "analyze_wildcard", "analyzer", "batched_reduce_size", "default_operator", "df", "docvalue_fields", "error_trace", "expand_wildcards", "explain", "from", "human", "ignore_throttled", "ignore_unavailable", "lenient", "max_concurrent_shard_requests", "pre_filter_shard_size", "preference", "q", "request_cache", "rest_total_hits_as_int", "routing", "scroll", "search_type", "seq_no_primary_term", "size", "sort", "stats", "stored_fields", "suggest_field", "suggest_mode", "suggest_size", "suggest_text", "terminate_after", "timeout", "track_scores", "track_total_hits", "typed_keys", "version"

see the search reference <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html> for more info.

also go look at "send_get_body_as" in Search::Elasticsearch::Transport. 🫶

🍓 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", "error_trace", "expand_wildcards", "human", "ignore_throttled", "ignore_unavailable", "lenient", "lowercase_expanded_terms" "min_score", "preference", "q", "routing", "terminate_after"

see the count docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-count.html> for more info.

💜 search_template()

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

    body    => { search params }        # required
);

do a search by specifying a template (either predefined or defined right there inside the body) plus the parameters to use with that template, like:

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

See the search template docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html> for more info, bestie 💅

Query string parameters: "allow_no_indices", "error_trace", "expand_wildcards", "explain", "human", "ignore_throttled", "ignore_unavailable", "preference", "profile", "rest_total_hits_as_int", "scroll", "search_type", "typed_keys"

✨ `render_search_template()` ✨

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

Renders the template, fills in the parameters you passed in, and hands you back the resulting JSON. It's giving fill-in-the-blanks but make it ✨search✨, like:

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

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

🌈 `scroll()` 🌈

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

Once a search() has been done with the scroll parameter, scroll() lets you keep pulling more results until they're all exhausted. Like a lil conveyor belt of hits, no cap 🍓

See scroll_helper() and Search::Elasticsearch::Client::8_0::Scroll for a helper utility that makes managing scroll requests so much easier.

Query string parameters: "error_trace", "human", "rest_total_hits_as_int", "scroll", "scroll_id"

See 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 info 💖

🎀 `clear_scroll()` 🎀

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

The clear_scroll() method can clear unfinished scroll requests, which frees up resources on the server. Be a good citizen and clean up after yourself, periodt 💅

🦋 `scroll_helper()` 🦋

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

Returns a brand new instance of the class specified in scroll_helper_class, which defaults to Search::Elasticsearch::Client::8_0::Scroll. Iconic default, honestly 👑

🌸 `msearch()` 🌸

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

    body    => [ searches ]                     # required
);

The msearch() method lets you do multiple searches in one single request. Very much like the bulk() request, each search request in the body is two hashes: first the metadata hash, then the search request hash (aka 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 parameters: "error_trace", "human", "max_concurrent_searches", "max__concurrent_shard_requests", "pre_filter_shard_size", "rest_total_hits_as_int", "search_type", "typed_keys"

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

💜 `msearch_template()` 💜

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

    body    => [ search_templates ]             # required
);

The msearch_template() method lets you do multiple searches in one single request using search templates. Same vibe as the bulk() request: each search request in the body is two hashes — the metadata hash, then the search request hash (the 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
        {},
        { source => { query => { match => { user => "{{user}}" }}} params => { user => 'joe' }},

        # uses a custom index
        { index => 'not_the_default_index' },
        { source => { query => { match => { user => "{{user}}" }}} params => { user => 'joe' }},
    ]
);

Query string parameters: "error_trace", "human", "max_concurrent_searches", "rest_total_hits_as_int", "search_type", "typed_keys"

See the msearch-template docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html> for more info 🌈

🔥 `explain()` 🔥

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

    body    => { search }   # required
);

The explain() method spills the tea on why the specified document did or did not match a query, and how the relevance score was calculated. For instance:

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

Query string parameters: "_source", "_source_excludes", "_source_includes", "analyze_wildcard", "analyzer", "default_operator", "df", "error_trace", "human", "lenient", "parent", "preference", "q", "routing", "stored_fields"

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

👑 `field_caps()` 👑

$response = $e->field_caps(
    index   => 'index'   | \@indices,   # optional
    body    => { filters }              # optional
);

The field-caps API returns field types and abilities, merged across indices. Like a lil glow-up report for your fields ✨

Query string parameters: "allow_no_indices", "error_trace", "expand_wildcards", "fields", "human", "ignore_unavailable"

See the field-caps docs <http://www.elastic.co/guide/en/elasticsearch/reference/current/search-field-caps.html> for more info 🎀

💖 `search_shards()` 💖

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

The search_shards() method returns information about which shards on which nodes will execute a search request. It's giving behind-the-scenes tour 🫶

Query string parameters: "allow_no_indices", "error_trace", "expand_wildcards", "human", "ignore_unavailable", "local", "preference", "routing"

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

🧚 `rank_eval()` 🧚

$result = $e->rank_eval(
    index   => 'index' | \@indices,     # optional
    body    => {...}                    # required
);

The ranking evaluation API gives you a way to run test cases to figure out whether your search results are improving or worsening. Basically a vibe check for your relevance 💅

Query string parameters: "allow_no_indices", "error_trace", "expand_wildcards", "filter_path", "human", "ignore_unavailable"

See the rank-eval docs <https://www.elastic.co/guide/en/elasticsearch/reference/current/search-rank-eval.html> for more info 🔥

💅 CRUD-BY-QUERY METHODS 💅

🌸 `delete_by_query()`

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

The delete_by_query() method deletes all the documents that match the query you hand it. Like, every single one. Gone. Periodt. 💀

Query string parameters:

"_source"
"_source_excludes"
"_source_includes"
"allow_no_indices"
"analyze_wildcard"
"analyzer"
"conflicts"
"default_operator"
"df"
"error_trace"
"expand_wildcards"
"from"
"human"
"ignore_unavailable"
"lenient"
"preference"
"q"
"refresh"
"request_cache"
"requests_per_second"
"routing"
"scroll"
"scroll_size"
"search_timeout"
"search_type"
"size"
"slices"
"sort"
"stats"
"terminate_after"
"version"
"timeout"
"wait_for_active_shards"
"wait_for_completion"

Want the full lore? The delete-by-query docs live at https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html 🦋

🎀 `delete_by_query_rethrottle()`

$response = $e->delete_by_query_rethrottle(
    task_id             => 'id'         # required
    requests_per_second => num
);

The delete_by_query_rethrottle() API dynamically updates the throtting of a delete-by-query request that's already running, and you point at it with "task_id". It's giving "hey bestie, slow down a lil" energy. 🐢

Query string parameters:

"error_trace"
"filter_path"
"human"
"requests_per_second"

Docs are over here: https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html ✨

🌈 `reindex()`

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

The reindex() API indexes documents from one index — or multiple indices — into a brand new index. Moving day, but for your docs. 🚚💨

Query string parameters:

"error_trace"
"human"
"refresh"
"requests_per_second"
"slices"
"timeout"
"wait_for_active_shards"
"wait_for_completion"

The reindex docs are at https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html 🌟

💜 `reindex_rethrottle()`

$response = $e->delete_by_query_rethrottle(
    task_id => 'id',            # required
    requests_per_second => num
);

okay so — no cap — this synopsis literally says $e->delete_by_query_rethrottle even though we're in the reindex_rethrottle() section. That's exactly what the page says, so that's exactly what you're getting. I'm not fixing it, bestie, I'm just the messenger. 💀

The reindex_rethrottle() API dynamically updates the throtting of a reindex request that's already out there living its life, identified by "task_id".

Query string parameters:

"error_trace"
"filter_path"
"human"
"requests_per_second"

Docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html 🧚

⭐ `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 bulk-updates documents from one index or several indices, using a script. Glow-up for your whole dataset. 👑

Query string parameters:

"_source"
"_source_excludes"
"_source_includes"
"allow_no_indices"
"analyze_wildcard"
"analyzer"
"conflicts"
"default_operator"
"df"
"error_trace"
"expand_wildcards"
"from"
"human"
"ignore_unavailable"
"lenient"
"pipeline"
"preference"
"q"
"refresh"
"request_cache"
"requests_per_second"
"routing"
"scroll"
"scroll_size"
"search_timeout"
"search_type"
"size"
"slices"
"sort"
"stats"
"terminate_after"
"timeout"
"version"
"version_type"
"wait_for_active_shards"
"wait_for_completion"

Full docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html 🌸

🫶 `update_by_query_rethrottle()`

$response = $e->update_by_query_rethrottle(
    task_id             => 'id'         # required
    requests_per_second => num
);

The update_by_query_rethrottle() API dynamically updates the throtting of an update-by-query request, and "task_id" is how you identify which one you mean. 💖

Query string parameters:

"error_trace"
"filter_path"
"human"
"requests_per_second"

Docs: https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html 😭

📜 INDEXED SCRIPT METHODS 📜

Elasticsearch lets you store scripts right in the cluster state and then reference them by id. Iconic behaviour, honestly. The methods to manage those indexed scripts are as follows:

✨ `put_script()`

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

The put_script() method stores a script in the cluster state. For instance:

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

Query string parameters:

"error_trace"
"human"

The indexed scripts docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts 🦋

🌟 `get_script()`

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

Retrieve the indexed script from the cluster state. Just, like, go get it. 💅

Query string parameters:

"error_trace"
"human"
"master_timeout"

The indexed scripts docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts 💜

🎀 `delete_script()`

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

Delete the indexed script from the cluster state. Bye bestie, you will not be missed (jk, but you are deleted). 💀

Query string parameters:

"error_trace"
"human"
"master_timeout"
"timeout"

The indexed scripts docs: http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts 🧚

🌈 `scripts_painless_execute()`

$result = $e->scripts_painless_execute(
    body => {...}   # required
);

The Painless execute API lets an arbitrary script run and hands you back a result. It's giving "try it and see" main character energy. 🔥

Query string parameters:

"error_trace"
"filter_path"
"human"

The painless execution docs: https://www.elastic.co/guide/en/elasticsearch/painless/current/painless-execute-api.html ⭐

👑 AUTHOR 👑

Enrico Zimuel <enrico.zimuel@elastic.co> — legend behaviour, fr fr. 💖

📄 COPYRIGHT AND LICENSE 📄

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

And that's a wrap, bestie! This was Search...Direct(3pm), rendered with perl v5.38.2, dated 2024-02-04. Slay, go forth, and may your queries always be indexed. 🎀💅✨

📦 where this page comes from

debian trixie: libsearch-elasticsearch-perl 8.12-1 · Apache-2.0
ubuntu noble: libsearch-elasticsearch-perl 8.12-1 · Apache-2.0
ubuntu resolute: libsearch-elasticsearch-perl 8.12-1 · Apache-2.0
ubuntu stonking: libsearch-elasticsearch-perl 8.12-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::8_0::Direct 💖

✨ NAME ✨

🎀 VERSION 🎀

🌸 SYNOPSIS 🌸

💜 DESCRIPTION 💜

🌈 PREVIOUS VERSIONS OF ELASTICSEARCH 🌈

✨ CONVENTIONS ✨

🎀 Parameter passing 🎀

🦋 Path parameters 🦋

🌸 Query-string parameters 🌸

💖 Body parameter 💖

⭐ Boolean parameters ⭐

🔍 Filter path parameter 🔍

🙈 Ignore parameter 🙈

💅 CONFIGURATION 💅

🌟 "bulk_helper_class" 🌟

🌟 "scroll_helper_class" 🌟

👑 GENERAL METHODS 👑

💖 info()

💖 ping()

💖 indices()

💖 ingest()

💖 cluster()

💖 nodes()

💖 snapshot()

💖 tasks()

💖 cat()

💖 ccr()

💖 ilm()

🎀 DOCUMENT CRUD METHODS 🎀

✨ index()

✨ create()

✨ get()

✨ get_source()

✨ exists()

✨ delete()

✨ update()

✨ termvectors()

💥 BULK DOCUMENT CRUD METHODS 💥

🎀 bulk()

🌸 bulk_helper()

🦋 mget()

🧚 mtermvectors()

🔍 SEARCH METHODS 🔍

⭐ search()

🍓 count()

💜 search_template()

✨ render_search_template() ✨

🌈 scroll() 🌈

🎀 clear_scroll() 🎀

🦋 scroll_helper() 🦋

🌸 msearch() 🌸

💜 msearch_template() 💜

🔥 explain() 🔥

👑 field_caps() 👑

💖 search_shards() 💖

🧚 rank_eval() 🧚

💅 CRUD-BY-QUERY METHODS 💅

🌸 delete_by_query()

🎀 delete_by_query_rethrottle()

🌈 reindex()

💜 reindex_rethrottle()

⭐ update_by_query()

🫶 update_by_query_rethrottle()

📜 INDEXED SCRIPT METHODS 📜

✨ put_script()

🌟 get_script()

🎀 delete_script()

🌈 scripts_painless_execute()

👑 AUTHOR 👑

📄 COPYRIGHT AND LICENSE 📄

🌟 `"bulk_helper_class"` 🌟

🌟 `"scroll_helper_class"` 🌟

💖 `info()`

💖 `ping()`

💖 `indices()`

💖 `ingest()`

💖 `cluster()`

💖 `nodes()`

💖 `snapshot()`

💖 `tasks()`

💖 `cat()`

💖 `ccr()`

💖 `ilm()`

✨ `index()`

✨ `create()`

✨ `get()`

✨ `get_source()`

✨ `exists()`

✨ `delete()`

✨ `update()`

✨ `termvectors()`

✨ `render_search_template()` ✨

🌈 `scroll()` 🌈

🎀 `clear_scroll()` 🎀

🦋 `scroll_helper()` 🦋

🌸 `msearch()` 🌸

💜 `msearch_template()` 💜

🔥 `explain()` 🔥

👑 `field_caps()` 👑

💖 `search_shards()` 💖

🧚 `rank_eval()` 🧚

🌸 `delete_by_query()`

🎀 `delete_by_query_rethrottle()`

🌈 `reindex()`

💜 `reindex_rethrottle()`

⭐ `update_by_query()`

🫶 `update_by_query_rethrottle()`

✨ `put_script()`

🌟 `get_script()`

🎀 `delete_script()`

🌈 `scripts_painless_execute()`