Filename | /home/ss5/perl5/perlbrew/perls/perl-5.22.0/lib/site_perl/5.22.0/Search/Elasticsearch/Client/5_0/Direct.pm |
Statements | Executed 24 statements in 727µs |
Calls | P | F | Exclusive Time |
Inclusive Time |
Subroutine |
---|---|---|---|---|---|
1 | 1 | 1 | 9µs | 651µs | BEGIN@3 | Search::Elasticsearch::Client::5_0::Direct::
1 | 1 | 1 | 6µs | 165µs | BEGIN@7 | Search::Elasticsearch::Client::5_0::Direct::
1 | 1 | 1 | 6µs | 128µs | BEGIN@8 | Search::Elasticsearch::Client::5_0::Direct::
1 | 1 | 1 | 4µs | 3.16ms | _build_indices | Search::Elasticsearch::Client::5_0::Direct::
1 | 1 | 1 | 1µs | 1µs | _namespace | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build__bulk_class | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build__scroll_class | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build_cat | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build_cluster | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build_ingest | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build_nodes | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build_snapshot | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | _build_tasks | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | bulk_helper | Search::Elasticsearch::Client::5_0::Direct::
0 | 0 | 0 | 0s | 0s | scroll_helper | Search::Elasticsearch::Client::5_0::Direct::
Line | State ments |
Time on line |
Calls | Time in subs |
Code |
---|---|---|---|---|---|
1 | package Search::Elasticsearch::Client::5_0::Direct; | ||||
2 | 1 | 200ns | $Search::Elasticsearch::Client::5_0::Direct::VERSION = '5.01'; | ||
3 | 2 | 29µs | 2 | 1.29ms | # spent 651µs (9+642) within Search::Elasticsearch::Client::5_0::Direct::BEGIN@3 which was called:
# once (9µs+642µs) by Module::Runtime::require_module at line 3 # spent 651µs making 1 call to Search::Elasticsearch::Client::5_0::Direct::BEGIN@3
# spent 642µs making 1 call to Moo::import |
4 | 1 | 1µs | 1 | 11.3ms | with 'Search::Elasticsearch::Client::5_0::Role::API'; # spent 11.3ms making 1 call to Moo::with |
5 | 1 | 900ns | 1 | 3.67ms | with 'Search::Elasticsearch::Role::Client::Direct'; # spent 3.67ms making 1 call to Moo::with |
6 | |||||
7 | 2 | 21µs | 2 | 324µs | # spent 165µs (6+159) within Search::Elasticsearch::Client::5_0::Direct::BEGIN@7 which was called:
# once (6µs+159µs) by Module::Runtime::require_module at line 7 # spent 165µs making 1 call to Search::Elasticsearch::Client::5_0::Direct::BEGIN@7
# spent 159µs making 1 call to Sub::Exporter::__ANON__[Sub/Exporter.pm:337] |
8 | 2 | 630µs | 2 | 251µs | # spent 128µs (6+123) within Search::Elasticsearch::Client::5_0::Direct::BEGIN@8 which was called:
# once (6µs+123µs) by Module::Runtime::require_module at line 8 # spent 128µs making 1 call to Search::Elasticsearch::Client::5_0::Direct::BEGIN@8
# spent 123µs making 1 call to namespace::clean::import |
9 | |||||
10 | 1 | 3µs | # spent 1µs within Search::Elasticsearch::Client::5_0::Direct::_namespace which was called:
# once (1µs+0s) by Search::Elasticsearch::Role::Client::Direct::_build_namespace at line 149 of Search/Elasticsearch/Role/Client/Direct.pm | ||
11 | |||||
12 | 1 | 2µs | 1 | 154µs | has 'cluster' => ( is => 'lazy', init_arg => undef ); # spent 154µs making 1 call to Moo::has |
13 | 1 | 900ns | 1 | 104µs | has 'nodes' => ( is => 'lazy', init_arg => undef ); # spent 104µs making 1 call to Moo::has |
14 | 1 | 1µs | 1 | 98µs | has 'indices' => ( is => 'lazy', init_arg => undef ); # spent 98µs making 1 call to Moo::has |
15 | 1 | 1µs | 1 | 99µs | has 'ingest' => ( is => 'lazy', init_arg => undef ); # spent 99µs making 1 call to Moo::has |
16 | 1 | 800ns | 1 | 97µs | has 'snapshot' => ( is => 'lazy', init_arg => undef ); # spent 97µs making 1 call to Moo::has |
17 | 1 | 700ns | 1 | 100µs | has 'cat' => ( is => 'lazy', init_arg => undef ); # spent 100µs making 1 call to Moo::has |
18 | 1 | 1µs | 1 | 96µs | has 'tasks' => ( is => 'lazy', init_arg => undef ); # spent 96µs making 1 call to Moo::has |
19 | 1 | 900ns | 1 | 85µs | has 'bulk_helper_class' => ( is => 'rw' ); # spent 85µs making 1 call to Moo::has |
20 | 1 | 1µs | 1 | 66µs | has 'scroll_helper_class' => ( is => 'rw' ); # spent 66µs making 1 call to Moo::has |
21 | 1 | 800ns | 1 | 100µs | has '_bulk_class' => ( is => 'lazy' ); # spent 100µs making 1 call to Moo::has |
22 | 1 | 600ns | 1 | 98µs | has '_scroll_class' => ( is => 'lazy' ); # spent 98µs making 1 call to Moo::has |
23 | |||||
24 | #=================================== | ||||
25 | sub _build__bulk_class { | ||||
26 | #=================================== | ||||
27 | my $self = shift; | ||||
28 | my $bulk_class = $self->bulk_helper_class | ||||
29 | || 'Client::' . $self->api_version . '::Bulk'; | ||||
30 | $self->_build_helper( 'bulk', $bulk_class ); | ||||
31 | } | ||||
32 | |||||
33 | #=================================== | ||||
34 | sub _build__scroll_class { | ||||
35 | #=================================== | ||||
36 | my $self = shift; | ||||
37 | my $scroll_class = $self->scroll_helper_class | ||||
38 | || 'Client::' . $self->api_version . '::Scroll'; | ||||
39 | $self->_build_helper( 'scroll', $scroll_class ); | ||||
40 | } | ||||
41 | |||||
42 | #=================================== | ||||
43 | sub bulk_helper { | ||||
44 | #=================================== | ||||
45 | my ( $self, $params ) = parse_params(@_); | ||||
46 | $params->{es} ||= $self; | ||||
47 | $self->_bulk_class->new($params); | ||||
48 | } | ||||
49 | |||||
50 | #=================================== | ||||
51 | sub scroll_helper { | ||||
52 | #=================================== | ||||
53 | my ( $self, $params ) = parse_params(@_); | ||||
54 | $params->{es} ||= $self; | ||||
55 | $self->_scroll_class->new($params); | ||||
56 | } | ||||
57 | |||||
58 | #=================================== | ||||
59 | sub _build_cluster { shift->_build_namespace('Cluster') } | ||||
60 | sub _build_nodes { shift->_build_namespace('Nodes') } | ||||
61 | 1 | 6µs | 1 | 3.16ms | # spent 3.16ms (4µs+3.16) within Search::Elasticsearch::Client::5_0::Direct::_build_indices which was called:
# once (4µs+3.16ms) by Search::Elasticsearch::Client::5_0::Direct::indices at line 20 of (eval 310)[Sub/Quote.pm:3] # spent 3.16ms making 1 call to Search::Elasticsearch::Role::Client::Direct::_build_namespace |
62 | sub _build_ingest { shift->_build_namespace('Ingest') } | ||||
63 | sub _build_snapshot { shift->_build_namespace('Snapshot') } | ||||
64 | sub _build_cat { shift->_build_namespace('Cat') } | ||||
65 | sub _build_tasks { shift->_build_namespace('Tasks') } | ||||
66 | #=================================== | ||||
67 | |||||
68 | 1 | 3µs | 1 | 5.25ms | __PACKAGE__->_install_api(''); # spent 5.25ms making 1 call to Search::Elasticsearch::Role::Client::Direct::_install_api |
69 | |||||
70 | 1 | 12µs | 1; | ||
71 | |||||
72 | =pod | ||||
73 | |||||
74 | =encoding UTF-8 | ||||
75 | |||||
76 | =head1 NAME | ||||
77 | |||||
78 | Search::Elasticsearch::Client::5_0::Direct - Thin client with full support for Elasticsearch 5.x APIs | ||||
79 | |||||
80 | =head1 VERSION | ||||
81 | |||||
82 | version 5.01 | ||||
83 | |||||
84 | =head1 SYNOPSIS | ||||
85 | |||||
86 | Create a client: | ||||
87 | |||||
88 | use Search::Elasticsearch; | ||||
89 | my $e = Search::Elasticsearch->new( | ||||
90 | client => '5_0::Direct' | ||||
91 | ); | ||||
92 | |||||
93 | Index a doc: | ||||
94 | |||||
95 | $e->index( | ||||
96 | index => 'my_index', | ||||
97 | type => 'blog_post', | ||||
98 | id => 123, | ||||
99 | body => { | ||||
100 | title => "Elasticsearch clients", | ||||
101 | content => "Interesting content...", | ||||
102 | date => "2013-09-23" | ||||
103 | } | ||||
104 | ); | ||||
105 | |||||
106 | Get a doc: | ||||
107 | |||||
108 | $e->get( | ||||
109 | index => 'my_index', | ||||
110 | type => 'my_type', | ||||
111 | id => 123 | ||||
112 | ); | ||||
113 | |||||
114 | Search for docs: | ||||
115 | |||||
116 | $results = $e->search( | ||||
117 | index => 'my_index', | ||||
118 | body => { | ||||
119 | query => { | ||||
120 | match => { | ||||
121 | title => "elasticsearch" | ||||
122 | } | ||||
123 | } | ||||
124 | } | ||||
125 | ); | ||||
126 | |||||
127 | Index-level requests: | ||||
128 | |||||
129 | $e->indices->create( index => 'my_index' ); | ||||
130 | $e->indices->delete( index => 'my_index' ) | ||||
131 | |||||
132 | Ingest pipeline requests: | ||||
133 | |||||
134 | $e->ingest->get_pipeline( id => 'apache-logs' ); | ||||
135 | |||||
136 | Cluster-level requests: | ||||
137 | |||||
138 | $health = $e->cluster->health; | ||||
139 | |||||
140 | Node-level requests: | ||||
141 | |||||
142 | $info = $e->nodes->info; | ||||
143 | $stats = $e->nodes->stats; | ||||
144 | |||||
145 | Snapshot and restore: | ||||
146 | |||||
147 | $e->snapshot->create_repository( | ||||
148 | repository => 'my_backups', | ||||
149 | type => 'fs', | ||||
150 | settings => { | ||||
151 | location => '/mnt/backups' | ||||
152 | } | ||||
153 | ); | ||||
154 | |||||
155 | $e->snapshot->create( | ||||
156 | repository => 'my_backups', | ||||
157 | snapshot => 'backup_2014' | ||||
158 | ); | ||||
159 | |||||
160 | Task management: | ||||
161 | |||||
162 | $e->tasks->list; | ||||
163 | |||||
164 | `cat` debugging: | ||||
165 | |||||
166 | say $e->cat->allocation; | ||||
167 | say $e->cat->health; | ||||
168 | |||||
169 | =head1 DESCRIPTION | ||||
170 | |||||
171 | The L<Search::Elasticsearch::Client::5_0::Direct> class provides the | ||||
172 | Elasticsearch 5.x compatible client returned by: | ||||
173 | |||||
174 | $e = Search::Elasticsearch->new( | ||||
175 | client => "5_0::Direct" # default | ||||
176 | ); | ||||
177 | |||||
178 | It is intended to be as close as possible to the native REST API that | ||||
179 | Elasticsearch uses, so that it is easy to translate the | ||||
180 | L<Elasticsearch reference documentation|http://www.elasticsearch/guide> | ||||
181 | for an API to the equivalent in this client. | ||||
182 | |||||
183 | This class provides the methods for L<document CRUD|/DOCUMENT CRUD METHODS>, | ||||
184 | L<bulk document CRUD|/BULK DOCUMENT CRUD METHODS> and L<search|/SEARCH METHODS>. | ||||
185 | It also provides access to clients for managing L<indices|/indices()> | ||||
186 | and the L<cluster|/cluster()>. | ||||
187 | |||||
188 | =head1 PREVIOUS VERSIONS OF ELASTICSEARCH | ||||
189 | |||||
190 | This version of the client supports the Elasticsearch 5.0 branch, | ||||
191 | which is not backwards compatible with earlier branches. | ||||
192 | |||||
193 | If you need to talk to a version of Elasticsearch before 5.0.0, please | ||||
194 | install one of the following modules: | ||||
195 | |||||
196 | =over | ||||
197 | |||||
198 | =item * | ||||
199 | |||||
200 | L<Search::Elasticsearch::Client::2_0> | ||||
201 | |||||
202 | =item * | ||||
203 | |||||
204 | L<Search::Elasticsearch::Client::1_0> | ||||
205 | |||||
206 | =item * | ||||
207 | |||||
208 | L<Search::Elasticsearch::Client::0_90> | ||||
209 | |||||
210 | =back | ||||
211 | |||||
212 | =head1 CONVENTIONS | ||||
213 | |||||
214 | =head2 Parameter passing | ||||
215 | |||||
216 | Parameters can be passed to any request method as a list or as a hash | ||||
217 | reference. The following two statements are equivalent: | ||||
218 | |||||
219 | $e->search( size => 10 ); | ||||
220 | $e->search({size => 10}); | ||||
221 | |||||
222 | =head2 Path parameters | ||||
223 | |||||
224 | Any values that should be included in the URL path, eg C</{index}/{type}> | ||||
225 | should be passed as top level parameters: | ||||
226 | |||||
227 | $e->search( index => 'my_index', type => 'my_type' ); | ||||
228 | |||||
229 | Alternatively, you can specify a C<path> parameter directly: | ||||
230 | |||||
231 | $e->search( path => '/my_index/my_type' ); | ||||
232 | |||||
233 | =head2 Query-string parameters | ||||
234 | |||||
235 | Any values that should be included in the query string should be passed | ||||
236 | as top level parameters: | ||||
237 | |||||
238 | $e->search( size => 10 ); | ||||
239 | |||||
240 | If you pass in a C<\%params> hash, then it will be included in the | ||||
241 | query string parameters without any error checking. The following: | ||||
242 | |||||
243 | $e->search( size => 10, params => { from => 5, size => 5 }) | ||||
244 | |||||
245 | would result in this query string: | ||||
246 | |||||
247 | ?from=5&size=10 | ||||
248 | |||||
249 | =head2 Body parameter | ||||
250 | |||||
251 | The request body should be passed in the C<body> key: | ||||
252 | |||||
253 | $e->search( | ||||
254 | body => { | ||||
255 | query => {...} | ||||
256 | } | ||||
257 | ); | ||||
258 | |||||
259 | The body can also be a UTF8-decoded string, which will be converted into | ||||
260 | UTF-8 bytes and passed as is: | ||||
261 | |||||
262 | $e->indices->analyze( body => "The quick brown fox"); | ||||
263 | |||||
264 | =head2 Filter path parameter | ||||
265 | |||||
266 | Any API which returns a JSON body accepts a C<filter_path> parameter | ||||
267 | which will filter the JSON down to only the specified paths. For instance, | ||||
268 | if you are running a search request and only want the C<total> hits and | ||||
269 | the C<_source> field for each hit (without the C<_id>, C<_index> etc), | ||||
270 | you can do: | ||||
271 | |||||
272 | $e->search( | ||||
273 | query => {...}, | ||||
274 | filter_paths => [ 'hits.total', 'hits.hits._source' ] | ||||
275 | ); | ||||
276 | |||||
277 | =head2 Ignore parameter | ||||
278 | |||||
279 | Normally, any HTTP status code outside the 200-299 range will result in | ||||
280 | an error being thrown. To suppress these errors, you can specify which | ||||
281 | status codes to ignore in the C<ignore> parameter. | ||||
282 | |||||
283 | $e->indices->delete( | ||||
284 | index => 'my_index', | ||||
285 | ignore => 404 | ||||
286 | ); | ||||
287 | |||||
288 | This is most useful for | ||||
289 | L<Missing|Search::Elasticsearch::Error/Search::Elasticsearch::Error::Missing> errors, which | ||||
290 | are triggered by a C<404> status code when some requested resource does | ||||
291 | not exist. | ||||
292 | |||||
293 | Multiple error codes can be specified with an array: | ||||
294 | |||||
295 | $e->indices->delete( | ||||
296 | index => 'my_index', | ||||
297 | ignore => [404,409] | ||||
298 | ); | ||||
299 | |||||
300 | =head1 CONFIGURATION | ||||
301 | |||||
302 | =head2 C<bulk_helper_class> | ||||
303 | |||||
304 | The class to use for the L</bulk_helper()> method. Defaults to | ||||
305 | L<Search::Elasticsearch::Client::5_0::Bulk>. | ||||
306 | |||||
307 | =head2 C<scroll_helper_class> | ||||
308 | |||||
309 | The class to use for the L</scroll_helper()> method. Defaults to | ||||
310 | L<Search::Elasticsearch::Client::5_0::Scroll>. | ||||
311 | |||||
312 | =head1 GENERAL METHODS | ||||
313 | |||||
314 | =head2 C<info()> | ||||
315 | |||||
316 | $info = $e->info | ||||
317 | |||||
318 | Returns information about the version of Elasticsearch that the responding node | ||||
319 | is running. | ||||
320 | |||||
321 | =head2 C<ping()> | ||||
322 | |||||
323 | $e->ping | ||||
324 | |||||
325 | Pings a node in the cluster and returns C<1> if it receives a C<200> | ||||
326 | response, otherwise it throws an error. | ||||
327 | |||||
328 | =head2 C<indices()> | ||||
329 | |||||
330 | $indices_client = $e->indices; | ||||
331 | |||||
332 | Returns a L<Search::Elasticsearch::Client::5_0::Direct::Indices> object which can be used | ||||
333 | for managing indices, eg creating, deleting indices, managing mapping, | ||||
334 | index settings etc. | ||||
335 | |||||
336 | =head2 C<ingest()> | ||||
337 | |||||
338 | $ingest_client = $e->ingest; | ||||
339 | |||||
340 | Returns a L<Search::Elasticsearch::Client::5_0::Direct::Ingest> object which can be used | ||||
341 | for managing ingest pipelines. | ||||
342 | |||||
343 | =head2 C<cluster()> | ||||
344 | |||||
345 | $cluster_client = $e->cluster; | ||||
346 | |||||
347 | Returns a L<Search::Elasticsearch::Client::5_0::Direct::Cluster> object which can be used | ||||
348 | for managing the cluster, eg cluster-wide settings and cluster health. | ||||
349 | |||||
350 | =head2 C<nodes()> | ||||
351 | |||||
352 | $node_client = $e->nodes; | ||||
353 | |||||
354 | Returns a L<Search::Elasticsearch::Client::5_0::Direct::Nodes> object which can be used | ||||
355 | to retrieve node info and stats. | ||||
356 | |||||
357 | =head2 C<snapshot()> | ||||
358 | |||||
359 | $snapshot_client = $e->snapshot; | ||||
360 | |||||
361 | Returns a L<Search::Elasticsearch::Client::5_0::Direct::Snapshot> object which | ||||
362 | is used for managing backup repositories and creating and restoring | ||||
363 | snapshots. | ||||
364 | |||||
365 | =head2 C<tasks()> | ||||
366 | |||||
367 | $tasks_client = $e->tasks; | ||||
368 | |||||
369 | Returns a L<Search::Elasticsearch::Client::5_0::Direct::Tasks> object which | ||||
370 | is used for accessing the task management API. | ||||
371 | |||||
372 | =head2 C<cat()> | ||||
373 | |||||
374 | $cat_client = $e->cat; | ||||
375 | |||||
376 | Returns a L<Search::Elasticsearch::Client::5_0::Direct::Cat> object which can be used | ||||
377 | to retrieve simple to read text info for debugging and monitoring an | ||||
378 | Elasticsearch cluster. | ||||
379 | |||||
380 | =head1 DOCUMENT CRUD METHODS | ||||
381 | |||||
382 | These methods allow you to perform create, index, update and delete requests | ||||
383 | for single documents: | ||||
384 | |||||
385 | =head2 C<index()> | ||||
386 | |||||
387 | $response = $e->index( | ||||
388 | index => 'index_name', # required | ||||
389 | type => 'type_name', # required | ||||
390 | id => 'doc_id', # optional, otherwise auto-generated | ||||
391 | |||||
392 | body => { document } # required | ||||
393 | ); | ||||
394 | |||||
395 | The C<index()> method is used to index a new document or to reindex | ||||
396 | an existing document. | ||||
397 | |||||
398 | Query string parameters: | ||||
399 | C<op_type>, | ||||
400 | C<parent>, | ||||
401 | C<pipeline>, | ||||
402 | C<refresh>, | ||||
403 | C<routing>, | ||||
404 | C<timeout>, | ||||
405 | C<timestamp>, | ||||
406 | C<ttl>, | ||||
407 | C<version>, | ||||
408 | C<version_type>, | ||||
409 | C<wait_for_active_shards> | ||||
410 | |||||
411 | See the L<index docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-index_.html> | ||||
412 | for more information. | ||||
413 | |||||
414 | =head2 C<create()> | ||||
415 | |||||
416 | $response = $e->create( | ||||
417 | index => 'index_name', # required | ||||
418 | type => 'type_name', # required | ||||
419 | id => 'doc_id', # required | ||||
420 | |||||
421 | body => { document } # required | ||||
422 | ); | ||||
423 | |||||
424 | The C<create()> method works exactly like the L</index()> method, except | ||||
425 | that it will throw a C<Conflict> error if a document with the same | ||||
426 | C<index>, C<type> and C<id> already exists. | ||||
427 | |||||
428 | Query string parameters: | ||||
429 | C<consistency>, | ||||
430 | C<op_type>, | ||||
431 | C<parent>, | ||||
432 | C<refresh>, | ||||
433 | C<routing>, | ||||
434 | C<timeout>, | ||||
435 | C<timestamp>, | ||||
436 | C<ttl>, | ||||
437 | C<version>, | ||||
438 | C<version_type> | ||||
439 | |||||
440 | See the L<create docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-create.html> | ||||
441 | for more information. | ||||
442 | |||||
443 | =head2 C<get()> | ||||
444 | |||||
445 | $response = $e->get( | ||||
446 | index => 'index_name', # required | ||||
447 | type => 'type_name', # required | ||||
448 | id => 'doc_id', # required | ||||
449 | ); | ||||
450 | |||||
451 | The C<get()> method will retrieve the document with the specified | ||||
452 | C<index>, C<type> and C<id>, or will throw a C<Missing> error. | ||||
453 | |||||
454 | Query string parameters: | ||||
455 | C<_source>, | ||||
456 | C<_source_exclude>, | ||||
457 | C<_source_include>, | ||||
458 | C<parent>, | ||||
459 | C<preference>, | ||||
460 | C<realtime>, | ||||
461 | C<refresh>, | ||||
462 | C<routing>, | ||||
463 | C<stored_fields>, | ||||
464 | C<version>, | ||||
465 | C<version_type> | ||||
466 | |||||
467 | See the L<get docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html> | ||||
468 | for more information. | ||||
469 | |||||
470 | =head2 C<get_source()> | ||||
471 | |||||
472 | $response = $e->get_source( | ||||
473 | index => 'index_name', # required | ||||
474 | type => 'type_name', # required | ||||
475 | id => 'doc_id', # required | ||||
476 | ); | ||||
477 | |||||
478 | The C<get_source()> method works just like the L</get()> method except that | ||||
479 | it returns just the C<_source> field (the value of the C<body> parameter | ||||
480 | in the L</index()> method) instead of returning the C<_source> field | ||||
481 | plus the document metadata, ie the C<_index>, C<_type> etc. | ||||
482 | |||||
483 | Query string parameters: | ||||
484 | C<_source>, | ||||
485 | C<_source_exclude>, | ||||
486 | C<_source_include>, | ||||
487 | C<parent>, | ||||
488 | C<preference>, | ||||
489 | C<realtime>, | ||||
490 | C<refresh>, | ||||
491 | C<routing>, | ||||
492 | C<version>, | ||||
493 | C<version_type> | ||||
494 | |||||
495 | See the L<get_source docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html> | ||||
496 | for more information. | ||||
497 | |||||
498 | =head2 C<exists()> | ||||
499 | |||||
500 | $response = $e->exists( | ||||
501 | index => 'index_name', # required | ||||
502 | type => 'type_name', # required | ||||
503 | id => 'doc_id', # required | ||||
504 | ); | ||||
505 | |||||
506 | The C<exists()> method returns C<1> if a document with the specified | ||||
507 | C<index>, C<type> and C<id> exists, or an empty string if it doesn't. | ||||
508 | |||||
509 | Query string parameters: | ||||
510 | C<parent>, | ||||
511 | C<preference>, | ||||
512 | C<realtime>, | ||||
513 | C<refresh>, | ||||
514 | C<routing> | ||||
515 | |||||
516 | See the L<exists docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-get.html> | ||||
517 | for more information. | ||||
518 | |||||
519 | =head2 C<delete()> | ||||
520 | |||||
521 | $response = $e->delete( | ||||
522 | index => 'index_name', # required | ||||
523 | type => 'type_name', # required | ||||
524 | id => 'doc_id', # required | ||||
525 | ); | ||||
526 | |||||
527 | The C<delete()> method will delete the document with the specified | ||||
528 | C<index>, C<type> and C<id>, or will throw a C<Missing> error. | ||||
529 | |||||
530 | Query string parameters: | ||||
531 | C<parent>, | ||||
532 | C<refresh>, | ||||
533 | C<routing>, | ||||
534 | C<timeout>, | ||||
535 | C<version>, | ||||
536 | C<version_type>, | ||||
537 | C<wait_for_active_shards> | ||||
538 | |||||
539 | See the L<delete docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete.html> | ||||
540 | for more information. | ||||
541 | |||||
542 | =head2 C<update()> | ||||
543 | |||||
544 | $response = $e->update( | ||||
545 | index => 'index_name', # required | ||||
546 | type => 'type_name', # required | ||||
547 | id => 'doc_id', # required | ||||
548 | |||||
549 | body => { update } # required | ||||
550 | ); | ||||
551 | |||||
552 | The C<update()> method updates a document with the corresponding | ||||
553 | C<index>, C<type> and C<id> if it exists. Updates can be performed either by: | ||||
554 | |||||
555 | =over | ||||
556 | |||||
557 | =item * providing a partial document to be merged in to the existing document: | ||||
558 | |||||
559 | $response = $e->update( | ||||
560 | ..., | ||||
561 | body => { | ||||
562 | doc => { new_field => 'new_value'}, | ||||
563 | } | ||||
564 | ); | ||||
565 | |||||
566 | =item * with an inline script: | ||||
567 | |||||
568 | $response = $e->update( | ||||
569 | ..., | ||||
570 | body => { | ||||
571 | script => { | ||||
572 | inline => "ctx._source.counter += incr", | ||||
573 | params => { incr => 5 } | ||||
574 | } | ||||
575 | } | ||||
576 | ); | ||||
577 | |||||
578 | =item * with an indexed script: | ||||
579 | |||||
580 | $response = $e->update( | ||||
581 | ..., | ||||
582 | body => { | ||||
583 | script => { | ||||
584 | id => $id, | ||||
585 | lang => 'painless', | ||||
586 | params => { incr => 5 } | ||||
587 | } | ||||
588 | } | ||||
589 | ); | ||||
590 | |||||
591 | See L<indexed scripts|https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts> | ||||
592 | for more information. | ||||
593 | |||||
594 | =item * with a script stored as a file: | ||||
595 | |||||
596 | $response = $e->update( | ||||
597 | ..., | ||||
598 | body => { | ||||
599 | script => { | ||||
600 | file => 'counter', | ||||
601 | lang => 'painless', | ||||
602 | params => { incr => 5 } | ||||
603 | } | ||||
604 | } | ||||
605 | ); | ||||
606 | |||||
607 | See L<scripting docs|https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html> | ||||
608 | for more information. | ||||
609 | |||||
610 | =back | ||||
611 | |||||
612 | Query string parameters: | ||||
613 | C<_source>, | ||||
614 | C<_source_exclude>, | ||||
615 | C<_source_include>, | ||||
616 | C<fields>, | ||||
617 | C<lang>, | ||||
618 | C<parent>, | ||||
619 | C<refresh>, | ||||
620 | C<retry_on_conflict>, | ||||
621 | C<routing>, | ||||
622 | C<timeout>, | ||||
623 | C<timestamp>, | ||||
624 | C<ttl>, | ||||
625 | C<version>, | ||||
626 | C<version_type>, | ||||
627 | C<wait_for_active_shards> | ||||
628 | |||||
629 | See the L<update docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update.html> | ||||
630 | for more information. | ||||
631 | |||||
632 | =head2 C<termvectors()> | ||||
633 | |||||
634 | $results = $e->termvectors( | ||||
635 | index => $index, # required | ||||
636 | type => $type, # required | ||||
637 | |||||
638 | id => $id, # optional | ||||
639 | body => {...} # optional | ||||
640 | ) | ||||
641 | |||||
642 | The C<termvectors()> method retrieves term and field statistics, positions, | ||||
643 | offsets and payloads for the specified document, assuming that termvectors | ||||
644 | have been enabled. | ||||
645 | |||||
646 | Query string parameters: | ||||
647 | C<field_statistics>, | ||||
648 | C<fields>, | ||||
649 | C<offsets>, | ||||
650 | C<parent>, | ||||
651 | C<payloads>, | ||||
652 | C<positions>, | ||||
653 | C<preference>, | ||||
654 | C<realtime>, | ||||
655 | C<routing>, | ||||
656 | C<term_statistics>, | ||||
657 | C<version>, | ||||
658 | C<version_type> | ||||
659 | |||||
660 | See the L<termvector docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-termvectors.html> | ||||
661 | for more information. | ||||
662 | |||||
663 | =head1 BULK DOCUMENT CRUD METHODS | ||||
664 | |||||
665 | The bulk document CRUD methods are used for running multiple CRUD actions | ||||
666 | within a single request. By reducing the number of network requests | ||||
667 | that need to be made, bulk requests greatly improve performance. | ||||
668 | |||||
669 | =head2 C<bulk()> | ||||
670 | |||||
671 | $response = $e->bulk( | ||||
672 | index => 'index_name', # required if type specified | ||||
673 | type => 'type_name', # optional | ||||
674 | |||||
675 | body => [ actions ] # required | ||||
676 | ); | ||||
677 | |||||
678 | See L<Search::Elasticsearch::Client::5_0::Bulk> and L</bulk_helper()> for a helper module that makes | ||||
679 | bulk indexing simpler to use. | ||||
680 | |||||
681 | The C<bulk()> method can perform multiple L</index()>, L</create()>, | ||||
682 | L</delete()> or L</update()> actions with a single request. The C<body> | ||||
683 | parameter expects an array containing the list of actions to perform. | ||||
684 | |||||
685 | An I<action> consists of an initial metadata hash ref containing the action | ||||
686 | type, plus the associated metadata, eg : | ||||
687 | |||||
688 | { delete => { _index => 'index', _type => 'type', _id => 123 }} | ||||
689 | |||||
690 | The C<index> and C<create> actions then expect a hashref containing | ||||
691 | the document itself: | ||||
692 | |||||
693 | { create => { _index => 'index', _type => 'type', _id => 123 }}, | ||||
694 | { title => "A newly created document" } | ||||
695 | |||||
696 | And the C<update> action expects a hashref containing the update commands, | ||||
697 | eg: | ||||
698 | |||||
699 | { update => { _index => 'index', _type => 'type', _id => 123 }}, | ||||
700 | { script => "ctx._source.counter+=1" } | ||||
701 | |||||
702 | Each action can include the same parameters that you would pass to | ||||
703 | the equivalent L</index()>, L</create()>, L</delete()> or L</update()> | ||||
704 | request, except that C<_index>, C<_type> and C<_id> must be specified with | ||||
705 | the preceding underscore. All other parameters can be specified with or | ||||
706 | without the underscore. | ||||
707 | |||||
708 | For instance: | ||||
709 | |||||
710 | $response = $e->bulk( | ||||
711 | index => 'index_name', # default index name | ||||
712 | type => 'type_name', # default type name | ||||
713 | body => [ | ||||
714 | |||||
715 | # create action | ||||
716 | { create => { | ||||
717 | _index => 'not_the_default_index', | ||||
718 | _type => 'not_the_default_type', | ||||
719 | _id => 123 | ||||
720 | }}, | ||||
721 | { title => 'Foo' }, | ||||
722 | |||||
723 | # index action | ||||
724 | { index => { _id => 124 }}, | ||||
725 | { title => 'Foo' }, | ||||
726 | |||||
727 | # delete action | ||||
728 | { delete => { _id => 125 }}, | ||||
729 | |||||
730 | # update action | ||||
731 | { update => { _id => 126 }}, | ||||
732 | { script => "ctx._source.counter+1" } | ||||
733 | ] | ||||
734 | ); | ||||
735 | |||||
736 | Each action is performed separately. One failed action will not | ||||
737 | cause the others to fail as well. | ||||
738 | |||||
739 | Query string parameters: | ||||
740 | C<_source>, | ||||
741 | C<_source_exclude>, | ||||
742 | C<_source_include>, | ||||
743 | C<fields>, | ||||
744 | C<pipeline>, | ||||
745 | C<refresh>, | ||||
746 | C<routing>, | ||||
747 | C<timeout>, | ||||
748 | C<wait_for_active_shards> | ||||
749 | |||||
750 | See the L<bulk docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-bulk.html> | ||||
751 | for more information. | ||||
752 | |||||
753 | =head2 C<bulk_helper()> | ||||
754 | |||||
755 | $bulk_helper = $e->bulk_helper( @args ); | ||||
756 | |||||
757 | Returns a new instance of the class specified in the L</bulk_helper_class>, | ||||
758 | which defaults to L<Search::Elasticsearch::Client::5_0::Bulk>. | ||||
759 | |||||
760 | =head2 C<mget()> | ||||
761 | |||||
762 | $results = $e->mget( | ||||
763 | index => 'default_index', # optional, required when type specified | ||||
764 | type => 'default_type', # optional | ||||
765 | |||||
766 | body => { docs or ids } # required | ||||
767 | ); | ||||
768 | |||||
769 | The C<mget()> method will retrieve multiple documents with a single request. | ||||
770 | The C<body> consists of an array of documents to retrieve: | ||||
771 | |||||
772 | $results = $e->mget( | ||||
773 | index => 'default_index', | ||||
774 | type => 'default_type', | ||||
775 | body => { | ||||
776 | docs => [ | ||||
777 | { _id => 1}, | ||||
778 | { _id => 2, _type => 'not_the_default_type' } | ||||
779 | ] | ||||
780 | } | ||||
781 | ); | ||||
782 | |||||
783 | You can also pass any of the other parameters that the L</get()> request | ||||
784 | accepts. | ||||
785 | |||||
786 | If you have specified an C<index> and C<type>, you can just include the | ||||
787 | C<ids> of the documents to retrieve: | ||||
788 | |||||
789 | $results = $e->mget( | ||||
790 | index => 'default_index', | ||||
791 | type => 'default_type', | ||||
792 | body => { | ||||
793 | ids => [ 1, 2, 3] | ||||
794 | } | ||||
795 | ); | ||||
796 | |||||
797 | Query string parameters: | ||||
798 | C<_source>, | ||||
799 | C<_source_exclude>, | ||||
800 | C<_source_include>, | ||||
801 | C<preference>, | ||||
802 | C<realtime>, | ||||
803 | C<refresh>, | ||||
804 | C<stored_fields> | ||||
805 | |||||
806 | See the L<mget docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-get.html> | ||||
807 | for more information. | ||||
808 | |||||
809 | =head2 C<mtermvectors()> | ||||
810 | |||||
811 | $results = $e->mtermvectors( | ||||
812 | index => $index, # required if type specified | ||||
813 | type => $type, # optional | ||||
814 | |||||
815 | body => { } # optional | ||||
816 | ) | ||||
817 | |||||
818 | Runs multiple L</termvector()> requests in a single request, eg: | ||||
819 | |||||
820 | $results = $e->mtermvectors( | ||||
821 | index => 'test', | ||||
822 | body => { | ||||
823 | docs => [ | ||||
824 | { _type => 'test', _id => 1, fields => ['text'] }, | ||||
825 | { _type => 'test', _id => 2, payloads => 1 }, | ||||
826 | ] | ||||
827 | } | ||||
828 | ); | ||||
829 | |||||
830 | Query string parameters: | ||||
831 | C<field_statistics>, | ||||
832 | C<fields>, | ||||
833 | C<ids>, | ||||
834 | C<offsets>, | ||||
835 | C<parent>, | ||||
836 | C<payloads>, | ||||
837 | C<positions>, | ||||
838 | C<preference>, | ||||
839 | C<realtime>, | ||||
840 | C<routing>, | ||||
841 | C<term_statistics>, | ||||
842 | C<version>, | ||||
843 | C<version_type> | ||||
844 | |||||
845 | See the L<mtermvectors docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/docs-multi-termvectors.html> | ||||
846 | for more information. | ||||
847 | |||||
848 | =head1 SEARCH METHODS | ||||
849 | |||||
850 | The search methods are used for querying documents in one, more or all indices | ||||
851 | and of one, more or all types: | ||||
852 | |||||
853 | =head2 C<search()> | ||||
854 | |||||
855 | $results = $e->search( | ||||
856 | index => 'index' | \@indices, # optional | ||||
857 | type => 'type' | \@types, # optional | ||||
858 | |||||
859 | body => { search params } # optional | ||||
860 | ); | ||||
861 | |||||
862 | The C<search()> method searches for matching documents in one or more | ||||
863 | indices. It is just as easy to search a single index as it is to search | ||||
864 | all the indices in your cluster. It can also return | ||||
865 | L<aggregations|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html> | ||||
866 | L<highlighted snippets|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-highlighting.html> | ||||
867 | and L<did-you-mean|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-phrase.html> | ||||
868 | or L<search-as-you-type|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-completion.html> | ||||
869 | suggestions. | ||||
870 | |||||
871 | The I<lite> L<version of search|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-uri-request.html> | ||||
872 | allows you to specify a query string in the C<q> parameter, using the | ||||
873 | Lucene query string syntax: | ||||
874 | |||||
875 | $results = $e->search( q => 'title:(elasticsearch clients)'); | ||||
876 | |||||
877 | However, the preferred way to search is by using the | ||||
878 | L<Query DSL|http://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl.html> | ||||
879 | to create a query, and passing that C<query> in the | ||||
880 | L<request body|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html>: | ||||
881 | |||||
882 | $results = $e->search( | ||||
883 | body => { | ||||
884 | query => { | ||||
885 | match => { title => 'Elasticsearch clients'} | ||||
886 | } | ||||
887 | } | ||||
888 | ); | ||||
889 | |||||
890 | Query string parameters: | ||||
891 | C<_source>, | ||||
892 | C<_source_exclude>, | ||||
893 | C<_source_include>, | ||||
894 | C<allow_no_indices>, | ||||
895 | C<analyze_wildcard>, | ||||
896 | C<analyzer>, | ||||
897 | C<default_operator>, | ||||
898 | C<df>, | ||||
899 | C<docvalue_fields>, | ||||
900 | C<expand_wildcards>, | ||||
901 | C<explain>, | ||||
902 | C<fielddata_fields>, | ||||
903 | C<from>, | ||||
904 | C<ignore_unavailable>, | ||||
905 | C<lenient>, | ||||
906 | C<lowercase_expanded_terms>, | ||||
907 | C<preference>, | ||||
908 | C<q>, | ||||
909 | C<request_cache>, | ||||
910 | C<routing>, | ||||
911 | C<scroll>, | ||||
912 | C<search_type>, | ||||
913 | C<size>, | ||||
914 | C<sort>, | ||||
915 | C<stats>, | ||||
916 | C<stored_fields>, | ||||
917 | C<suggest_field>, | ||||
918 | C<suggest_mode>, | ||||
919 | C<suggest_size>, | ||||
920 | C<suggest_text>, | ||||
921 | C<terminate_after>, | ||||
922 | C<timeout>, | ||||
923 | C<track_scores>, | ||||
924 | C<version> | ||||
925 | |||||
926 | See the L<search reference|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html> | ||||
927 | for more information. | ||||
928 | |||||
929 | Also see L<Search::Elasticsearch::Transport/send_get_body_as>. | ||||
930 | |||||
931 | =head2 C<count()> | ||||
932 | |||||
933 | $results = $e->count( | ||||
934 | index => 'index' | \@indices, # optional | ||||
935 | type => 'type' | \@types, # optional | ||||
936 | |||||
937 | body => { query } # optional | ||||
938 | ) | ||||
939 | |||||
940 | The C<count()> method returns the total count of all documents matching the | ||||
941 | query: | ||||
942 | |||||
943 | $results = $e->count( | ||||
944 | body => { | ||||
945 | query => { | ||||
946 | match => { title => 'Elasticsearch clients' } | ||||
947 | } | ||||
948 | } | ||||
949 | ); | ||||
950 | |||||
951 | Query string parameters: | ||||
952 | C<allow_no_indices>, | ||||
953 | C<analyze_wildcard>, | ||||
954 | C<analyzer>, | ||||
955 | C<default_operator>, | ||||
956 | C<df>, | ||||
957 | C<expand_wildcards>, | ||||
958 | C<ignore_unavailable>, | ||||
959 | C<lenient>, | ||||
960 | C<lowercase_expanded_terms> | ||||
961 | C<min_score>, | ||||
962 | C<preference>, | ||||
963 | C<q>, | ||||
964 | C<routing> | ||||
965 | |||||
966 | See the L<count docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-count.html> | ||||
967 | for more information. | ||||
968 | |||||
969 | =head2 C<search_template()> | ||||
970 | |||||
971 | $results = $e->search_template( | ||||
972 | index => 'index' | \@indices, # optional | ||||
973 | type => 'type' | \@types, # optional | ||||
974 | |||||
975 | body => { search params } # optional | ||||
976 | ); | ||||
977 | |||||
978 | Perform a search by specifying a template (either predefined or defined | ||||
979 | within the C<body>) and parameters to use with the template, eg: | ||||
980 | |||||
981 | $results = $e->search_template( | ||||
982 | body => { | ||||
983 | inline => { | ||||
984 | query => { | ||||
985 | match => { | ||||
986 | "{{my_field}}" => "{{my_value}}" | ||||
987 | } | ||||
988 | }, | ||||
989 | size => "{{my_size}}" | ||||
990 | }, | ||||
991 | params => { | ||||
992 | my_field => 'foo', | ||||
993 | my_value => 'bar', | ||||
994 | my_size => 5 | ||||
995 | } | ||||
996 | } | ||||
997 | ); | ||||
998 | |||||
999 | See the L<search template docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html> | ||||
1000 | for more information. | ||||
1001 | |||||
1002 | Query string parameters: | ||||
1003 | C<allow_no_indices>, | ||||
1004 | C<expand_wildcards>, | ||||
1005 | C<explain>, | ||||
1006 | C<ignore_unavailable>, | ||||
1007 | C<preference>, | ||||
1008 | C<profile>, | ||||
1009 | C<scroll>, | ||||
1010 | C<search_type> | ||||
1011 | |||||
1012 | =head2 C<render_search_template()> | ||||
1013 | |||||
1014 | $response = $e->render_search_template( | ||||
1015 | id => 'id', # optional | ||||
1016 | body => { template } # optional | ||||
1017 | ); | ||||
1018 | |||||
1019 | Renders the template, filling in the passed-in parameters and returns the resulting JSON, eg: | ||||
1020 | |||||
1021 | $results = $e->render_search_template( | ||||
1022 | body => { | ||||
1023 | inline => { | ||||
1024 | query => { | ||||
1025 | match => { | ||||
1026 | "{{my_field}}" => "{{my_value}}" | ||||
1027 | } | ||||
1028 | }, | ||||
1029 | size => "{{my_size}}" | ||||
1030 | }, | ||||
1031 | params => { | ||||
1032 | my_field => 'foo', | ||||
1033 | my_value => 'bar', | ||||
1034 | my_size => 5 | ||||
1035 | } | ||||
1036 | } | ||||
1037 | ); | ||||
1038 | |||||
1039 | See the L<search template docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html> | ||||
1040 | for more information. | ||||
1041 | |||||
1042 | =head2 C<scroll()> | ||||
1043 | |||||
1044 | $results = $e->scroll( | ||||
1045 | scroll => '1m', | ||||
1046 | scroll_id => $id | ||||
1047 | ); | ||||
1048 | |||||
1049 | When a L</search()> has been performed with the | ||||
1050 | C<scroll> parameter, the C<scroll()> | ||||
1051 | method allows you to keep pulling more results until the results | ||||
1052 | are exhausted. | ||||
1053 | |||||
1054 | See L</scroll_helper()> and L<Search::Elasticsearch::Client::5_0::Scroll> for a helper utility | ||||
1055 | which makes managing scroll requests much easier. | ||||
1056 | |||||
1057 | Query string parameters: | ||||
1058 | C<scroll>, | ||||
1059 | C<scroll_id> | ||||
1060 | |||||
1061 | See the L<scroll docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-scroll.html> | ||||
1062 | and the L<search_type docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search.html/search-request-search-type.html> | ||||
1063 | for more information. | ||||
1064 | |||||
1065 | =head2 C<clear_scroll()> | ||||
1066 | |||||
1067 | $response = $e->clear_scroll( | ||||
1068 | scroll_id => $id | \@ids # required | ||||
1069 | ); | ||||
1070 | |||||
1071 | Or | ||||
1072 | |||||
1073 | $response = $e->clear_scroll( | ||||
1074 | body => $id | ||||
1075 | ); | ||||
1076 | |||||
1077 | The C<clear_scroll()> method can clear unfinished scroll requests, freeing | ||||
1078 | up resources on the server. | ||||
1079 | |||||
1080 | =head2 C<scroll_helper()> | ||||
1081 | |||||
1082 | $scroll_helper = $e->scroll_helper( @args ); | ||||
1083 | |||||
1084 | Returns a new instance of the class specified in the L</scroll_helper_class>, | ||||
1085 | which defaults to L<Search::Elasticsearch::Client::5_0::Scroll>. | ||||
1086 | |||||
1087 | =head2 C<msearch()> | ||||
1088 | |||||
1089 | $results = $e->msearch( | ||||
1090 | index => 'default_index' | \@indices, # optional | ||||
1091 | type => 'default_type' | \@types, # optional | ||||
1092 | |||||
1093 | body => [ searches ] # required | ||||
1094 | ); | ||||
1095 | |||||
1096 | The C<msearch()> method allows you to perform multiple searches in a single | ||||
1097 | request. Similar to the L</bulk()> request, each search request in the | ||||
1098 | C<body> consists of two hashes: the metadata hash then the search request | ||||
1099 | hash (the same data that you'd specify in the C<body> of a L</search()> | ||||
1100 | request). For instance: | ||||
1101 | |||||
1102 | $results = $e->msearch( | ||||
1103 | index => 'default_index', | ||||
1104 | type => ['default_type_1', 'default_type_2'], | ||||
1105 | body => [ | ||||
1106 | # uses defaults | ||||
1107 | {}, | ||||
1108 | { query => { match_all => {} }}, | ||||
1109 | |||||
1110 | # uses a custom index | ||||
1111 | { index => 'not_the_default_index' }, | ||||
1112 | { query => { match_all => {} }} | ||||
1113 | ] | ||||
1114 | ); | ||||
1115 | |||||
1116 | Query string parameters: | ||||
1117 | C<max_concurrent_searches>, | ||||
1118 | C<search_type> | ||||
1119 | |||||
1120 | See the L<msearch docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-multi-search.html> | ||||
1121 | for more information. | ||||
1122 | |||||
1123 | =head2 C<msearch_template()> | ||||
1124 | |||||
1125 | $results = $e->msearch_template( | ||||
1126 | index => 'default_index' | \@indices, # optional | ||||
1127 | type => 'default_type' | \@types, # optional | ||||
1128 | |||||
1129 | body => [ search_templates ] # required | ||||
1130 | ); | ||||
1131 | |||||
1132 | The C<msearch_template()> method allows you to perform multiple searches in a single | ||||
1133 | request using search templates. Similar to the L</bulk()> request, each search | ||||
1134 | request in the C<body> consists of two hashes: the metadata hash then the search request | ||||
1135 | hash (the same data that you'd specify in the C<body> of a L</search()> | ||||
1136 | request). For instance: | ||||
1137 | |||||
1138 | $results = $e->msearch( | ||||
1139 | index => 'default_index', | ||||
1140 | type => ['default_type_1', 'default_type_2'], | ||||
1141 | body => [ | ||||
1142 | # uses defaults | ||||
1143 | {}, | ||||
1144 | { inline => { query => { match => { user => "{{user}}" }}} params => { user => 'joe' }}, | ||||
1145 | |||||
1146 | # uses a custom index | ||||
1147 | { index => 'not_the_default_index' }, | ||||
1148 | { inline => { query => { match => { user => "{{user}}" }}} params => { user => 'joe' }}, | ||||
1149 | ] | ||||
1150 | ); | ||||
1151 | |||||
1152 | Query string parameters: | ||||
1153 | C<search_type> | ||||
1154 | |||||
1155 | See the L<msearch-template docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/multi-search-template.html> | ||||
1156 | for more information. | ||||
1157 | |||||
1158 | =head2 C<explain()> | ||||
1159 | |||||
1160 | $response = $e->explain( | ||||
1161 | index => 'my_index', # required | ||||
1162 | type => 'my_type', # required | ||||
1163 | id => 123, # required | ||||
1164 | |||||
1165 | body => { search } # required | ||||
1166 | ); | ||||
1167 | |||||
1168 | The C<explain()> method explains why the specified document did or | ||||
1169 | did not match a query, and how the relevance score was calculated. | ||||
1170 | For instance: | ||||
1171 | |||||
1172 | $response = $e->explain( | ||||
1173 | index => 'my_index', | ||||
1174 | type => 'my_type', | ||||
1175 | id => 123, | ||||
1176 | body => { | ||||
1177 | query => { | ||||
1178 | match => { title => 'Elasticsearch clients' } | ||||
1179 | } | ||||
1180 | } | ||||
1181 | ); | ||||
1182 | |||||
1183 | Query string parameters: | ||||
1184 | C<_source>, | ||||
1185 | C<_source_exclude>, | ||||
1186 | C<_source_include>, | ||||
1187 | C<analyze_wildcard>, | ||||
1188 | C<analyzer>, | ||||
1189 | C<default_operator>, | ||||
1190 | C<df>, | ||||
1191 | C<lenient>, | ||||
1192 | C<lowercase_expanded_terms>, | ||||
1193 | C<parent>, | ||||
1194 | C<preference>, | ||||
1195 | C<q>, | ||||
1196 | C<routing>, | ||||
1197 | C<stored_fields> | ||||
1198 | |||||
1199 | See the L<explain docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-explain.html> | ||||
1200 | for more information. | ||||
1201 | |||||
1202 | =head2 C<field_stats()> | ||||
1203 | |||||
1204 | $response = $e->field_stats( | ||||
1205 | index => 'index' | \@indices, # optional | ||||
1206 | fields => 'field' | \@fields, # optional | ||||
1207 | level => 'cluster' | 'indices', # optional | ||||
1208 | body => { filters } # optional | ||||
1209 | ); | ||||
1210 | |||||
1211 | The C<field-stats> API returns statistical properties of a field | ||||
1212 | (such as min and max values) without executing a search. | ||||
1213 | |||||
1214 | Query string parameters: | ||||
1215 | C<allow_no_indices>, | ||||
1216 | C<expand_wildcards>, | ||||
1217 | C<fields>, | ||||
1218 | C<ignore_unavailable>, | ||||
1219 | C<level> | ||||
1220 | |||||
1221 | See the L<field-stats docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-field-stats.html> | ||||
1222 | for more information. | ||||
1223 | |||||
1224 | =head2 C<search_shards()> | ||||
1225 | |||||
1226 | $response = $e->search_shards( | ||||
1227 | index => 'index' | \@indices, # optional | ||||
1228 | type => 'type' | \@types, # optional | ||||
1229 | ) | ||||
1230 | |||||
1231 | The C<search_shards()> method returns information about which shards on | ||||
1232 | which nodes will execute a search request. | ||||
1233 | |||||
1234 | Query string parameters: | ||||
1235 | C<allow_no_indices>, | ||||
1236 | C<expand_wildcards>, | ||||
1237 | C<ignore_unavailable>, | ||||
1238 | C<local>, | ||||
1239 | C<preference>, | ||||
1240 | C<routing> | ||||
1241 | |||||
1242 | See the L<search-shards docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-shards.html> | ||||
1243 | for more information. | ||||
1244 | |||||
1245 | =head1 CRUD-BY-QUERY METHODS | ||||
1246 | |||||
1247 | =head2 C<delete_by_query()> | ||||
1248 | |||||
1249 | $response = $e->delete_by_query( | ||||
1250 | index => 'index' | \@indices, # optional | ||||
1251 | type => 'type' | \@types, # optional, | ||||
1252 | body => { delete-by-query } # required | ||||
1253 | ); | ||||
1254 | |||||
1255 | The C<delete_by_query()> method deletes all documents which match the specified query. | ||||
1256 | |||||
1257 | Query string parameters: | ||||
1258 | C<_source>, | ||||
1259 | C<_source_exclude>, | ||||
1260 | C<_source_include>, | ||||
1261 | C<allow_no_indices>, | ||||
1262 | C<analyze_wildcard>, | ||||
1263 | C<analyzer>, | ||||
1264 | C<conflicts>, | ||||
1265 | C<default_operator>, | ||||
1266 | C<df>, | ||||
1267 | C<expand_wildcards>, | ||||
1268 | C<from>, | ||||
1269 | C<ignore_unavailable>, | ||||
1270 | C<lenient>, | ||||
1271 | C<lowercase_expanded_terms>, | ||||
1272 | C<preference>, | ||||
1273 | C<q>, | ||||
1274 | C<refresh>, | ||||
1275 | C<request_cache>, | ||||
1276 | C<requests_per_second>, | ||||
1277 | C<routing>, | ||||
1278 | C<scroll>, | ||||
1279 | C<scroll_size>, | ||||
1280 | C<search_timeout>, | ||||
1281 | C<search_type>, | ||||
1282 | C<size>, | ||||
1283 | C<sort>, | ||||
1284 | C<stats>, | ||||
1285 | C<terminate_after>, | ||||
1286 | C<version>, | ||||
1287 | C<timeout>, | ||||
1288 | C<wait_for_active_shards>, | ||||
1289 | C<wait_for_completion> | ||||
1290 | |||||
1291 | See the L<delete-by-query docs|https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-delete-by-query.html> | ||||
1292 | for more information. | ||||
1293 | |||||
1294 | =head2 C<reindex()> | ||||
1295 | |||||
1296 | $response = $e->reindex( | ||||
1297 | body => { reindex } # required | ||||
1298 | ); | ||||
1299 | |||||
1300 | The C<reindex()> API is used to index documents from one index or multiple indices | ||||
1301 | to a new index. | ||||
1302 | |||||
1303 | Query string parameters: | ||||
1304 | C<refresh>, | ||||
1305 | C<requests_per_second>, | ||||
1306 | C<timeout>, | ||||
1307 | C<wait_for_active_shards>, | ||||
1308 | C<wait_for_completion> | ||||
1309 | |||||
1310 | See the L<reindex docs|https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html> | ||||
1311 | for more information. | ||||
1312 | |||||
1313 | =head2 C<update_by_query()> | ||||
1314 | |||||
1315 | $response = $e->update_by_query( | ||||
1316 | index => 'index' | \@indices, # optional | ||||
1317 | type => 'type' | \@types, # optional, | ||||
1318 | body => { update-by-query } # optional | ||||
1319 | ); | ||||
1320 | |||||
1321 | The C<update_by_query()> API is used to bulk update documents from one index or | ||||
1322 | multiple indices using a script. | ||||
1323 | |||||
1324 | Query string parameters: | ||||
1325 | C<_source>, | ||||
1326 | C<_source_exclude>, | ||||
1327 | C<_source_include>, | ||||
1328 | C<allow_no_indices>, | ||||
1329 | C<analyze_wildcard>, | ||||
1330 | C<analyzer>, | ||||
1331 | C<conflicts>, | ||||
1332 | C<default_operator>, | ||||
1333 | C<df>, | ||||
1334 | C<expand_wildcards>, | ||||
1335 | C<from>, | ||||
1336 | C<ignore_unavailable>, | ||||
1337 | C<lenient>, | ||||
1338 | C<lowercase_expanded_terms>, | ||||
1339 | C<pipeline>, | ||||
1340 | C<preference>, | ||||
1341 | C<q>, | ||||
1342 | C<refresh>, | ||||
1343 | C<request_cache>, | ||||
1344 | C<requests_per_second>, | ||||
1345 | C<routing>, | ||||
1346 | C<scroll>, | ||||
1347 | C<scroll_size>, | ||||
1348 | C<search_timeout>, | ||||
1349 | C<search_type>, | ||||
1350 | C<size>, | ||||
1351 | C<sort>, | ||||
1352 | C<stats>, | ||||
1353 | C<terminate_after>, | ||||
1354 | C<timeout>, | ||||
1355 | C<version>, | ||||
1356 | C<version_type>, | ||||
1357 | C<wait_for_active_shards>, | ||||
1358 | C<wait_for_completion> | ||||
1359 | |||||
1360 | See the L<update_by_query docs|https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-update-by-query.html> | ||||
1361 | for more information. | ||||
1362 | |||||
1363 | =head2 C<reindex_rethrottle> | ||||
1364 | |||||
1365 | $response = $e->reindex_rethrottle( | ||||
1366 | task_id => 'task_id', # required | ||||
1367 | requests_per_second => $req_per_second | ||||
1368 | ); | ||||
1369 | |||||
1370 | The C<reindex_rethrottle()> API is used to dynamically update the throtting | ||||
1371 | of an existing reindex request, identified by C<task_id>. | ||||
1372 | |||||
1373 | Query string parameters: | ||||
1374 | C<requests_per_second> | ||||
1375 | |||||
1376 | See the L<reindex docs|https://www.elastic.co/guide/en/elasticsearch/reference/current/docs-reindex.html> | ||||
1377 | for more information. | ||||
1378 | |||||
1379 | =head1 PERCOLATION METHODS | ||||
1380 | |||||
1381 | =head2 C<percolate()> | ||||
1382 | |||||
1383 | $results = $e->percolate( | ||||
1384 | index => 'my_index', # required | ||||
1385 | type => 'my_type', # required | ||||
1386 | |||||
1387 | body => { percolation } # required | ||||
1388 | ); | ||||
1389 | |||||
1390 | Percolation is search inverted: instead of finding docs which match a | ||||
1391 | particular query, it finds queries which match a particular document, eg | ||||
1392 | for I<alert-me-when> functionality. | ||||
1393 | |||||
1394 | The C<percolate()> method runs a percolation request to find the | ||||
1395 | queries matching a particular document. In the C<body> you should pass the | ||||
1396 | C<_source> field of the document under the C<doc> key: | ||||
1397 | |||||
1398 | $results = $e->percolate( | ||||
1399 | index => 'my_index', | ||||
1400 | type => 'my_type', | ||||
1401 | body => { | ||||
1402 | doc => { | ||||
1403 | title => 'Elasticsearch rocks' | ||||
1404 | } | ||||
1405 | } | ||||
1406 | ); | ||||
1407 | |||||
1408 | Query string parameters: | ||||
1409 | C<allow_no_indices>, | ||||
1410 | C<expand_wildcards>, | ||||
1411 | C<ignore_unavailable>, | ||||
1412 | C<percolate_format>, | ||||
1413 | C<percolate_index>, | ||||
1414 | C<percolate_preference>, | ||||
1415 | C<percolate_routing>, | ||||
1416 | C<percolate_type>, | ||||
1417 | C<preference>, | ||||
1418 | C<routing>, | ||||
1419 | C<version>, | ||||
1420 | C<version_type> | ||||
1421 | |||||
1422 | See the L<percolate docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-percolate.html> | ||||
1423 | for more information. | ||||
1424 | |||||
1425 | =head2 C<count_percolate()> | ||||
1426 | |||||
1427 | $results = $e->count_percolate( | ||||
1428 | index => 'my_index', # required | ||||
1429 | type => 'my_type', # required | ||||
1430 | |||||
1431 | body => { percolation } # required | ||||
1432 | ); | ||||
1433 | |||||
1434 | The L</count_percolate()> request works just like the L</percolate()> | ||||
1435 | request except that it returns a count of all matching queries, instead | ||||
1436 | of the queries themselves. | ||||
1437 | |||||
1438 | $results = $e->count_percolate( | ||||
1439 | index => 'my_index', | ||||
1440 | type => 'my_type', | ||||
1441 | body => { | ||||
1442 | doc => { | ||||
1443 | title => 'Elasticsearch rocks' | ||||
1444 | } | ||||
1445 | } | ||||
1446 | ); | ||||
1447 | |||||
1448 | Query string parameters: | ||||
1449 | C<allow_no_indices>, | ||||
1450 | C<expand_wildcards>, | ||||
1451 | C<ignore_unavailable>, | ||||
1452 | C<percolate_index>, | ||||
1453 | C<percolate_type>, | ||||
1454 | C<preference>, | ||||
1455 | C<routing>, | ||||
1456 | C<version>, | ||||
1457 | C<version_type> | ||||
1458 | |||||
1459 | See the L<percolate docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-percolate.html> | ||||
1460 | for more information. | ||||
1461 | |||||
1462 | =head2 C<mpercolate()> | ||||
1463 | |||||
1464 | $results = $e->mpercolate( | ||||
1465 | index => 'my_index', # required if type | ||||
1466 | type => 'my_type', # optional | ||||
1467 | |||||
1468 | body => [ percolation requests ] # required | ||||
1469 | ); | ||||
1470 | |||||
1471 | Multi-percolation allows multiple L</percolate()> requests to be run | ||||
1472 | in a single request. | ||||
1473 | |||||
1474 | $results = $e->mpercolate( | ||||
1475 | index => 'my_index', | ||||
1476 | type => 'my_type', | ||||
1477 | body => [ | ||||
1478 | # first request | ||||
1479 | { percolate => { | ||||
1480 | index => 'twitter', | ||||
1481 | type => 'tweet' | ||||
1482 | }}, | ||||
1483 | { doc => {message => 'some_text' }}, | ||||
1484 | |||||
1485 | # second request | ||||
1486 | { percolate => { | ||||
1487 | index => 'twitter', | ||||
1488 | type => 'tweet', | ||||
1489 | id => 1 | ||||
1490 | }}, | ||||
1491 | {}, | ||||
1492 | ] | ||||
1493 | ); | ||||
1494 | |||||
1495 | Query string parameters: | ||||
1496 | C<allow_no_indices>, | ||||
1497 | C<expand_wildcards>, | ||||
1498 | C<ignore_unavailable> | ||||
1499 | |||||
1500 | See the L<mpercolate docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-percolate.html> | ||||
1501 | for more information. | ||||
1502 | |||||
1503 | =head2 C<suggest()> | ||||
1504 | |||||
1505 | $results = $e->suggest( | ||||
1506 | index => 'index' | \@indices, # optional | ||||
1507 | |||||
1508 | body => { suggest request } # required | ||||
1509 | ); | ||||
1510 | |||||
1511 | The C<suggest()> method is used to run | ||||
1512 | L<did-you-mean|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesteres-phrase.html> | ||||
1513 | or L<search-as-you-type|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-suggesters-completion.html> | ||||
1514 | suggestion requests, which can also be run as part of a L</search()> request. | ||||
1515 | |||||
1516 | $results = $e->suggest( | ||||
1517 | index => 'my_index', | ||||
1518 | body => { | ||||
1519 | my_suggestions => { | ||||
1520 | phrase => { | ||||
1521 | text => 'johnny walker', | ||||
1522 | field => 'title' | ||||
1523 | } | ||||
1524 | } | ||||
1525 | } | ||||
1526 | ); | ||||
1527 | |||||
1528 | Query string parameters: | ||||
1529 | C<allow_no_indices>, | ||||
1530 | C<expand_wildcards>, | ||||
1531 | C<ignore_unavailable>, | ||||
1532 | C<preference>, | ||||
1533 | C<routing> | ||||
1534 | |||||
1535 | =head1 INDEXED SCRIPT METHODS | ||||
1536 | |||||
1537 | Elasticsearch allows you to store scripts in the cluster state | ||||
1538 | and reference them by id. The methods to manage indexed scripts are as follows: | ||||
1539 | |||||
1540 | =head2 C<put_script()> | ||||
1541 | |||||
1542 | $result = $e->put_script( | ||||
1543 | lang => 'lang', # required | ||||
1544 | id => 'id', # required | ||||
1545 | body => { script } # required | ||||
1546 | ); | ||||
1547 | |||||
1548 | The C<put_script()> method is used to store a script in the cluster state. For instance: | ||||
1549 | |||||
1550 | $result = $e->put_scripts( | ||||
1551 | lang => 'painless', | ||||
1552 | id => 'hello_world', | ||||
1553 | body => { | ||||
1554 | script => q(return "hello world"); | ||||
1555 | } | ||||
1556 | ); | ||||
1557 | |||||
1558 | Query string parameters: None | ||||
1559 | |||||
1560 | See the L<indexed scripts docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts> for more. | ||||
1561 | |||||
1562 | =head2 C<get_script()> | ||||
1563 | |||||
1564 | $script = $e->get_script( | ||||
1565 | lang => 'lang', # required | ||||
1566 | id => 'id', # required | ||||
1567 | ); | ||||
1568 | |||||
1569 | Retrieve the indexed script from the cluster state. | ||||
1570 | |||||
1571 | Query string parameters: None | ||||
1572 | |||||
1573 | See the L<indexed scripts docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts> for more. | ||||
1574 | |||||
1575 | =head2 C<delete_script()> | ||||
1576 | |||||
1577 | $script = $e->delete_script( | ||||
1578 | lang => 'lang', # required | ||||
1579 | id => 'id', # required | ||||
1580 | ); | ||||
1581 | |||||
1582 | Delete the indexed script from the cluster state. | ||||
1583 | |||||
1584 | Query string parameters: None | ||||
1585 | |||||
1586 | See the L<indexed scripts docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/modules-scripting.html#_indexed_scripts> for more. | ||||
1587 | |||||
1588 | =head1 INDEXED SEARCH TEMPLATE METHODS | ||||
1589 | |||||
1590 | Mustache templates can be used to create search requests. These templates can | ||||
1591 | be stored in the cluster state and retrieved by ID. The methods to | ||||
1592 | manage indexed scripts are as follows: | ||||
1593 | |||||
1594 | =head2 C<put_template()> | ||||
1595 | |||||
1596 | $result = $e->put_template( | ||||
1597 | id => 'id', # required | ||||
1598 | body => { template } || "template" # required | ||||
1599 | ); | ||||
1600 | |||||
1601 | The C<put_template()> method is used to store a template in the cluster state. | ||||
1602 | For instance: | ||||
1603 | |||||
1604 | $result = $e->put_template( | ||||
1605 | id => 'hello_world', | ||||
1606 | body => { | ||||
1607 | template => { | ||||
1608 | query => { | ||||
1609 | match => { | ||||
1610 | title => "hello world" | ||||
1611 | } | ||||
1612 | } | ||||
1613 | } | ||||
1614 | } | ||||
1615 | ); | ||||
1616 | |||||
1617 | Query string parameters: None | ||||
1618 | |||||
1619 | See the L<indexed search template docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html#_pre_registered_template> for more. | ||||
1620 | |||||
1621 | =head2 C<get_template()> | ||||
1622 | |||||
1623 | $script = $e->get_template( | ||||
1624 | id => 'id', # required | ||||
1625 | ); | ||||
1626 | |||||
1627 | Retrieve the indexed template from the cluster state. | ||||
1628 | |||||
1629 | Query string parameters: None | ||||
1630 | |||||
1631 | See the L<indexed search template docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html#_pre_registered_template> for more. | ||||
1632 | |||||
1633 | =head2 C<delete_template()> | ||||
1634 | |||||
1635 | $script = $e->delete_template( | ||||
1636 | id => 'id', # required | ||||
1637 | ); | ||||
1638 | |||||
1639 | Delete the indexed template from the cluster state. | ||||
1640 | |||||
1641 | Query string parameters: None | ||||
1642 | |||||
1643 | See the L<indexed search template docs|http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html#_pre_registered_template> for more. | ||||
1644 | |||||
1645 | =head1 AUTHOR | ||||
1646 | |||||
1647 | Clinton Gormley <drtech@cpan.org> | ||||
1648 | |||||
1649 | =head1 COPYRIGHT AND LICENSE | ||||
1650 | |||||
1651 | This software is Copyright (c) 2016 by Elasticsearch BV. | ||||
1652 | |||||
1653 | This is free software, licensed under: | ||||
1654 | |||||
1655 | The Apache License, Version 2.0, January 2004 | ||||
1656 | |||||
1657 | =cut | ||||
1658 | |||||
1659 | 1 | 10µs | 1 | 158µs | __END__ # spent 158µs making 1 call to B::Hooks::EndOfScope::XS::__ANON__[B/Hooks/EndOfScope/XS.pm:17] |