OpenSearch/docs/perl/index.asciidoc

= Elasticsearch.pm

== Overview

Search::Elasticsearch is the official Perl API for Elasticsearch. The full
documentation is available on https://metacpan.org/module/Search::Elasticsearch.

It can be installed with:

[source,sh]
------------------------------------
cpanm Search::Elasticsearch
------------------------------------

=== Features

This client provides:

* Full support for all Elasticsearch APIs

* HTTP backend (blocking and asynchronous with https://metacpan.org/module/Search::Elasticsearch::Async)

* Robust networking support which handles load balancing, failure detection and failover

* Good defaults

* Helper utilities for more complex operations, such as bulk indexing, scrolled searches and reindexing.

* Logging support via Log::Any

* Compatibility with the official clients for Python, Ruby, PHP and Javascript

* Easy extensibility

== Synopsis

[source,perl]
------------------------------------
use Search::Elasticsearch;

# Connect to localhost:9200:
my $e = Search::Elasticsearch->new();

# Round-robin between two nodes:
my $e = Search::Elasticsearch->new(
    nodes => [
        'search1:9200',
        'search2:9200'
    ]
);

# Connect to cluster at search1:9200, sniff all nodes and round-robin between them:
my $e = Search::Elasticsearch->new(
    nodes    => 'search1:9200',
    cxn_pool => 'Sniff'
);

# Index a document:
$e->index(
    index   => 'my_app',
    type    => 'blog_post',
    id      => 1,
    body    => {
        title   => 'Elasticsearch clients',
        content => 'Interesting content...',
        date    => '2013-09-24'
    }
);

# Get the document:
my $doc = $e->get(
    index   => 'my_app',
    type    => 'blog_post',
    id      => 1
);

# Search:
my $results = $e->search(
    index => 'my_app',
    body  => {
        query => {
            match => { title => 'elasticsearch' }
        }
    }
);
------------------------------------

[[v0_90]]
== Elasticsearch 0.90.* and earlier

The current version of the client supports the Elasticsearch 1.0 branch by
default, which is not backwards compatible with the 0.90 branch.

If you need to talk to a version of Elasticsearch before 1.0.0,
please use `Search::Elasticsearch::Client::0_90::Direct` as follows:

[source,perl]
------------------------------------
    $es = Search::Elasticsearch->new(
        client => '0_90::Direct'
    );
------------------------------------


== Reporting issues

The GitHub repository is http://github.com/elasticsearch/elasticsearch-perl
and any issues can be reported on the issues list at
http://github.com/elasticsearch/elasticsearch-perl/issues.

== Contributing

Open source contributions are welcome. Please read our
https://github.com/elasticsearch/elasticsearch-perl/blob/master/CONTRIBUTING.asciidoc[guide to contributing].

== Copyright and License

This software is Copyright (c) 2013-2015 by Elasticsearch BV.

This is free software, licensed under:
https://github.com/elasticsearch/elasticsearch-perl/blob/master/LICENSE.txt[The Apache License Version 2.0].