Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Search::Elasticsearch(User Contributed Perl DocumentatSearch::Elasticsearch(3)

NAME
       Search::Elasticsearch - The official client for Elasticsearch

VERSION
       version 5.02

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:

       o   Search::Elasticsearch::Client::2_0

       o   Search::Elasticsearch::Client::1_0

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

       o   Full	support	for all	Elasticsearch APIs

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

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

       o   Good	defaults

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

       o   Logging support via Log::Any

       o   Compatibility with the official clients for Python, Ruby, PHP, and
	   Javascript

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

       o   "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.

       o   "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.

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

	   $e =	Search::Elasticsearch->new(
	       client => '5_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:

       o   Search::Elasticsearch::Transport

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

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

       o   Search::Elasticsearch::Cxn::Hijk

       o   Search::Elasticsearch::Cxn::LWP

       o   Search::Elasticsearch::Cxn::NetCurl

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

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

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

       o   Search::Elasticsearch::CxnPool::Sniff

       o   Search::Elasticsearch::CxnPool::Static::NoPing

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

       o   Search::Elasticsearch::Logger::LogAny

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

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

       o   Search::Elasticsearch::Serializer::JSON::Cpanel

       o   Search::Elasticsearch::Serializer::JSON::XS

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

       o   GitHub

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

       o   CPAN	Ratings

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

       o   Search MetaCPAN

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

       o   IRC

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

       o   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

perl v5.24.1			  2017-04-02	      Search::Elasticsearch(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | PREVIOUS VERSIONS OF ELASTICSEARCH | INSTALLING ELASTICSEARCH | CREATING A NEW INSTANCE | RUNNING REQUESTS | MODULES | BUGS | SUPPORT | TEST SUITE | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Search::Elasticsearch&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help