The Perl Advent Calendar needs more articles for 2022. Submit your idea today!
    Search::Elasticsearch - The official client for Elasticsearch

    version 7.711001

        use Search::Elasticsearch;

        # Connect to localhost:9200:

        my $e = Search::Elasticsearch->new();

        # Round-robin between two nodes:

        my $e = Search::Elasticsearch->new(
            nodes => [

        # Connect to cluster at search1:9200, sniff all nodes and round-robin between them:

        my $e = Search::Elasticsearch->new(
            nodes    => 'search1:9200',
            cxn_pool => 'Sniff'

        # Index a document:

            index   => 'my_app',
            type    => 'blog_post',
            id      => 1,
            body    => {
                title   => 'Elasticsearch clients',
                content => 'Interesting content...',
                date    => '2013-09-24'

        # Get the document:

        my $doc = $e->get(
            index   => 'my_app',
            type    => 'blog_post',
            id      => 1

        # Search:

        my $results = $e->search(
            index => 'my_app',
            body  => {
                query => {
                    match => { title => 'elasticsearch' }

        # Cluster requests:

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

        # Index requests:


    Search::Elasticsearch is the official Perl client for Elasticsearch,
    supported by <>. Elasticsearch itself is a
    flexible and powerful open source, distributed real-time search and
    analytics engine for the cloud. You can read more about it on

    This version of the client supports the Elasticsearch 7.0 branch, which
    is not backwards compatible with earlier branches.

    If you need to talk to a version of Elasticsearch before 7.0.0, please
    install one of the following packages:

    *   Search::Elasticsearch::Client::2_0

    *   Search::Elasticsearch::Client::1_0

    *   Search::Elasticsearch::Client::0_90

        *The greatest deception men suffer is from their own opinions.*

        Leonardo da Vinci

    All of us have opinions, especially when it comes to designing APIs.
    Unfortunately, the opinions of programmers seldom coincide. The
    intention of this client, and of the officially supported clients
    available for other languages, is to provide robust support for the full
    native Elasticsearch API with as few opinions as possible: you should be
    able to read the Elasticsearch reference documentation
    <> and understand how to use this client, or
    any of the other official clients.

    Should you decide that you want to customize the API, then this client
    provides the basis for your code. It does the hard stuff for you,
    allowing you to build on top of it.

    This client provides:

    *   Full support for all Elasticsearch APIs

    *   HTTP backend (for an async backend using Promises, see

    *   Robust networking support which handles load balancing, failure
        detection and failover

    *   Good defaults

    *   Helper utilities for more complex operations, such as bulk indexing,
        and scrolled searches

    *   Logging support via Log::Any

    *   Compatibility with the official clients for Python, Ruby, PHP, and

    *   Easy extensibility

    You can download the latest version of Elasticsearch from
    <>. See the installation instructions
    tml> for details. You will need to have a recent version of Java
    installed, preferably the Java v8 from Sun.

    The "new()" method returns a new client which can be used to run
    requests against the Elasticsearch cluster.

        use Search::Elasticsearch;
        my $e = Search::Elasticsearch->new( %params );

    The most important arguments to "new()" are the following:

    The "nodes" parameter tells the client which Elasticsearch nodes it
    should talk to. It can be a single node, multiples nodes or, if not
    specified, will default to "localhost:9200":

        # default: localhost:9200
        $e = Search::Elasticsearch->new();

        # single
        $e = Search::Elasticsearch->new( nodes => 'search_1:9200');

        # multiple
        $e = Search::Elasticsearch->new(
            nodes => [

    Each "node" can be a URL including a scheme, host, port, path and
    userinfo (for authentication). For instance, this would be a valid node:

    See "node" in Search::Elasticsearch::Role::Cxn for more on node

    The CxnPool modules manage connections to nodes in the Elasticsearch
    cluster. They handle the load balancing between nodes and failover when
    nodes fail. Which "CxnPool" you should use depends on where your cluster
    is. There are three choices:

    *   "Static"

            $e = Search::Elasticsearch->new(
                cxn_pool => 'Static'     # default
                nodes    => [

        The Static connection pool, which is the default, should be used
        when you don't have direct access to the Elasticsearch cluster, eg
        when you are accessing the cluster through a proxy. See
        Search::Elasticsearch::CxnPool::Static for more.

    *   "Sniff"

            $e = Search::Elasticsearch->new(
                cxn_pool => 'Sniff',
                nodes    => [

        The Sniff connection pool should be used when you do have direct
        access to the Elasticsearch cluster, eg when your web servers and
        Elasticsearch servers are on the same network. The nodes that you
        specify are used to *discover* the cluster, which is then *sniffed*
        to find the current list of live nodes that the cluster knows about.
        See Search::Elasticsearch::CxnPool::Sniff.

    *   "Static::NoPing"

            $e = Search::Elasticsearch->new(
                cxn_pool => 'Static::NoPing'
                nodes    => [

        The Static::NoPing connection pool should be used when your access
        to a remote cluster is so limited that you cannot ping individual
        nodes with a "HEAD /" request.

        See Search::Elasticsearch::CxnPool::Static::NoPing for more.

    For debugging purposes, it is useful to be able to dump the actual HTTP
    requests which are sent to the cluster, and the response that is
    received. This can be enabled with the "trace_to" parameter, as follows:

        # To STDERR
        $e = Search::Elasticsearch->new(
            trace_to => 'Stderr'

        # To a file
        $e = Search::Elasticsearch->new(
            trace_to => ['File','/path/to/filename']

    Logging is handled by Log::Any. See
    Search::Elasticsearch::Logger::LogAny for more information.

    Other arguments are explained in the respective module docs.

    When you create a new instance of Search::Elasticsearch, it returns a
    client object, which can be used for running requests.

        use Search::Elasticsearch;
        my $e = Search::Elasticsearch->new( %params );

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

        # index a document
            index   => 'my_index',
            type    => 'blog_post',
            id      => 1,
            body    => {
                title   => 'Elasticsearch clients',
                content => 'Interesting content...',
                date    => '2013-09-24'

    See Search::Elasticsearch::Client::6_0::Direct for more details about
    the requests that can be run.

    Each chunk of functionality is handled by a different module, which can
    be specified in the call to new() as shown in cxn_pool above. For
    instance, the following will use the
    Search::Elasticsearch::CxnPool::Sniff module for the connection pool.

        $e = Search::Elasticsearch->new(
            cxn_pool => 'Sniff'

    Custom modules can be named with the appropriate prefix, eg
    "Search::Elasticsearch::CxnPool::", or by prefixing the full class name
    with "+":

        $e = Search::Elasticsearch->new(
            cxn_pool => '+My::Custom::CxnClass'

    The modules that you can override are specified with the following
    arguments to "new()":

    The class to use for the client functionality, which provides methods
    that can be called to execute requests, such as "search()", "index()" or
    "delete()". The client parses the user's requests and passes them to the
    "transport" class to be executed.

    The default version of the client is "7_0::Direct", which can be
    explicitly specified as follows:

        $e = Search::Elasticsearch->new(
            client => '7_0::Direct'

    The Transport class accepts a parsed request from the "client" class,
    fetches a "cxn" from its "cxn_pool" and tries to execute the request,
    retrying after failure where appropriate. See:

    *   Search::Elasticsearch::Transport

    The class which handles raw requests to Elasticsearch nodes. See:

    *   Search::Elasticsearch::Cxn::HTTPTiny (default)

    *   Search::Elasticsearch::Cxn::LWP

    *   Search::Elasticsearch::Cxn::NetCurl

    The class which the "cxn_pool" uses to create new "cxn" objects. See:

    *   Search::Elasticsearch::Cxn::Factory

  "cxn_pool" (2)
    The class to use for the connection pool functionality. It calls the
    "cxn_factory" class to create new "cxn" objects when appropriate. See:

    *   Search::Elasticsearch::CxnPool::Static (default)

    *   Search::Elasticsearch::CxnPool::Sniff

    *   Search::Elasticsearch::CxnPool::Static::NoPing

    The class to use for logging events and tracing HTTP requests/responses.

    *   Search::Elasticsearch::Logger::LogAny

    The class to use for serializing request bodies and deserializing
    response bodies. See:

    *   Search::Elasticsearch::Serializer::JSON (default)

    *   Search::Elasticsearch::Serializer::JSON::Cpanel

    *   Search::Elasticsearch::Serializer::JSON::XS

    *   Search::Elasticsearch::Serializer::JSON::PP

    This is a stable API but this implementation is new. Watch this space
    for new releases.

    If you have any suggestions for improvements, or find any bugs, please
    report them to
    <>. I will be
    notified, and then you'll automatically be notified of progress on your
    bug as I make changes.

    You can find documentation for this module with the perldoc command.

        perldoc Search::Elasticsearch

    You can also look for information at:

    *   GitHub


    *   CPAN Ratings


    *   Search MetaCPAN


    *   IRC

        The #elasticsearch <irc://> channel on

    *   Mailing list

        The main Elasticsearch mailing list <>.

    The full test suite requires a live Elasticsearch node to run, and
    should be run as :

        perl Makefile.PL
        ES=localhost:9200 make test


    You can change the Cxn class which is used by setting the "ES_CXN"
    environment variable:

        ES_CXN=NetCurl ES=localhost:9200 make test

    Enrico Zimuel <>

    This software is Copyright (c) 2021 by Elasticsearch BV.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004