view release on metacpan or  search on metacpan

README  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, 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.