1Search::Elasticsearch(3U)ser Contributed Perl DocumentatiSoenarch::Elasticsearch(3)
2
3
4

NAME

6       Search::Elasticsearch - The official client for Elasticsearch
7

VERSION

9       version 6.00
10

SYNOPSIS

12           use Search::Elasticsearch;
13
14           # Connect to localhost:9200:
15
16           my $e = Search::Elasticsearch->new();
17
18           # Round-robin between two nodes:
19
20           my $e = Search::Elasticsearch->new(
21               nodes => [
22                   'search1:9200',
23                   'search2:9200'
24               ]
25           );
26
27           # Connect to cluster at search1:9200, sniff all nodes and round-robin between them:
28
29           my $e = Search::Elasticsearch->new(
30               nodes    => 'search1:9200',
31               cxn_pool => 'Sniff'
32           );
33
34           # Index a document:
35
36           $e->index(
37               index   => 'my_app',
38               type    => 'blog_post',
39               id      => 1,
40               body    => {
41                   title   => 'Elasticsearch clients',
42                   content => 'Interesting content...',
43                   date    => '2013-09-24'
44               }
45           );
46
47           # Get the document:
48
49           my $doc = $e->get(
50               index   => 'my_app',
51               type    => 'blog_post',
52               id      => 1
53           );
54
55           # Search:
56
57           my $results = $e->search(
58               index => 'my_app',
59               body  => {
60                   query => {
61                       match => { title => 'elasticsearch' }
62                   }
63               }
64           );
65
66           # Cluster requests:
67
68           $info        = $e->cluster->info;
69           $health      = $e->cluster->health;
70           $node_stats  = $e->cluster->node_stats;
71
72           # Index requests:
73
74           $e->indices->create(index=>'my_index');
75           $e->indices->delete(index=>'my_index');
76

DESCRIPTION

78       Search::Elasticsearch is the official Perl client for Elasticsearch,
79       supported by elastic.co <http://elastic.co>.  Elasticsearch itself is a
80       flexible and powerful open source, distributed real-time search and
81       analytics engine for the cloud.  You can read more about it on
82       elastic.co <http://www.elastic.co>.
83

PREVIOUS VERSIONS OF ELASTICSEARCH

85       This version of the client supports the Elasticsearch 5.0 branch, which
86       is not backwards compatible with earlier branches.
87
88       If you need to talk to a version of Elasticsearch before 5.0.0, please
89       install one of the following packages:
90
91       ·   Search::Elasticsearch::Client::2_0
92
93       ·   Search::Elasticsearch::Client::1_0
94
95       ·   Search::Elasticsearch::Client::0_90
96
97   Motivation
98           The greatest deception men suffer is from their own opinions.
99
100           Leonardo da Vinci
101
102       All of us have opinions, especially when it comes to designing APIs.
103       Unfortunately, the opinions of programmers seldom coincide. The
104       intention of this client, and of the officially supported clients
105       available for other languages, is to provide robust support for the
106       full native Elasticsearch API with as few opinions as possible:  you
107       should be able to read the Elasticsearch reference documentation
108       <http://www.elastic.co/guide> and understand how to use this client, or
109       any of the other official clients.
110
111       Should you decide that you want to customize the API, then this client
112       provides the basis for your code.  It does the hard stuff for you,
113       allowing you to build on top of it.
114
115   Features
116       This client provides:
117
118       ·   Full support for all Elasticsearch APIs
119
120       ·   HTTP backend (for an async backend using Promises, see
121           Search::Elasticsearch::Async)
122
123       ·   Robust networking support which handles load balancing, failure
124           detection and failover
125
126       ·   Good defaults
127
128       ·   Helper utilities for more complex operations, such as bulk
129           indexing, and scrolled searches
130
131       ·   Logging support via Log::Any
132
133       ·   Compatibility with the official clients for Python, Ruby, PHP, and
134           Javascript
135
136       ·   Easy extensibility
137

INSTALLING ELASTICSEARCH

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

CREATING A NEW INSTANCE

