Skip to content

Commit

Permalink
documents
Browse files Browse the repository at this point in the history
  • Loading branch information
@gugod
gugod committed May 12, 2014
1 parent 212b9c6 commit 5b6fe14
Showing 1 changed file with 106 additions and 55 deletions.
161 changes: 106 additions & 55 deletions lib/Elastijk.pm
View file
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,8 @@ sub new {

1;

__END__
=encoding utf-8
=head1 NAME
Expand Down Expand Up @@ -97,10 +99,65 @@ 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 object-oriented uses first, then
the functions.
use. The following documentation describe the low-level function first.
=head1 FUNCTIONS
=head2 Elastijk::request( $args :HashRef ) : ($status :Int, $response :HashRef)
Making a request to the ElasticSearch server specified in C<$args>. It returns 2
values. C<$status> is the HTTP status code of the response, and the C<$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 C<$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 C<index>, C<type>, C<id>, C<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 C</> in between to form the URL that makes sense, for example:
/${index}/${type}/${id}
/${index}/${command}
The value of C<uri_param> is used to form the query_string part in the URI, some
common ones for ElasticSearch are C<q>, C<search_type>, and C<timeout>. But the
accepted list is different for different commands.
The value of C<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 C<request> directly, in which case, the default value is 'GET'.
For all cases, Elastijk simply bypass the value it recieve to the server without
doing any parameter validation. If that generates some errors, it'll be on
server side.
=head2 Elastijk::request_raw( $args :HashRef ) : ($status :Int, $response :Str)
Making a request to the ElasticSearch server specified in C<$args>. The main
difference between this function and C<Elastijk::request> is that
C<$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.
=head1 OBJECT
=head2 OBJECT PROPERTIES
=head2 PROPERTIES
An Elastijk object is constructed like this:
Expand All @@ -121,54 +178,60 @@ Here's a full list of key-value pairs that are consumed:
type => Str (optional)
The values for C<index> and C<type> act like a "default" value and they are only
used in methods that could use them.
used in methods that could use them. Which is handy to save some extra typing.
Given objects constructed with different default of C<index> attribute:
=head1 OBJECT METHODS
$es0 = Elastijk->new();
$es1 = Elastijk->new( index => "foo" );
All methods takes these key-value pairs
... calling the same C<search> method with the same arugments will generate
different request:
host => Str
port => Str
index => Str
type => Str
id => Str
command => Str
uri_param => HashRef
body => HashRef | ArrayRef | Str
The 4 values of C<index>, C<type>, C<id>, C<command> are used to form the URI
path following ElasticSearch's routing convention:
my @args = (uri_param => { q => "nihao" });
$es0->search( @args ); # GET /_search?q=nihao
$es1->search( @args ); # GET /foo/_search?q=nihao
/${index}/${type}/${id}/${command}
This behaviour is consistent for all methods.
All these path parts are optional, when that is the case, Elstaijk properly
remove C</> in between to form the URL that makes sense.
=head1 METHODS
/${index}/${type}/${id}
/${index}/${command}
All methods takes the same key-value pair HashRef as C<Elastijk::request> function,
and returns 2 values that are HTTP status code, and the body hashref.
Most of of methods are named after an server command. For eaxmple, the command
Many of of methods are named after an server command. For eaxmple, the command
C<_search> corresponds to method C<search>, the command C<_bulk> corresponds to
method C<bulk>.
Elastijk does as little data transformation as possible to keep it a
stupid, thin client.
All methods return 2 values that are HTTP status code string, and the body
hashref.
All methods return 2 values that are HTTP status code, and the body hashref:
my ($status, $res) = $es->search(...)
if ($status =~ /\A2/) { # successful
....
if (substr($status,0,1) eq '2') { # 2xx = successful
...
}
The status code is used for error-checking purposes. The C<exists> method
modifyed C<$res> to be a boolean to allow this intuitive uses:
The status code is used for error-checking purposes. ElastiSearch should respond
with status 4XX when the relevant thing is missing, and 5XX when there are some
sort of errors. To check if a request is successful, test if it is 200 or 201.
Due to the fact the value of a lists is the last value of element, it is a
little bit shorter if status check could be ignored:
if ($es->exists( ... )) {
....
my $res = $es->search(...);
for (@{ $res->{hits}hits} }) {
...
}
C<count> and C<exists> method modified C<$res> to be a scalar (instead of
HashRef) to allow these intuitive use cases:
if ($es->exists(...)) { ... }
if ($es->count(...) > 10) { ... }
... the original response body are discarded.
=head2 request( ... )
This is a low-level method that just bypass things, but it is useful when, say,
Expand All @@ -177,12 +240,21 @@ corresponding method in the Client yet. The only difference between using this
method and calling C<Elasijk::request> directly, is that the values of
C<host>,C<port>,C<index>, and <type> ind the object context are consumed.
=head2 search( ... )
=head2 head(...), get(...), put(...), post(...), delete(...)
Shorthands for the HTTP verbs. All these are just direct delegate to C<request>
method.
This method encapsulate <request body search|http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-request-body.html>
=head2 search( body => {...}, uri_param => {...} )
This method invokes L<the search api|http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-search.html>.
The arguments are key-value pairs from the API documents.
=head2 count( body => {...}, uri_param => {...} )
This method corresponds to L<the search count api|http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/search-count.html>
=head2 exists( index => Str, type => Str, id => Str )
Check if the given thing exists. Which can be a document, a type, and an index.
Expand All @@ -196,27 +268,6 @@ to check the existence of different things:
See also L<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-exists.html> ,
L<http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/indices-types-exists.html#indices-types-exists> , and L<http://www.elasticsearch.org/guide/en/elasticsearch/guide/current/doc-exists.html>
=head2 delete
=head1 FUNCTIONS
=head2 Elastijk::request( $args :HashRef ) : ($status :Int, $response :HashRef)
Making a request to the ElasticSearch server specified in C<$args>. It returns 2
values. C<$status> is the HTTP status code of the response, and the C<$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.
=head2 Elastijk::request_raw( $args :HashRef ) : ($status :Int, $response :Str)
Making a request to the ElasticSearch server specified in C<$args>. The main
difference between this function and C<Elastijk::request> is that
C<$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.
=head1 AUTHORS
=over 4
Expand All @@ -229,7 +280,7 @@ parsing to be done latter in some bulk-processing pipeline.
=head1 COPYRIGHT
Copyright (c) 2013 Kang-min Liu C<< <gugod@gugod.org> >>.
Copyright (c) 2013,2014 Kang-min Liu C<< <gugod@gugod.org> >>.
=head1 LICENCE
Expand Down

0 comments on commit 5b6fe14

Please sign in to comment.