| 1 | package Search::Elasticsearch::Client::0_90::Direct; | ||
| 2 | |||
| 3 | use Moo; | ||
| 4 | with 'Search::Elasticsearch::Client::0_90::Role::API'; | ||
| 5 | with 'Search::Elasticsearch::Role::Client::Direct'; | ||
| 6 | |||
| 7 | our $VERSION='6.81'; | ||
| 8 | use Search::Elasticsearch 6.00 (); | ||
| 9 | |||
| 10 | use Search::Elasticsearch::Util qw(parse_params is_compat); | ||
| 11 | use namespace::clean; | ||
| 12 | |||
| 13 | sub _namespace {__PACKAGE__} | ||
| 14 | |||
| 15 | has 'cluster' => ( is => 'lazy' ); | ||
| 16 | has 'indices' => ( is => 'lazy' ); | ||
| 17 | has 'bulk_helper_class' => ( is => 'rw' ); | ||
| 18 | has 'scroll_helper_class' => ( is => 'rw' ); | ||
| 19 | has '_bulk_class' => ( is => 'lazy' ); | ||
| 20 | has '_scroll_class' => ( is => 'lazy' ); | ||
| 21 | |||
| 22 | __PACKAGE__->_install_api(''); | ||
| 23 | |||
| 24 | #=================================== | ||
| 25 | sub create { | ||
| 26 | #=================================== | ||
| 27 | my ( $self, $params ) = parse_params(@_); | ||
| 28 | $params->{op_type} = 'create'; | ||
| 29 | $self->_index( 'create', $params ); | ||
| 30 | } | ||
| 31 | |||
| 32 | #=================================== | ||
| 33 | sub index { | ||
| 34 | #=================================== | ||
| 35 | my ( $self, $params ) = parse_params(@_); | ||
| 36 | $self->_index( 'index', $params ); | ||
| 37 | } | ||
| 38 | |||
| 39 | #=================================== | ||
| 40 | sub _index { | ||
| 41 | #=================================== | ||
| 42 | my ( $self, $name, $params ) = @_; | ||
| 43 | my $defn = $self->api->{index}; | ||
| 44 | unless ( defined $params->{id} and length $params->{id} ) { | ||
| 45 | $defn = { %$defn, method => 'POST' }; | ||
| 46 | } | ||
| 47 | $self->perform_request( { %$defn, name => $name }, $params ); | ||
| 48 | } | ||
| 49 | |||
| 50 | #=================================== | ||
| 51 | around 'clear_scroll' => sub { | ||
| 52 | #=================================== | ||
| 53 | my $orig = shift; | ||
| 54 | my ( $self, $params ) = parse_params(@_); | ||
| 55 | $params->{scroll_id} ||= delete $params->{body}; | ||
| 56 | $orig->( $self, $params ); | ||
| 57 | }; | ||
| 58 | |||
| 59 | #=================================== | ||
| 60 | sub _build__bulk_class { | ||
| 61 | #=================================== | ||
| 62 | my $self = shift; | ||
| 63 | my $bulk_class = $self->bulk_helper_class | ||
| 64 | || 'Client::' . $self->api_version . '::Bulk'; | ||
| 65 | $self->_build_helper( 'bulk', $bulk_class ); | ||
| 66 | } | ||
| 67 | |||
| 68 | #=================================== | ||
| 69 | sub _build__scroll_class { | ||
| 70 | #=================================== | ||
| 71 | my $self = shift; | ||
| 72 | my $scroll_class = $self->scroll_helper_class | ||
| 73 | || 'Client::' . $self->api_version . '::Scroll'; | ||
| 74 | $self->_build_helper( 'scroll', $scroll_class ); | ||
| 75 | } | ||
| 76 | |||
| 77 | #=================================== | ||
| 78 | sub bulk_helper { | ||
| 79 | #=================================== | ||
| 80 | my ( $self, $params ) = parse_params(@_); | ||
| 81 | $params->{es} ||= $self; | ||
| 82 | $self->_bulk_class->new($params); | ||
| 83 | } | ||
| 84 | |||
| 85 | #=================================== | ||
| 86 | sub scroll_helper { | ||
| 87 | #=================================== | ||
| 88 | my ( $self, $params ) = parse_params(@_); | ||
| 89 | $params->{es} ||= $self; | ||
| 90 | $self->_scroll_class->new($params); | ||
| 91 | } | ||
| 92 | |||
| 93 | #=================================== | ||
| 94 | sub _build_cluster { shift->_build_namespace('Cluster') } | ||
| 95 | sub _build_indices { shift->_build_namespace('Indices') } | ||
| 96 | #=================================== | ||
| 97 | |||
| 98 | 1; | ||
| 99 | |||
| 100 | =pod | ||
| 101 | |||
| 102 | =encoding UTF-8 | ||
| 103 | |||
| 104 | =head1 NAME | ||
| 105 | |||
| 106 | Search::Elasticsearch::Client::0_90::Direct - Thin client with full support for Elasticsearch 0.90 APIs | ||
| 107 | |||
| 108 | =head1 VERSION | ||
| 109 | |||
| 110 | version 6.81 | ||
| 111 | |||
| 112 | =head1 SYNOPSIS | ||
| 113 | |||
| 114 | Create a client: | ||
| 115 | |||
| 116 | use Search::Elasticsearch; | ||
| 117 | my $e = Search::Elasticsearch->new( | ||
| 118 | client => '0_90::Direct' # for the 0.90 branch | ||
| 119 | ); | ||
| 120 | |||
| 121 | Index a doc: | ||
| 122 | |||
| 123 | $e->index( | ||
| 124 | index => 'my_index', | ||
| 125 | type => 'blog_post', | ||
| 126 | id => 123, | ||
| 127 | body => { | ||
| 128 | title => "Elasticsearch clients", | ||
| 129 | content => "Interesting content...", | ||
| 130 | date => "2013-09-23" | ||
| 131 | } | ||
| 132 | ); | ||
| 133 | |||
| 134 | Get a doc: | ||
| 135 | |||
| 136 | $e->get( | ||
| 137 | index => 'my_index', | ||
| 138 | type => 'my_type', | ||
| 139 | id => 123 | ||
| 140 | ); | ||
| 141 | |||
| 142 | Search for docs: | ||
| 143 | |||
| 144 | $results = $e->search( | ||
| 145 | index => 'my_index', | ||
| 146 | body => { | ||
| 147 | query => { | ||
| 148 | match => { | ||
| 149 | title => "elasticsearch" | ||
| 150 | } | ||
| 151 | } | ||
| 152 | } | ||
| 153 | ); | ||
| 154 | |||
| 155 | Index-level requests: | ||
| 156 | |||
| 157 | $e->indices->create( index => 'my_index' ); | ||
| 158 | $e->indices->delete( index => 'my_index' ) | ||
| 159 | |||
| 160 | Cluster-level requests: | ||
| 161 | |||
| 162 | $state = $e->cluster->state; | ||
| 163 | $stats = $e->cluster->node_stats; | ||
| 164 | |||
| 165 | =head1 DESCRIPTION | ||
| 166 | |||
| 167 | The L<Search::Elasticsearch::Client::0_90::Direct> class provides the | ||
| 168 | Elasticsearch 0.90.x compatible client that is returned by: | ||
| 169 | |||
| 170 | $e = Search::Elasticsearch->new( client => '0_90::Direct' ); | ||
| 171 | |||
| 172 | It is intended to be as close as possible to the native REST API that | ||
| 173 | Elasticsearch uses, so that it is easy to translate the | ||
| 174 | L<Elasticsearch reference documentation|http://www.elasticsearch/guide> | ||
| 175 | for an API to the equivalent in this client. | ||
| 176 | |||
| 177 | This class provides the methods for L<document CRUD|/DOCUMENT CRUD METHODS>, | ||
| 178 | L<bulk document CRUD|/BULK DOCUMENT CRUD METHODS> and L<search|/SEARCH METHODS>. | ||
| 179 | It also provides access to clients for managing L<indices|/indices()> | ||
| 180 | and the L<cluster|/cluster()>. | ||
| 181 | |||
| 182 | =head1 CONVENTIONS | ||
| 183 | |||
| 184 | =head2 Parameter passing | ||
| 185 | |||
| 186 | Parameters can be passed to any request method as a list or as a hash | ||
| 187 | reference. The following two statements are equivalent: | ||
| 188 | |||
| 189 | $e->search( size => 10 ); | ||
| 190 | $e->search({size => 10}); | ||
| 191 | |||
| 192 | =head2 Path parameters | ||
| 193 | |||
| 194 | Any values that should be included in the URL path, eg C</{index}/{type}> | ||
| 195 | should be passed as top level parameters: | ||
| 196 | |||
| 197 | $e->search( index => 'my_index', type => 'my_type' ); | ||
| 198 | |||
| 199 | Alternatively, you can specify a C<path> parameter directly: | ||
| 200 | |||
| 201 | $e->search( path => '/my_index/my_type' ); | ||
| 202 | |||
| 203 | =head2 Query-string parameters | ||
| 204 | |||
| 205 | Any values that should be included in the query string should be passed | ||
| 206 | as top level parameters: | ||
| 207 | |||
| 208 | $e->search( size => 10 ); | ||
| 209 | |||
| 210 | If you pass in a C<\%params> hash, then it will be included in the | ||
| 211 | query string parameters without any error checking. The following: | ||
| 212 | |||
| 213 | $e->search( size => 10, params => { from => 5, size => 5 }) | ||
| 214 | |||
| 215 | would result in this query string: | ||
| 216 | |||
| 217 | ?from=5&size=10 | ||
| 218 | |||
| 219 | =head2 Body parameter | ||
| 220 | |||
| 221 | The request body should be passed in the C<body> key: | ||
| 222 | |||
| 223 | $e->search( | ||
| 224 | body => { | ||
| 225 | query => {...} | ||
| 226 | } | ||
| 227 | ); | ||
| 228 | |||
| 229 | The body can also be a UTF8-decoded string, which will be converted into | ||
| 230 | UTF-8 bytes and passed as is: | ||
| 231 | |||
| 232 | $e->indices->analyze( body => "The quick brown fox"); | ||
| 233 | |||
| 234 | =head2 Ignore parameter | ||
| 235 | |||
| 236 | Normally, any HTTP status code outside the 200-299 range will result in | ||
| 237 | an error being thrown. To suppress these errors, you can specify which | ||
| 238 | status codes to ignore in the C<ignore> parameter. | ||
| 239 | |||
| 240 | $e->indices->delete( | ||
| 241 | index => 'my_index', | ||
| 242 | ignore => 404 | ||
| 243 | ); | ||
| 244 | |||
| 245 | This is most useful for | ||
| 246 | L<Missing|Search::Elasticsearch::Error/Search::Elasticsearch::Error::Missing> errors, which | ||
| 247 | are triggered by a C<404> status code when some requested resource does | ||
| 248 | not exist. | ||
| 249 | |||
| 250 | Multiple error codes can be specified with an array: | ||
| 251 | |||
| 252 | $e->indices->delete( | ||
| 253 | index => 'my_index', | ||
| 254 | ignore => [404,409] | ||
| 255 | ); | ||
| 256 | |||
| 257 | =head1 CONFIGURATION | ||
| 258 | |||
| 259 | =head2 C<bulk_helper_class> | ||
| 260 | |||
| 261 | The class to use for the L</bulk_helper()> method. Defaults to | ||
| 262 | L<Search::Elasticsearch::Client::0_90::Bulk>. | ||
| 263 | |||
| 264 | =head2 C<scroll_helper_class> | ||
| 265 | |||
| 266 | The class to use for the L</scroll_helper()> method. Defaults to | ||
| 267 | L<Search::Elasticsearch::Client::0_90::Scroll>. | ||
| 268 | |||
| 269 | =head1 GENERAL METHODS | ||
| 270 | |||
| 271 | =head2 C<info()> | ||
| 272 | |||
| 273 | $info = $e->info | ||
| 274 | |||
| 275 | Returns information about the version of Elasticsearch that the responding node | ||
| 276 | is running. | ||
| 277 | |||
| 278 | =head2 C<ping()> | ||
| 279 | |||
| 280 | $e->ping | ||
| 281 | |||
| 282 | Pings a node in the cluster and returns C<1> if it receives a C<200> | ||
| 283 | response, otherwise it throws an error. | ||
| 284 | |||
| 285 | =head2 C<indices()> | ||
| 286 | |||
| 287 | $indices_client = $e->indices; | ||
| 288 | |||
| 289 | Returns an L<Search::Elasticsearch::Client::0_90::Direct::Indices> object which can be used | ||
| 290 | for managing indices, eg creating, deleting indices, managing mapping, | ||
| 291 | index settings etc. | ||
| 292 | |||
| 293 | =head2 C<cluster()> | ||
| 294 | |||
| 295 | $cluster_client = $e->cluster; | ||
| 296 | |||
| 297 | Returns an L<Search::Elasticsearch::Client::0_90::Direct::Cluster> object which can be used | ||
| 298 | for managing the cluster, eg cluster-wide settings, cluster health, | ||
| 299 | node information and stats. | ||
| 300 | |||
| 301 | =head1 DOCUMENT CRUD METHODS | ||
| 302 | |||
| 303 | These methods allow you to perform create, index, update and delete requests | ||
| 304 | for single documents: | ||
| 305 | |||
| 306 | =head2 C<index()> | ||
| 307 | |||
| 308 | $response = $e->index( | ||
| 309 | index => 'index_name', # required | ||
| 310 | type => 'type_name', # required | ||
| 311 | id => 'doc_id', # optional, otherwise auto-generated | ||
| 312 | |||
| 313 | body => { document } # required | ||
| 314 | ); | ||
| 315 | |||
| 316 | The C<index()> method is used to index a new document or to reindex | ||
| 317 | an existing document. | ||
| 318 | |||
| 319 | Query string parameters: | ||
| 320 | C<consistency>, | ||
| 321 | C<op_type>, | ||
| 322 | C<parent>, | ||
| 323 | C<percolate>, | ||
| 324 | C<refresh>, | ||
| 325 | C<replication>, | ||
| 326 | C<routing>, | ||
| 327 | C<timeout>, | ||
| 328 | C<timestamp>, | ||
| 329 | C<ttl>, | ||
| 330 | C<version>, | ||
| 331 | C<version_type> | ||
| 332 | |||
| 333 | See the L<index docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-index_.html> | ||
| 334 | for more information. | ||
| 335 | |||
| 336 | =head2 C<create()> | ||
| 337 | |||
| 338 | $response = $e->create( | ||
| 339 | index => 'index_name', # required | ||
| 340 | type => 'type_name', # required | ||
| 341 | id => 'doc_id', # optional, otherwise auto-generated | ||
| 342 | |||
| 343 | body => { document } # required | ||
| 344 | ); | ||
| 345 | |||
| 346 | The C<create()> method works exactly like the L</index()> method, except | ||
| 347 | that it will throw a C<Conflict> error if a document with the same | ||
| 348 | C<index>, C<type> and C<id> already exists. | ||
| 349 | |||
| 350 | Query string parameters: | ||
| 351 | C<consistency>, | ||
| 352 | C<op_type>, | ||
| 353 | C<parent>, | ||
| 354 | C<percolate>, | ||
| 355 | C<refresh>, | ||
| 356 | C<replication>, | ||
| 357 | C<routing>, | ||
| 358 | C<timeout>, | ||
| 359 | C<timestamp>, | ||
| 360 | C<ttl>, | ||
| 361 | C<version>, | ||
| 362 | C<version_type> | ||
| 363 | |||
| 364 | See the L<create docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-create.html> | ||
| 365 | for more information. | ||
| 366 | |||
| 367 | =head2 C<get()> | ||
| 368 | |||
| 369 | $response = $e->get( | ||
| 370 | index => 'index_name', # required | ||
| 371 | type => 'type_name', # required | ||
| 372 | id => 'doc_id', # required | ||
| 373 | ); | ||
| 374 | |||
| 375 | The C<get()> method will retrieve the document with the specified | ||
| 376 | C<index>, C<type> and C<id>, or will throw a C<Missing> error. | ||
| 377 | |||
| 378 | Query string parameters: | ||
| 379 | C<_source>, | ||
| 380 | C<_source_exclude>, | ||
| 381 | C<_source_include>, | ||
| 382 | C<fields>, | ||
| 383 | C<parent>, | ||
| 384 | C<preference>, | ||
| 385 | C<realtime>, | ||
| 386 | C<refresh>, | ||
| 387 | C<routing> | ||
| 388 | |||
| 389 | See the L<get docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-get.html> | ||
| 390 | for more information. | ||
| 391 | |||
| 392 | =head2 C<get_source()> | ||
| 393 | |||
| 394 | $response = $e->get_source( | ||
| 395 | index => 'index_name', # required | ||
| 396 | type => 'type_name', # required | ||
| 397 | id => 'doc_id', # required | ||
| 398 | ); | ||
| 399 | |||
| 400 | The C<get_source()> method works just like the L</get()> method except that | ||
| 401 | it returns just the C<_source> field (the value of the C<body> parameter | ||
| 402 | in the L</index()> method) instead of returning the C<_source> field | ||
| 403 | plus the document metadata, ie the C<_index>, C<_type> etc. | ||
| 404 | |||
| 405 | Query string parameters: | ||
| 406 | C<_source_exclude>, | ||
| 407 | C<_source_include>, | ||
| 408 | C<parent>, | ||
| 409 | C<preference>, | ||
| 410 | C<realtime>, | ||
| 411 | C<refresh>, | ||
| 412 | C<routing> | ||
| 413 | |||
| 414 | See the L<get_source docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-get.html> | ||
| 415 | for more information. | ||
| 416 | |||
| 417 | =head2 C<exists()> | ||
| 418 | |||
| 419 | $response = $e->exists( | ||
| 420 | index => 'index_name', # required | ||
| 421 | type => 'type_name', # required | ||
| 422 | id => 'doc_id', # required | ||
| 423 | ); | ||
| 424 | |||
| 425 | The C<exists()> method returns C<1> if a document with the specified | ||
| 426 | C<index>, C<type> and C<id> exists, or an empty string if it doesn't. | ||
| 427 | |||
| 428 | Query string parameters: | ||
| 429 | C<parent>, | ||
| 430 | C<preference>, | ||
| 431 | C<realtime>, | ||
| 432 | C<refresh>, | ||
| 433 | C<routing> | ||
| 434 | |||
| 435 | See the L<exists docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-get.html> | ||
| 436 | for more information. | ||
| 437 | |||
| 438 | =head2 C<delete()> | ||
| 439 | |||
| 440 | $response = $e->delete( | ||
| 441 | index => 'index_name', # required | ||
| 442 | type => 'type_name', # required | ||
| 443 | id => 'doc_id', # required | ||
| 444 | ); | ||
| 445 | |||
| 446 | The C<delete()> method will delete the document with the specified | ||
| 447 | C<index>, C<type> and C<id>, or will throw a C<Missing> error. | ||
| 448 | |||
| 449 | Query string parameters: | ||
| 450 | C<consistency>, | ||
| 451 | C<parent>, | ||
| 452 | C<refresh>, | ||
| 453 | C<replication>, | ||
| 454 | C<routing>, | ||
| 455 | C<timeout>, | ||
| 456 | C<version>, | ||
| 457 | C<version_type> | ||
| 458 | |||
| 459 | See the L<delete docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-delete.html> | ||
| 460 | for more information. | ||
| 461 | |||
| 462 | =head2 C<update()> | ||
| 463 | |||
| 464 | $response = $e->update( | ||
| 465 | index => 'index_name', # required | ||
| 466 | type => 'type_name', # required | ||
| 467 | id => 'doc_id', # required | ||
| 468 | |||
| 469 | body => { update } # required | ||
| 470 | ); | ||
| 471 | |||
| 472 | The C<update()> method updates a document with the corresponding | ||
| 473 | C<index>, C<type> and C<id> if it exists. Updates can be performed either by: | ||
| 474 | |||
| 475 | =over | ||
| 476 | |||
| 477 | =item * providing a partial document to be merged in to the existing document: | ||
| 478 | |||
| 479 | $response = $e->update( | ||
| 480 | ..., | ||
| 481 | body => { | ||
| 482 | doc => { new_field => 'new_value'}, | ||
| 483 | } | ||
| 484 | ); | ||
| 485 | |||
| 486 | =item * or with a script: | ||
| 487 | |||
| 488 | $response = $e->update( | ||
| 489 | ..., | ||
| 490 | body => { | ||
| 491 | script => "ctx._source.counter += incr", | ||
| 492 | params => { incr => 5 } | ||
| 493 | } | ||
| 494 | ); | ||
| 495 | |||
| 496 | =back | ||
| 497 | |||
| 498 | Query string parameters: | ||
| 499 | C<consistency>, | ||
| 500 | C<fields>, | ||
| 501 | C<lang>, | ||
| 502 | C<parent>, | ||
| 503 | C<percolate>, | ||
| 504 | C<realtime>, | ||
| 505 | C<refresh>, | ||
| 506 | C<replication>, | ||
| 507 | C<retry_on_conflict>, | ||
| 508 | C<routing>, | ||
| 509 | C<script>, | ||
| 510 | C<timeout>, | ||
| 511 | C<timestamp>, | ||
| 512 | C<ttl>, | ||
| 513 | C<version>, | ||
| 514 | C<version_type> | ||
| 515 | |||
| 516 | See the L<update docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-update.html> | ||
| 517 | for more information. | ||
| 518 | |||
| 519 | =head1 BULK DOCUMENT CRUD METHODS | ||
| 520 | |||
| 521 | The bulk document CRUD methods are used for running multiple CRUD actions | ||
| 522 | within a single request. By reducing the number of network requests | ||
| 523 | that need to be made, bulk requests greatly improve performance. | ||
| 524 | |||
| 525 | =head2 C<bulk()> | ||
| 526 | |||
| 527 | $response = $e->bulk( | ||
| 528 | index => 'index_name', # required if type specified | ||
| 529 | type => 'type_name', # optional | ||
| 530 | |||
| 531 | body => [ actions ] # required | ||
| 532 | ); | ||
| 533 | |||
| 534 | See L<Search::Elasticsearch::Client::0_90::Bulk> and L</bulk_helper()> for a helper module that makes | ||
| 535 | bulk indexing simpler to use. | ||
| 536 | |||
| 537 | The C<bulk()> method can perform multiple L</index()>, L</create()>, | ||
| 538 | L</delete()> or L</update()> actions with a single request. The C<body> | ||
| 539 | parameter expects an array containing the list of actions to perform. | ||
| 540 | |||
| 541 | An I<action> consists of an initial metadata hash ref containing the action | ||
| 542 | type, plus the associated metadata, eg : | ||
| 543 | |||
| 544 | { delete => { _index => 'index', _type => 'type', _id => 123 }} | ||
| 545 | |||
| 546 | The C<index> and C<create> actions then expect a hashref containing | ||
| 547 | the document itself: | ||
| 548 | |||
| 549 | { create => { _index => 'index', _type => 'type', _id => 123 }}, | ||
| 550 | { title => "A newly created document" } | ||
| 551 | |||
| 552 | And the C<update> action expects a hashref containing the update commands, | ||
| 553 | eg: | ||
| 554 | |||
| 555 | { update => { _index => 'index', _type => 'type', _id => 123 }}, | ||
| 556 | { script => "ctx._source.counter+=1" } | ||
| 557 | |||
| 558 | Each action can include the same parameters that you would pass to | ||
| 559 | the equivalent L</index()>, L</create()>, L</delete()> or L</update()> | ||
| 560 | request, except that C<_index>, C<_type> and C<_id> must be specified with | ||
| 561 | the preceding underscore. All other parameters can be specified with or | ||
| 562 | without the underscore. | ||
| 563 | |||
| 564 | For instance: | ||
| 565 | |||
| 566 | $response = $e->bulk( | ||
| 567 | index => 'index_name', # default index name | ||
| 568 | type => 'type_name', # default type name | ||
| 569 | body => [ | ||
| 570 | |||
| 571 | # create action | ||
| 572 | { create => { | ||
| 573 | _index => 'not_the_default_index', | ||
| 574 | _type => 'not_the_default_type', | ||
| 575 | _id => 123 | ||
| 576 | }}, | ||
| 577 | { title => 'Foo' }, | ||
| 578 | |||
| 579 | # index action | ||
| 580 | { index => { _id => 124 }}, | ||
| 581 | { title => 'Foo' }, | ||
| 582 | |||
| 583 | # delete action | ||
| 584 | { delete => { _id => 125 }}, | ||
| 585 | |||
| 586 | # update action | ||
| 587 | { update => { _id => 126 }}, | ||
| 588 | { script => "ctx._source.counter+1" } | ||
| 589 | ] | ||
| 590 | ); | ||
| 591 | |||
| 592 | Each action is performed separately. One failed action will not | ||
| 593 | cause the others to fail as well. | ||
| 594 | |||
| 595 | Query string parameters: | ||
| 596 | C<consistency>, | ||
| 597 | C<refresh>, | ||
| 598 | C<replication>, | ||
| 599 | C<timeout>, | ||
| 600 | C<type> | ||
| 601 | |||
| 602 | See the L<bulk docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-bulk.html> | ||
| 603 | for more information. | ||
| 604 | |||
| 605 | =head2 C<bulk_helper()> | ||
| 606 | |||
| 607 | $bulk_helper = $e->bulk_helper( @args ); | ||
| 608 | |||
| 609 | Returns a new instance of the class specified in the L</bulk_helper_class>, | ||
| 610 | which defaults to L<Search::Elasticsearch::Client::0_90::Bulk>. | ||
| 611 | |||
| 612 | =head2 C<mget()> | ||
| 613 | |||
| 614 | $results = $e->mget( | ||
| 615 | index => 'default_index', # optional, required when type specified | ||
| 616 | type => 'default_type', # optional | ||
| 617 | |||
| 618 | body => { docs or ids } # required | ||
| 619 | ); | ||
| 620 | |||
| 621 | The C<mget()> method will retrieve multiple documents with a single request. | ||
| 622 | The C<body> consists of an array of documents to retrieve: | ||
| 623 | |||
| 624 | $results = $e->mget( | ||
| 625 | index => 'default_index', | ||
| 626 | type => 'default_type', | ||
| 627 | body => { | ||
| 628 | docs => [ | ||
| 629 | { _id => 1}, | ||
| 630 | { _id => 2, _type => 'not_the_default_type' } | ||
| 631 | ] | ||
| 632 | } | ||
| 633 | ); | ||
| 634 | |||
| 635 | You can also pass any of the other parameters that the L</get()> request | ||
| 636 | accepts. | ||
| 637 | |||
| 638 | If you have specified an C<index> and C<type>, you can just include the | ||
| 639 | C<ids> of the documents to retrieve: | ||
| 640 | |||
| 641 | $results = $e->mget( | ||
| 642 | index => 'default_index', | ||
| 643 | type => 'default_type', | ||
| 644 | body => { | ||
| 645 | ids => [ 1, 2, 3] | ||
| 646 | } | ||
| 647 | ); | ||
| 648 | |||
| 649 | Query string parameters: | ||
| 650 | C<_source>, | ||
| 651 | C<_source_exclude>, | ||
| 652 | C<_source_include>, | ||
| 653 | C<fields>, | ||
| 654 | C<preference>, | ||
| 655 | C<realtime>, | ||
| 656 | C<refresh> | ||
| 657 | |||
| 658 | See the L<mget docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-multi-get.html> | ||
| 659 | for more information. | ||
| 660 | |||
| 661 | =head2 C<delete_by_query()> | ||
| 662 | |||
| 663 | $result = $e->delete_by_query( | ||
| 664 | index => 'index' | \@indices, # optional | ||
| 665 | type => 'type' | \@types, # optional | ||
| 666 | |||
| 667 | body => { query } # required | ||
| 668 | |||
| 669 | ); | ||
| 670 | |||
| 671 | The C<delete_by_query()> method deletes all documents which match the | ||
| 672 | query. For instance, to delete all documents from 2012: | ||
| 673 | |||
| 674 | $result = $e->delete_by_query( | ||
| 675 | body => { | ||
| 676 | query => { | ||
| 677 | range => { | ||
| 678 | date => { | ||
| 679 | gte => '2012-01-01', | ||
| 680 | lt => '2013-01-01' | ||
| 681 | } | ||
| 682 | } | ||
| 683 | } | ||
| 684 | } | ||
| 685 | ); | ||
| 686 | |||
| 687 | Query string parameters: | ||
| 688 | C<allow_no_indices>, | ||
| 689 | C<analyzer>, | ||
| 690 | C<consistency>, | ||
| 691 | C<default_operator>, | ||
| 692 | C<df>, | ||
| 693 | C<expand_wildcards>, | ||
| 694 | C<ignore_indices>, | ||
| 695 | C<ignore_unavailable>, | ||
| 696 | C<q>, | ||
| 697 | C<replication>, | ||
| 698 | C<routing>, | ||
| 699 | C<source>, | ||
| 700 | C<timeout> | ||
| 701 | |||
| 702 | See the L<delete_by_query docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/docs-delete-by-query.html> | ||
| 703 | for more information. | ||
| 704 | |||
| 705 | =head1 SEARCH METHODS | ||
| 706 | |||
| 707 | The search methods are used for querying documents in one, more or all indices | ||
| 708 | and of one, more or all types: | ||
| 709 | |||
| 710 | =head2 C<search()> | ||
| 711 | |||
| 712 | $results = $e->search( | ||
| 713 | index => 'index' | \@indices, # optional | ||
| 714 | type => 'type' | \@types, # optional | ||
| 715 | |||
| 716 | body => { search params } # optional | ||
| 717 | ); | ||
| 718 | |||
| 719 | The C<search()> method searches for matching documents in one or more | ||
| 720 | indices. It is just as easy to search a single index as it is to search | ||
| 721 | all the indices in your cluster. It can also return | ||
| 722 | L<facets|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-facets.thml> | ||
| 723 | (aggregations on particular fields), | ||
| 724 | L<highlighted snippets|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-highlighting.html> | ||
| 725 | and L<did-you-mean|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-suggesters-phrase.html> | ||
| 726 | or L<search-as-you-type|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-suggesters-completion.html> | ||
| 727 | suggestions. | ||
| 728 | |||
| 729 | The I<lite> L<version of search|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-uri-request.html> | ||
| 730 | allows you to specify a query string in the C<q> parameter, using the | ||
| 731 | Lucene query string syntax: | ||
| 732 | |||
| 733 | $results = $e->search( q => 'title:(elasticsearch clients)'); | ||
| 734 | |||
| 735 | However, the preferred way to search is by using the | ||
| 736 | L<Query DSL|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/query-dsl.html> | ||
| 737 | to create a query, and passing that C<query> in the | ||
| 738 | L<request body|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-request-body.html>: | ||
| 739 | |||
| 740 | $results = $e->search( | ||
| 741 | body => { | ||
| 742 | query => { | ||
| 743 | match => { title => 'Elasticsearch clients'} | ||
| 744 | } | ||
| 745 | } | ||
| 746 | ); | ||
| 747 | |||
| 748 | Query string parameters: | ||
| 749 | C<_source>, | ||
| 750 | C<_source_exclude>, | ||
| 751 | C<_source_include>, | ||
| 752 | C<allow_no_indices>, | ||
| 753 | C<analyze_wildcard>, | ||
| 754 | C<analyzer>, | ||
| 755 | C<default_operator>, | ||
| 756 | C<df>, | ||
| 757 | C<expand_wildcards>, | ||
| 758 | C<explain>, | ||
| 759 | C<fields>, | ||
| 760 | C<from>, | ||
| 761 | C<ignore_indices>, | ||
| 762 | C<ignore_indices>, | ||
| 763 | C<ignore_unavailable>, | ||
| 764 | C<lenient>, | ||
| 765 | C<lowercase_expanded_terms>, | ||
| 766 | C<preference>, | ||
| 767 | C<q>, | ||
| 768 | C<routing>, | ||
| 769 | C<scroll>, | ||
| 770 | C<search_type>, | ||
| 771 | C<size>, | ||
| 772 | C<sort>, | ||
| 773 | C<source>, | ||
| 774 | C<stats>, | ||
| 775 | C<suggest_field>, | ||
| 776 | C<suggest_mode>, | ||
| 777 | C<suggest_size>, | ||
| 778 | C<suggest_text>, | ||
| 779 | C<timeout>, | ||
| 780 | C<version> | ||
| 781 | |||
| 782 | See the L<search reference|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-request-body.html> | ||
| 783 | for more information. | ||
| 784 | |||
| 785 | Also see L<Search::Elasticsearch::Transport/send_get_body_as>. | ||
| 786 | |||
| 787 | =head2 C<count()> | ||
| 788 | |||
| 789 | $results = $e->count( | ||
| 790 | index => 'index' | \@indices, # optional | ||
| 791 | type => 'type' | \@types, # optional | ||
| 792 | |||
| 793 | body => { query } # optional | ||
| 794 | ) | ||
| 795 | |||
| 796 | The C<count()> method returns the total count of all documents matching the | ||
| 797 | query: | ||
| 798 | |||
| 799 | $results = $e->count( | ||
| 800 | body => { | ||
| 801 | query => { | ||
| 802 | match => { title => 'Elasticsearch clients' } | ||
| 803 | } | ||
| 804 | } | ||
| 805 | ); | ||
| 806 | |||
| 807 | Query string parameters: | ||
| 808 | C<allow_no_indices>, | ||
| 809 | C<expand_wildcards>, | ||
| 810 | C<ignore_indices>, | ||
| 811 | C<ignore_unavailable>, | ||
| 812 | C<min_score>, | ||
| 813 | C<preference>, | ||
| 814 | C<routing>, | ||
| 815 | C<source> | ||
| 816 | |||
| 817 | See the L<count docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-count.html> | ||
| 818 | for more information. | ||
| 819 | |||
| 820 | =head2 C<scroll()> | ||
| 821 | |||
| 822 | $results = $e->scroll( | ||
| 823 | scroll => '1m', | ||
| 824 | scroll_id => $id | ||
| 825 | ); | ||
| 826 | |||
| 827 | When a L</search()> has been performed with the | ||
| 828 | C<scroll> parameter, the C<scroll()> | ||
| 829 | method allows you to keep pulling more results until the results | ||
| 830 | are exhausted. | ||
| 831 | |||
| 832 | B<NOTE:> you will almost always want to set the | ||
| 833 | C<search_type> to C<scan> in your | ||
| 834 | original C<search()> request. | ||
| 835 | |||
| 836 | See L</scroll_helper()> and L<Search::Elasticsearch::Client::0_90::Scroll> for a helper utility | ||
| 837 | which makes managing scroll requests much easier. | ||
| 838 | |||
| 839 | Query string parameters: | ||
| 840 | C<scroll>, | ||
| 841 | C<scroll_id> | ||
| 842 | |||
| 843 | See the L<scroll docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-request-scroll.html> | ||
| 844 | and the L<search_type docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search.html/search-request-search-type.html> | ||
| 845 | for more information. | ||
| 846 | |||
| 847 | =head2 C<clear_scroll()> | ||
| 848 | |||
| 849 | $response = $e->clear_scroll( | ||
| 850 | scroll_id => $id | \@ids # required | ||
| 851 | ); | ||
| 852 | |||
| 853 | The C<clear_scroll()> method can clear unfinished scroll requests, freeing | ||
| 854 | up resources on the server. | ||
| 855 | |||
| 856 | =head2 C<scroll_helper()> | ||
| 857 | |||
| 858 | $scroll_helper = $e->scroll_helper( @args ); | ||
| 859 | |||
| 860 | Returns a new instance of the class specified in the L</scroll_helper_class>, | ||
| 861 | which defaults to L<Search::Elasticsearch::Client::0_90::Scroll>. | ||
| 862 | |||
| 863 | =head2 C<msearch()> | ||
| 864 | |||
| 865 | $results = $e->msearch( | ||
| 866 | index => 'default_index' | \@indices, # optional | ||
| 867 | type => 'default_type' | \@types, # optional | ||
| 868 | |||
| 869 | body => [ searches ] # required | ||
| 870 | ); | ||
| 871 | |||
| 872 | The C<msearch()> method allows you to perform multiple searches in a single | ||
| 873 | request. Similar to the L</bulk()> request, each search request in the | ||
| 874 | C<body> consists of two hashes: the metadata hash then the search request | ||
| 875 | hash (the same data that you'd specify in the C<body> of a L</search()> | ||
| 876 | request). For instance: | ||
| 877 | |||
| 878 | $results = $e->msearch( | ||
| 879 | index => 'default_index', | ||
| 880 | type => ['default_type_1', 'default_type_2'], | ||
| 881 | body => [ | ||
| 882 | # uses defaults | ||
| 883 | {}, | ||
| 884 | { query => { match_all => {} }}, | ||
| 885 | |||
| 886 | # uses a custom index | ||
| 887 | { index => 'not_the_default_index' }, | ||
| 888 | { query => { match_all => {} }} | ||
| 889 | ] | ||
| 890 | ); | ||
| 891 | |||
| 892 | Query string parameters: | ||
| 893 | C<search_type> | ||
| 894 | |||
| 895 | See the L<msearch docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-multi-search.html> | ||
| 896 | for more information. | ||
| 897 | |||
| 898 | =head2 C<explain()> | ||
| 899 | |||
| 900 | $response = $e->explain( | ||
| 901 | index => 'my_index', # required | ||
| 902 | type => 'my_type', # required | ||
| 903 | id => 123, # required | ||
| 904 | |||
| 905 | body => { search } # required | ||
| 906 | ); | ||
| 907 | |||
| 908 | The C<explain()> method explains why the specified document did or | ||
| 909 | did not match a query, and how the relevance score was calculated. | ||
| 910 | For instance: | ||
| 911 | |||
| 912 | $response = $e->explain( | ||
| 913 | index => 'my_index', | ||
| 914 | type => 'my_type', | ||
| 915 | id => 123, | ||
| 916 | body => { | ||
| 917 | query => { | ||
| 918 | match => { title => 'Elasticsearch clients' } | ||
| 919 | } | ||
| 920 | } | ||
| 921 | ); | ||
| 922 | |||
| 923 | Query string parameters: | ||
| 924 | C<_source>, | ||
| 925 | C<_source_exclude>, | ||
| 926 | C<_source_include>, | ||
| 927 | C<analyze_wildcard>, | ||
| 928 | C<analyzer>, | ||
| 929 | C<default_operator>, | ||
| 930 | C<df>, | ||
| 931 | C<fields>, | ||
| 932 | C<lenient>, | ||
| 933 | C<lowercase_expanded_terms>, | ||
| 934 | C<parent>, | ||
| 935 | C<preference>, | ||
| 936 | C<q>, | ||
| 937 | C<routing>, | ||
| 938 | C<source> | ||
| 939 | |||
| 940 | See the L<explain docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-explain.html> | ||
| 941 | for more information. | ||
| 942 | |||
| 943 | =head2 C<percolate()> | ||
| 944 | |||
| 945 | $results = $e->percolate( | ||
| 946 | index => 'my_index', # required | ||
| 947 | type => 'my_type', # required | ||
| 948 | |||
| 949 | body => { percolation } # required | ||
| 950 | ); | ||
| 951 | |||
| 952 | Percolation is search inverted: instead of finding docs which match a | ||
| 953 | particular query, it finds queries which match a particular document, eg | ||
| 954 | for I<alert-me-when> functionality. | ||
| 955 | |||
| 956 | The C<percolate()> method runs a percolation request to find the | ||
| 957 | queries matching a particular document. In the C<body> you should pass the | ||
| 958 | C<_source> field of the document under the C<doc> key: | ||
| 959 | |||
| 960 | $results = $e->percolate( | ||
| 961 | index => 'my_index', | ||
| 962 | type => 'my_type', | ||
| 963 | body => { | ||
| 964 | doc => { | ||
| 965 | title => 'Elasticsearch rocks' | ||
| 966 | } | ||
| 967 | } | ||
| 968 | ); | ||
| 969 | |||
| 970 | Query string parameters: | ||
| 971 | C<prefer_local> | ||
| 972 | |||
| 973 | See the L<percolate docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-percolate.html> | ||
| 974 | for more information. | ||
| 975 | |||
| 976 | =head2 C<suggest()> | ||
| 977 | |||
| 978 | $results = $e->suggest( | ||
| 979 | index => 'index' | \@indices, # optional | ||
| 980 | type => 'type' | \@types, # optional | ||
| 981 | |||
| 982 | body => { suggest request } # required | ||
| 983 | ); | ||
| 984 | |||
| 985 | The C<suggest()> method is used to run | ||
| 986 | L<did-you-mean|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-suggesteres-phrase.html> | ||
| 987 | or L<search-as-you-type|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-suggesters-completion.html> | ||
| 988 | suggestion requests, which can also be run as part of a L</search()> request. | ||
| 989 | |||
| 990 | $results = $e->suggest( | ||
| 991 | index => 'my_index', | ||
| 992 | type => 'my_type', | ||
| 993 | body => { | ||
| 994 | my_suggestions => { | ||
| 995 | phrase => { | ||
| 996 | text => 'johnny walker', | ||
| 997 | field => 'title' | ||
| 998 | } | ||
| 999 | } | ||
| 1000 | } | ||
| 1001 | ); | ||
| 1002 | |||
| 1003 | Query string parameters: | ||
| 1004 | C<allow_no_indices>, | ||
| 1005 | C<expand_wildcards>, | ||
| 1006 | C<ignore_indices>, | ||
| 1007 | C<ignore_unavailable>, | ||
| 1008 | C<preference>, | ||
| 1009 | C<routing>, | ||
| 1010 | C<source> | ||
| 1011 | |||
| 1012 | =head2 C<mlt()> | ||
| 1013 | |||
| 1014 | $results = $e->mlt( | ||
| 1015 | index => 'my_index', # required | ||
| 1016 | type => 'my_type', # required | ||
| 1017 | id => 123, # required | ||
| 1018 | |||
| 1019 | body => { search } # optional | ||
| 1020 | ); | ||
| 1021 | |||
| 1022 | The C<mlt()> method runs a | ||
| 1023 | L<more-like-this query|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/query-dsl-mlt-query.html> | ||
| 1024 | to find other documents which are similar to the specified document. | ||
| 1025 | |||
| 1026 | Query string parameters: | ||
| 1027 | C<boost_terms>, | ||
| 1028 | C<max_doc_freq>, | ||
| 1029 | C<max_query_terms>, | ||
| 1030 | C<max_word_len>, | ||
| 1031 | C<min_doc_freq>, | ||
| 1032 | C<min_term_freq>, | ||
| 1033 | C<min_word_len>, | ||
| 1034 | C<mlt_fields>, | ||
| 1035 | C<percent_terms_to_match>, | ||
| 1036 | C<routing>, | ||
| 1037 | C<search_from>, | ||
| 1038 | C<search_indices>, | ||
| 1039 | C<search_scroll>, | ||
| 1040 | C<search_size>, | ||
| 1041 | C<search_source>, | ||
| 1042 | C<search_type>, | ||
| 1043 | C<search_types>, | ||
| 1044 | C<stop_words> | ||
| 1045 | |||
| 1046 | See the L<mlt docs|http://www.elastic.co/guide/en/elasticsearch/reference/0.90/search-more-like-this.html> | ||
| 1047 | for more information. | ||
| 1048 | |||
| 1049 | =head1 AUTHOR | ||
| 1050 | |||
| 1051 | Enrico Zimuel <enrico.zimuel@elastic.co> | ||
| 1052 | |||
| 1053 | =head1 COPYRIGHT AND LICENSE | ||
| 1054 | |||
| 1055 | This software is Copyright (c) 2020 by Elasticsearch BV. | ||
| 1056 | |||
| 1057 | This is free software, licensed under: | ||
| 1058 | |||
| 1059 | The Apache License, Version 2.0, January 2004 | ||
| 1060 | |||
| 1061 | =cut | ||
| 1062 | |||
| 1063 | __END__ |