146       The "new()" method returns a new client which can be used to run
147       requests against the Elasticsearch cluster.
148
149           use Search::Elasticsearch;
150           my $e = Search::Elasticsearch->new( %params );
151
152       The most important arguments to "new()" are the following:
153
154   "nodes"
155       The "nodes" parameter tells the client which Elasticsearch nodes it
156       should talk to.  It can be a single node, multiples nodes or, if not
157       specified, will default to "localhost:9200":
158
159           # default: localhost:9200
160           $e = Search::Elasticsearch->new();
161
162           # single
163           $e = Search::Elasticsearch->new( nodes => 'search_1:9200');
164
165           # multiple
166           $e = Search::Elasticsearch->new(
167               nodes => [
168                   'search_1:9200',
169                   'search_2:9200'
170               ]
171           );
172
173       Each "node" can be a URL including a scheme, host, port, path and
174       userinfo (for authentication).  For instance, this would be a valid
175       node:
176
177           https://username:password@search.domain.com:443/prefix/path
178
179       See "node" in Search::Elasticsearch::Role::Cxn for more on node
180       specification.
181
182   "cxn_pool"
183       The CxnPool modules manage connections to nodes in the Elasticsearch
184       cluster.  They handle the load balancing between nodes and failover
185       when nodes fail. Which "CxnPool" you should use depends on where your
186       cluster is. There are three choices:
187
188       ·   "Static"
189
190               $e = Search::Elasticsearch->new(
191                   cxn_pool => 'Static'     # default
192                   nodes    => [
193                       'search1.domain.com:9200',
194                       'search2.domain.com:9200'
195                   ],
196               );
197
198           The Static connection pool, which is the default, should be used
199           when you don't have direct access to the Elasticsearch cluster, eg
200           when you are accessing the cluster through a proxy.  See
201           Search::Elasticsearch::CxnPool::Static for more.
202
203       ·   "Sniff"
204
205               $e = Search::Elasticsearch->new(
206                   cxn_pool => 'Sniff',
207                   nodes    => [
208                       'search1:9200',
209                       'search2:9200'
210                   ],
211               );
212
213           The Sniff connection pool should be used when you do have direct
214           access to the Elasticsearch cluster, eg when your web servers and
215           Elasticsearch servers are on the same network.  The nodes that you
216           specify are used to discover the cluster, which is then sniffed to
217           find the current list of live nodes that the cluster knows about.
218           See Search::Elasticsearch::CxnPool::Sniff.
219
220       ·   "Static::NoPing"
221
222               $e = Search::Elasticsearch->new(
223                   cxn_pool => 'Static::NoPing'
224                   nodes    => [
225                       'proxy1.domain.com:80',
226                       'proxy2.domain.com:80'
227                   ],
228               );
229
230           The Static::NoPing connection pool should be used when your access
231           to a remote cluster is so limited that you cannot ping individual
232           nodes with a "HEAD /" request.
233
234           See Search::Elasticsearch::CxnPool::Static::NoPing for more.
235
236   "trace_to"
237       For debugging purposes, it is useful to be able to dump the actual HTTP
238       requests which are sent to the cluster, and the response that is
239       received.  This can be enabled with the "trace_to" parameter, as
240       follows:
241
242           # To STDERR
243           $e = Search::Elasticsearch->new(
244               trace_to => 'Stderr'
245           );
246
247           # To a file
248           $e = Search::Elasticsearch->new(
249               trace_to => ['File','/path/to/filename']
250           );
251
252       Logging is handled by Log::Any.  See
253       Search::Elasticsearch::Logger::LogAny for more information.
254
255   Other
256       Other arguments are explained in the respective module docs.
257

RUNNING REQUESTS

259       When you create a new instance of Search::Elasticsearch, it returns a
260       client object, which can be used for running requests.
261
262           use Search::Elasticsearch;
263           my $e = Search::Elasticsearch->new( %params );
264
265           # create an index
266           $e->indices->create( index => 'my_index' );
267
268           # index a document
269           $e->index(
270               index   => 'my_index',
271               type    => 'blog_post',
272               id      => 1,
273               body    => {
274                   title   => 'Elasticsearch clients',
275                   content => 'Interesting content...',
276                   date    => '2013-09-24'
277               }
278           );
279
280       See Search::Elasticsearch::Client::6_0::Direct for more details about
281       the requests that can be run.
282

MODULES

