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

FreeBSD Manual Pages


home | help
Search::Elasticsearch:UsereContributed PerlSearch::Elasticsearch::Role::Cxn(3)

       Search::Elasticsearch::Role::Cxn	- Provides common functionality	to
       HTTP Cxn	implementations

       version 6.00

       Search::Elasticsearch::Role::Cxn	provides common	functionality to Cxn
       implementations.	Cxn instances are created by a
       Search::Elasticsearch::Role::CxnPool implementation, using the
       Search::Elasticsearch::Cxn::Factory class.

       The configuration options are as	follows:

       A single	"node" is passed to "new()" by the
       Search::Elasticsearch::Cxn::Factory class.  It can either be a URI or a
       hash containing each part.  For instance:

	   node	=> 'localhost';			   # equiv of 'http://localhost:80'
	   node	=> 'localhost:9200';		   # equiv of 'http://localhost:9200'
	   node	=> 'http://localhost:9200';

	   node	=> 'https://localhost';		   # equiv of 'https://localhost:443'
	   node	=> 'localhost/path';		   # equiv of 'http://localhost:80/path'

	   node	=> 'http://user:pass@localhost';   # equiv of 'http://localhost:80'
						   # with userinfo => 'user:pass'

       Alternatively, a	"node" can be specified	as a hash:

	       scheme	   => 'http',
	       host	   => '',
	       port	   => '9200',
	       path	   => '/path',
	       userinfo	   => 'user:pass'

       Similarly, default values can be	specified with "port", "path_prefix",
       "userinfo" and "use_https":

	   $e =	Search::Elasticsearch->new(
	       port	   => 9201,
	       path_prefix => '/path',
	       userinfo	   => 'user:pass',
	       use_https   => 1,
	       nodes	   => [	'search1', 'search2' ]

       By default, all backends	that support HTTPS disable verification	of the
       host they are connecting	to.  Use "ssl_options" to configure the	type
       of verification that you	would like the client to perform, or to
       configure the client to present its own certificate.

       The values accepted by "ssl_options" depend on the "Cxn"	class.	See
       the documentation for the "Cxn" class that you are using.

       By default, Elasticsearch nodes accept a	maximum	post body of 100MB or
       "104_857_600" bytes. This client	enforces that limit.  The limit	can be
       customised with the "max_content_length"	parameter (specified in

       If you're using the Search::Elasticsearch::CxnPool::Sniff module, then
       the "max_content_length"	will be	automatically retrieved	from the live
       cluster,	unless you specify a custom "max_content_length":

	   # max_content_length	retrieved from cluster
	   $e =	Search::Elasticsearch->new(
	       cxn_pool	=> 'Sniff'

	   # max_content_length	fixed at 10,000	bytes
	   $e =	Search::Elasticsearch->new(
	       cxn_pool		  => 'Sniff',
	       max_content_length => 10_000

       Enable Gzip compression of requests to and responses from Elasticsearch
       as follows:

	   $e =	Search::Elasticsearch->new(
	       gzip => 1

       Enable Inflate/Deflate compression of requests to and responses from
       Elasticsearch as	follows:

	   $e =	Search::Elasticsearch->new(
	       deflate => 1

       IMPORTANT: The "request_timeout", "ping_timeout", "sniff_timeout", and
       "sniff_request_timeout" parameters default to values that allow this
       module to function with low powered hardware and	slow networks.	When
       you use Elasticsearch in	production, you	will probably want to reduce
       these timeout parameters	to values that suit your environment.

       The configuration parameters are	as follows:

	   $e =	Search::Elasticsearch->new(
	       request_timeout => 30

       How long	a normal request (ie not a ping	or sniff request) should wait
       before throwing a "Timeout" error.  Defaults to 30 seconds.

       Note: In	production, no CRUD or search request should take 30 seconds
       to run, although	admin tasks like "upgrade()", "optimize()", or
       snapshot	"create()" may take much longer. A more	reasonable value for
       production would	be 10 seconds or lower.

	   $e =	Search::Elasticsearch->new(
	       ping_timeout => 2

       How long	a ping request should wait before throwing a "Timeout" error.
       Defaults	to 2 seconds. The Search::Elasticsearch::CxnPool::Static
       module pings nodes on first use,	after any failure, and periodically to
       ensure that nodes are healthy. The "ping_timeout" should	be long	enough
       to allow	nodes respond in time, but not so long that sick nodes cause
       delays.	A reasonable value for use in production on reasonable
       hardware	would be 0.3-1 seconds.

	   $e =	Search::Elasticsearch->new(
	       dead_timeout => 60

       How long	a Cxn should be	considered to be dead (not used	to serve
       requests), before it is retried.	 The default is	60 seconds.  This
       value is	increased by powers of 2 for each time a request fails.	 In
       other words, the	delay after each failure is as follows:

	   Failure     Delay
	   1	       60 * 1  = 60 seconds
	   2	       60 * 2  = 120 seconds
	   3	       60 * 4  = 240 seconds
	   4	       60 * 8  = 480 seconds
	   5	       60 * 16 = 960 seconds

	   $e =	Search::Elasticsearch->new(
	       max_dead_timeout	=> 3600

       The maximum delay that should be	applied	to a failed node. If the
       "dead_timeout" calculation results in a delay greater than
       "max_dead_timeout" (default "3,600" seconds) then the
       "max_dead_timeout" is used instead.  In other words, dead nodes will be
       retried at least	once every hour	by default.

	   $e =	Search::Elasticsearch->new(
	       sniff_request_timeout =>	2

       How long	a sniff	request	should wait before throwing a "Timeout"	error.
       Defaults	to 2 seconds. A	reasonable value for production	would be 0.5-2

	   $e =	Search::Elasticsearch->new(
	       sniff_timeout =>	1

       How long	the node being sniffed should wait for responses from other
       nodes before responding to the client.  Defaults	to 1 second. A
       reasonable value	in production would be 0.3-1 seconds.

       Note: The "sniff_timeout" is distinct from the "sniff_request_timeout".
       For example, let's say you have a cluster with 5	nodes, 2 of which are
       unhealthy (taking a long	time to	respond):

       o   If you sniff	an unhealthy node, the request will throw a "Timeout"
	   error after "sniff_request_timeout" seconds.

       o   If you sniff	a healthy node,	it will	gather responses from the
	   other nodes,	and give up after "sniff_timeout" seconds, returning
	   just	the information	it has managed to gather from the healthy

       NOTE: The "sniff_request_timeout" must be longer	than the
       "sniff_timeout" to ensure that you get information about	healthy	nodes
       from the	cluster.

       Any default arguments which should be passed when creating a new
       instance	of the class which handles the network transport, eg

	   $e =	Search::Elasticsearch->new(
	       default_qs_params => {
		   session_key => 'my_session_key'

       Any values passed to "default_qs_params"	will be	added to the query
       string of every request.	Also see "default_headers()" in

       None of the methods listed below	are useful to the user.	They are
       documented for those who	are writing alternative	implementations	only.

	   $scheme = $cxn->scheme;

       Returns the scheme of the connection, ie	"http" or "https".

	   $bool = $cxn->is_https;

       Returns "true" or "false" depending on whether the "/scheme()" is
       "https" or not.

	   $userinfo = $cxn->userinfo

       Returns the username and	password of the	cxn, if	any, eg	"user:pass".
       If "userinfo" is	provided, then a Basic Authorization header is added
       to each request.

	   $headers = $cxn->default_headers

       The default headers that	are passed with	each request.  This includes
       the "Accept-Encoding" header if "/deflate" is true, and the
       "Authorization" header if "/userinfo" has a value.  Also	see
       "default_qs_params" in Search::Elasticsearch::Role::Cxn.

	   $int	= $cxn->max_content_length;

       Returns the maximum length in bytes that	the HTTP body can have.

	   $uri	= $cxn->build_uri({ path => '/_search',	qs => {	size =>	10 }});

       Returns the HTTP	URI to use for a particular request, combining the
       passed in "path"	parameter with any defined "path_prefix", and adding
       the query-string	parameters.

       None of the methods listed below	are useful to the user.	They are
       documented for those who	are writing alternative	implementations	only.

	   $host = $cxn->host;

       The value of the	"host" parameter, eg "".

	   $port = $cxn->port;

       The value of the	"port" parameter, eg 9200.

	   $uri	= $cxn->uri;

       A URI object representing the node, eg

	   $bool = $cxn->is_dead

       Is the current node marked as dead.

	   $bool = $cxn->is_live

       Is the current node marked as live.

	   $time = $cxn->next_ping($time)

       Get/set the time	for the	next scheduled ping.  If zero, no ping is
       scheduled and the cxn is	considered to be alive.	 If -1,	a ping is
       scheduled before	the next use.

	   $num	= $cxn->ping_failures($num)

       The number of times that	a cxn has been marked as dead.


       Mark the	cxn as dead, set "next_ping()" and increment

       Mark the	cxn as live, set "next_ping()" and "ping_failures()" to	zero.

       Set "next_ping()" to -1 (ie before next use) and	"ping_failures()" to

	   $bool = $cxn->pings_ok

       Try to ping the node and	call "mark_live()" or "mark_dead()" depending
       on the success or failure of the	ping.

	   $response = $cxn->sniff;

       Send a sniff request to the node	and return the response.

	   ($code,$result) = $cxn->process_response($params, $code, $msg, $body	);

       Processes the response received from an Elasticsearch node and either
       returns the HTTP	status code and	the response body (deserialized	from
       JSON) or	throws an error	of the appropriate type.

       The $params are the original params passed to "perform_request()" in
       Search::Elasticsearch::Transport, the $code is the HTTP status code,
       the $msg	is the error message returned by the backend library and the
       $body is	the HTTP response body returned	by Elasticsearch.

       Clinton Gormley <>

       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.32.0			  2017-11-1Search::Elasticsearch::Role::Cxn(3)


Want to link to this manual page? Use this URL:

home | help