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 8.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 7.0 branch, which
86       is not backwards compatible with earlier branches.
87
88       If you need to talk to a version of Elasticsearch before 7.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() or
307       delete(). The client parses the user's requests and passes them to the
308       "transport" class to be executed.
309
310       The default version of the client is "7_0::Direct", which can be
311       explicitly specified as follows:
312
313           $e = Search::Elasticsearch->new(
314               client => '7_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::LWP
330
331       •   Search::Elasticsearch::Cxn::NetCurl
332
333   "cxn_factory"
334       The class which the "cxn_pool" uses to create new "cxn" objects.  See:
335
336       •   Search::Elasticsearch::Cxn::Factory
337
338   "cxn_pool" (2)
339       The class to use for the connection pool functionality.  It calls the
340       "cxn_factory" class to create new "cxn" objects when appropriate. See:
341
342       •   Search::Elasticsearch::CxnPool::Static (default)
343
344       •   Search::Elasticsearch::CxnPool::Sniff
345
346       •   Search::Elasticsearch::CxnPool::Static::NoPing
347
348   "logger"
349       The class to use for logging events and tracing HTTP
350       requests/responses.  See:
351
352       •   Search::Elasticsearch::Logger::LogAny
353
354   "serializer"
355       The class to use for serializing request bodies and deserializing
356       response bodies.  See:
357
358       •   Search::Elasticsearch::Serializer::JSON (default)
359
360       •   Search::Elasticsearch::Serializer::JSON::Cpanel
361
362       •   Search::Elasticsearch::Serializer::JSON::XS
363
364       •   Search::Elasticsearch::Serializer::JSON::PP
365

BUGS

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

SUPPORT

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

TEST SUITE

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

AUTHOR

420       Enrico Zimuel <enrico.zimuel@elastic.co>
421

423       This software is Copyright (c) 2022 by Elasticsearch BV.
424
425       This is free software, licensed under:
426
427         The Apache License, Version 2.0, January 2004
428
429
430
431perl v5.36.0                      2023-01-20          Search::Elasticsearch(3)
Impressum