284       Each chunk of functionality is handled by a different module, which can
285       be specified in the call to new() as shown in cxn_pool above.  For
286       instance, the following will use the
287       Search::Elasticsearch::CxnPool::Sniff module for the connection pool.
288
289           $e = Search::Elasticsearch->new(
290               cxn_pool => 'Sniff'
291           );
292
293       Custom modules can be named with the appropriate prefix, eg
294       "Search::Elasticsearch::CxnPool::", or by prefixing the full class name
295       with "+":
296
297           $e = Search::Elasticsearch->new(
298               cxn_pool => '+My::Custom::CxnClass'
299           );
300
301       The modules that you can override are specified with the following
302       arguments to "new()":
303
304   "client"
305       The class to use for the client functionality, which provides methods
306       that can be called to execute requests, such as "search()", "index()"
307       or "delete()". The client parses the user's requests and passes them to
308       the "transport" class to be executed.
309
310       The default version of the client is "6_0::Direct", which can be
311       explicitly specified as follows:
312
313           $e = Search::Elasticsearch->new(
314               client => '6_0::Direct'
315           );
316
317   "transport"
318       The Transport class accepts a parsed request from the "client" class,
319       fetches a "cxn" from its "cxn_pool" and tries to execute the request,
320       retrying after failure where appropriate. See:
321
322       ·   Search::Elasticsearch::Transport
323
324   "cxn"
325       The class which handles raw requests to Elasticsearch nodes.  See:
326
327       ·   Search::Elasticsearch::Cxn::HTTPTiny (default)
328
329       ·   Search::Elasticsearch::Cxn::Hijk
330
331       ·   Search::Elasticsearch::Cxn::LWP
332
333       ·   Search::Elasticsearch::Cxn::NetCurl
334
335   "cxn_factory"
336       The class which the "cxn_pool" uses to create new "cxn" objects.  See:
337
338       ·   Search::Elasticsearch::Cxn::Factory
339
340   "cxn_pool" (2)
341       The class to use for the connection pool functionality.  It calls the
342       "cxn_factory" class to create new "cxn" objects when appropriate. See:
343
344       ·   Search::Elasticsearch::CxnPool::Static (default)
345
346       ·   Search::Elasticsearch::CxnPool::Sniff
347
348       ·   Search::Elasticsearch::CxnPool::Static::NoPing
349
350   "logger"
351       The class to use for logging events and tracing HTTP
352       requests/responses.  See:
353
354       ·   Search::Elasticsearch::Logger::LogAny
355
356   "serializer"
357       The class to use for serializing request bodies and deserializing
358       response bodies.  See:
359
360       ·   Search::Elasticsearch::Serializer::JSON (default)
361
362       ·   Search::Elasticsearch::Serializer::JSON::Cpanel
363
364       ·   Search::Elasticsearch::Serializer::JSON::XS
365
366       ·   Search::Elasticsearch::Serializer::JSON::PP
367

BUGS

369       This is a stable API but this implementation is new. Watch this space
370       for new releases.
371
372       If you have any suggestions for improvements, or find any bugs, please
373       report them to
374       <http://github.com/elasticsearch/elasticsearch-perl/issues>.  I will be
375       notified, and then you'll automatically be notified of progress on your
376       bug as I make changes.
377

SUPPORT

379       You can find documentation for this module with the perldoc command.
380
381           perldoc Search::Elasticsearch
382
383       You can also look for information at:
384
385       ·   GitHub
386
387           <http://github.com/elasticsearch/elasticsearch-perl>
388
389       ·   CPAN Ratings
390
391           <http://cpanratings.perl.org/d/Search::Elasticsearch>
392
393       ·   Search MetaCPAN
394
395           <https://metacpan.org/module/Search::Elasticsearch>
396
397       ·   IRC
398
399           The #elasticsearch <irc://irc.freenode.net/elasticsearch> channel
400           on "irc.freenode.net".
401
402       ·   Mailing list
403
404           The main Elasticsearch mailing list <http://discuss.elastic.co>.
405

TEST SUITE

407       The full test suite requires a live Elasticsearch node to run, and
408       should be run as :
409
410           perl Makefile.PL
411           ES=localhost:9200 make test
412
413       TESTS RUN IN THIS WAY ARE DESTRUCTIVE! DO NOT RUN AGAINST A CLUSTER
414       WITH DATA YOU WANT TO KEEP!
415
416       You can change the Cxn class which is used by setting the "ES_CXN"
417       environment variable:
418
419           ES_CXN=Hijk ES=localhost:9200 make test
420

AUTHOR

422       Clinton Gormley <drtech@cpan.org>
423

425       This software is Copyright (c) 2017 by Elasticsearch BV.
426
427       This is free software, licensed under:
428
429         The Apache License, Version 2.0, January 2004
430
431
432
433perl v5.30.0                      2019-07-26          Search::Elasticsearch(3)
Impressum