view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

# NAME

Elastijk - A specialized Elasticsearch client.

# SYNOPSIS

    use Elastijk;

    my ($status, $response) = Elastijk::request({
        host => "localhost",
        port => "9200",
        method => "GET",

        index => "blog",
        type => "article",
        command => "_search",

        uri_param => { search_type => "dfs_query_then_fetch" },
        body => {
            query => { match => { "body" => "cpan" } }
        }
    });

    if ($status eq "200") {
        for my $hit (@{ $response->{hits}{hits} }) {
            say $hit->{url};
        }
    }

# DESCRIPTION

Elastijk is a Elasticsearch client library. It uses [Hijk](https://metacpan.org/pod/Hijk), a HTTP client that
implements a tiny subset of HTTP/1.1 just enough to talk to Elasticsearch via
HTTP.

Elastijk provided low-level functions that are almost identical as using HTTP
client, and an object-oriented sugar layer to make it a little bit easier to
use. The following documentation describe the low-level function first.

# FUNCTIONS

## Elastijk::request( $args :HashRef ) : ($status :Int, $response :HashRef)

Making a request to the Elasticsearch server specified in `$args`. It returns 2
values. `$status` is the HTTP status code of the response, and the `$response`
decoded as HashRef. Elasticsearch API always respond a single HashRef as JSON
text, this might or might not be changed in the future, if it is changed then
this function will be adjusted accordingly.

The `$args` is a HashRef takes contains the following key-value pairs:

    host  => Str
    port  => Str
    index => Str
    type  => Str
    id    => Str
    command => Str
    uri_param => HashRef
    body  => HashRef | ArrayRef | Str
    method => "GET" | "POST" | "HEAD" | "PUT" | "DELETE"

The 4 values of `index`, `type`, `id`, `command` are used to form the URI
path following Elasticsearch's routing convention:

    /${index}/${type}/${id}/${command}

All these path parts are optional, when that is the case, Elstaijk properly
remove `/` in between to form the URL that makes sense, for example:

    /${index}/${type}/${id}
    /${index}/${command}

The value of `uri_param` is used to form the query\_string part in the URI, some
common ones for Elasticsearch are `q`, `search_type`, and `timeout`.  But the
accepted list is different for different commands.

The value of `method` corresponds to HTTP verbs, and is hard-coded to match
Elasticsearch API. Users generally do not need to provide this value, unless you
are calling `request` directly, in which case, the default value is 'GET'.

For all cases, Elastijk simply bypass the value it receive to the server without
doing any parameter validation. If that generates some errors, it'll be on
server side.

## Elastijk::request\_raw( $args :HashRef ) : ($status :Int, $response :Str)

Making a request to the Elasticsearch server specified in `$args`. The main
difference between this function and `Elastijk::request` is that
`$args-`{body}> s expected to be a String scalar, rather then a HashRef. And
the $response is not decoded from JSON. This function can be used if users wish
to use their own JSON parser to parse response, or if they wish to delay the
parsing to be done latter in some bulk-processing pipeline.

# OBJECT

## PROPERTIES

An Elastijk object is constructed like this:

    my $es = Elastijk->new(
        host => "es1.example.com",
        port => "9200"
    );

Under the hood, it is only a blessed hash, while all key-value pairs in the hash
are the properties. Users could break the packaging and modify those values, but
it is fine. All key-value pairs are shallow-copied from \`new\` method.

Here's a full list of key-value pairs that are consumed:

    host  => Str "localhost"
    port  => Str "9200"
    index => Str (optional)
    type  => Str (optional)

The values for `index` and `type` act like a "default" value and they are only
used in methods that could use them. Which is handy to save some extra typing.
Given objects constructed with different default of `index` attribute:

    $es0 = Elastijk->new();
    $es1 = Elastijk->new( index => "foo" );

... calling the same `search` method with the same arguments will generate
different request:

    my @args = (uri_param => { q => "nihao" });
    $es0->search( @args  ); # GET /_search?q=nihao
    $es1->search( @args  ); # GET /foo/_search?q=nihao

This behavior is consistent for all methods.

# METHODS

All methods takes the same key-value pair HashRef as
`Elastijk::request` function, and returns 2 values that are HTTP
status code, and the body hashref. The boilerplate of checking the
return values is something like:

    my ($status, $res) = $es->search(...);
    if (substr($status,0,1) eq '2') { # 2xx = successful
        ... $res->{hits} ...
    }

The `$res` contains the parsed response and it should be always a
HashRef, but it may be an ArrayRef. Elasticsearch server mostly
respond with a HTTP Body that is a valid JSON document -- but some
past version of Elasticsearch does not always follow that convention in
some APIs. Please consult the Elasticsearch API document link for the
hints of value type. Elastijk is a thin client, and that means itself
only assumes Elasticsearch servers response back with a valid JSON