Provided by: libsearch-elasticsearch-perl_6.00-1_all bug

NAME

       Search::Elasticsearch - The official client for Elasticsearch

VERSION

       version 6.00

SYNOPSIS

           use Search::Elasticsearch;

           # Connect to localhost:9200:

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

           # Round-robin between two nodes:

           my $e = Search::Elasticsearch->new(
               nodes => [
                   'search1:9200',
                   'search2:9200'
               ]
           );

           # 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:

           $e->index(
               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:

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

DESCRIPTION

       Search::Elasticsearch is the official Perl client for Elasticsearch, supported by
       elastic.co <http://elastic.co>.  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 elastic.co <http://www.elastic.co>.

PREVIOUS VERSIONS OF ELASTICSEARCH

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

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

       ·   Search::Elasticsearch::Client::2_0

       ·   Search::Elasticsearch::Client::1_0

       ·   Search::Elasticsearch::Client::0_90

   Motivation
           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 <http://www.elastic.co/guide> 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.

   Features
       This client provides:

       ·   Full support for all Elasticsearch APIs

       ·   HTTP backend (for an async backend using Promises, see Search::Elasticsearch::Async)

       ·   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 Javascript

       ·   Easy extensibility

INSTALLING ELASTICSEARCH

       You can download the latest version of Elasticsearch from
       <http://www.elastic.co/download>. See the installation instructions
       <https://www.elastic.co/guide/en/elasticsearch/reference/current/setup.html> for details.
       You will need to have a recent version of Java installed, preferably the Java v8 from Sun.

CREATING A NEW INSTANCE

       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:

   "nodes"
       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 => [
                   'search_1:9200',
                   'search_2:9200'
               ]
           );

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

           https://username:password@search.domain.com:443/prefix/path

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

   "cxn_pool"
       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    => [
                       'search1.domain.com:9200',
                       'search2.domain.com:9200'
                   ],
               );

           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    => [
                       'search1:9200',
                       'search2:9200'
                   ],
               );

           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    => [
                       'proxy1.domain.com:80',
                       'proxy2.domain.com:80'
                   ],
               );

           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.

   "trace_to"
       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
       Other arguments are explained in the respective module docs.

RUNNING REQUESTS

       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
           $e->index(
               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.

MODULES

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

   "client"
       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 "6_0::Direct", which can be explicitly specified as
       follows:

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

   "transport"
       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

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

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

       ·   Search::Elasticsearch::Cxn::Hijk

       ·   Search::Elasticsearch::Cxn::LWP

       ·   Search::Elasticsearch::Cxn::NetCurl

   "cxn_factory"
       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

   "logger"
       The class to use for logging events and tracing HTTP requests/responses.  See:

       ·   Search::Elasticsearch::Logger::LogAny

   "serializer"
       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

BUGS

       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
       <http://github.com/elasticsearch/elasticsearch-perl/issues>.  I will be notified, and then
       you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

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

           perldoc Search::Elasticsearch

       You can also look for information at:

       ·   GitHub

           <http://github.com/elasticsearch/elasticsearch-perl>

       ·   CPAN Ratings

           <http://cpanratings.perl.org/d/Search::Elasticsearch>

       ·   Search MetaCPAN

           <https://metacpan.org/module/Search::Elasticsearch>

       ·   IRC

           The #elasticsearch <irc://irc.freenode.net/elasticsearch> channel on
           "irc.freenode.net".

       ·   Mailing list

           The main Elasticsearch mailing list <http://discuss.elastic.co>.

TEST SUITE

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

           perl Makefile.PL
           ES=localhost:9200 make test

       TESTS RUN IN THIS WAY ARE DESTRUCTIVE! DO NOT RUN AGAINST A CLUSTER WITH DATA YOU WANT TO
       KEEP!

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

           ES_CXN=Hijk ES=localhost:9200 make test

AUTHOR

       Clinton Gormley <drtech@cpan.org>

COPYRIGHT AND LICENSE

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

       This is free software, licensed under:

         The Apache License, Version 2.0, January 2004