Search::Elasticsearch::Client::2_0::Direct - Thin client with full support for Elasticsearch 2.x APIs
version 2.01
Create a client:
use Search::Elasticsearch; my $e = Search::Elasticsearch->new( client => '2_0::Direct' );
Index a doc:
$e->index( index => 'my_index', type => 'blog_post', id => 123, body => { title => "Elasticsearch clients", content => "Interesting content...", date => "2013-09-23" } );
Get a doc:
$e->get( index => 'my_index', type => 'my_type', id => 123 );
Search for docs:
$results = $e->search( index => 'my_index', body => { query => { match => { title => "elasticsearch" } } } );
Index-level requests:
$e->indices->create( index => 'my_index' ); $e->indices->delete( index => 'my_index' )
Cluster-level requests:
$health = $e->cluster->health;
Node-level requests:
$info = $e->nodes->info; $stats = $e->nodes->stats;
Snapshot and restore:
$e->snapshot->create_repository( repository => 'my_backups', type => 'fs', settings => { location => '/mnt/backups' } ); $e->snapshot->create( repository => 'my_backups', snapshot => 'backup_2014' );
Task management:
$e->tasks->list;
`cat` debugging:
say $e->cat->allocation; say $e->cat->health;
The Search::Elasticsearch::Client::2_0::Direct class provides a client compatible with the as-yet-unreleased version 2.x of Elasticsearch.
$e = Search::Elasticsearch->new( client => "2_0::Direct" );
It is intended to be as close as possible to the native REST API that Elasticsearch uses, so that it is easy to translate the Elasticsearch reference documentation for an API to the equivalent in this client.
This class provides the methods for document CRUD, bulk document CRUD and search. It also provides access to clients for managing indices and the cluster.
This version of the client supports the Elasticsearch 2.0 branch, which is not backwards compatible with the 1.x and 0.90 branch.
If you need to talk to a version of Elasticsearch before 2.0.0, please use Search::Elasticsearch::Client::1_0::Direct or Search::Elasticsearch::Client::0_90::Direct as follows:
$es = Search::Elasticsearch->new( client => '1_0::Direct' # or '0_90::Direct' );
Parameters can be passed to any request method as a list or as a hash reference. The following two statements are equivalent:
$e->search( size => 10 ); $e->search({size => 10});
Any values that should be included in the URL path, eg /{index}/{type} should be passed as top level parameters:
/{index}/{type}
$e->search( index => 'my_index', type => 'my_type' );
Alternatively, you can specify a path parameter directly:
path
$e->search( path => '/my_index/my_type' );
Any values that should be included in the query string should be passed as top level parameters:
$e->search( size => 10 );
If you pass in a \%params hash, then it will be included in the query string parameters without any error checking. The following:
\%params
$e->search( size => 10, params => { from => 5, size => 5 })
would result in this query string:
?from=5&size=10
The request body should be passed in the body key:
body
$e->search( body => { query => {...} } );
The body can also be a UTF8-decoded string, which will be converted into UTF-8 bytes and passed as is:
$e->indices->analyze( body => "The quick brown fox");
Any API which returns a JSON body accepts a filter_path parameter which will filter the JSON down to only the specified paths. For instance, if you are running a search request and only want the total hits and the _source field for each hit (without the _id, _index etc), you can do:
filter_path
total
_source
_id
_index
$e->search( query => {...}, filter_paths => [ 'hits.total', 'hits.hits._source' ] );
Normally, any HTTP status code outside the 200-299 range will result in an error being thrown. To suppress these errors, you can specify which status codes to ignore in the ignore parameter.
ignore
$e->indices->delete( index => 'my_index', ignore => 404 );
This is most useful for Missing errors, which are triggered by a 404 status code when some requested resource does not exist.
404
Multiple error codes can be specified with an array:
$e->indices->delete( index => 'my_index', ignore => [404,409] );
bulk_helper_class
The class to use for the "bulk_helper()" method. Defaults to Search::Elasticsearch::Bulk.
scroll_helper_class
The class to use for the "scroll_helper()" method. Defaults to Search::Elasticsearch::Scroll.
info()
$info = $e->info
Returns information about the version of Elasticsearch that the responding node is running.
ping()
$e->ping
Pings a node in the cluster and returns 1 if it receives a 200 response, otherwise it throws an error.
1
200
indices()
$indices_client = $e->indices;
Returns an Search::Elasticsearch::Client::2_0::Direct::Indices object which can be used for managing indices, eg creating, deleting indices, managing mapping, index settings etc.
cluster()
$cluster_client = $e->cluster;
Returns an Search::Elasticsearch::Client::2_0::Direct::Cluster object which can be used for managing the cluster, eg cluster-wide settings and cluster health.
nodes()
$node_client = $e->nodes;
Returns an Search::Elasticsearch::Client::2_0::Direct::Nodes object which can be used to retrieve node info and stats.
snapshot()
$snapshot_client = $e->snapshot;
Returns an Search::Elasticsearch::Client::2_0::Direct::Snapshot object which is used for managing backup repositories and creating and restoring snapshots.
tasks()
$tasks_client = $e->tasks;
Returns an Search::Elasticsearch::Client::2_0::Direct::Tasks object which is used for accessing the task management API.
cat()
$cat_client = $e->cat;
Returns an Search::Elasticsearch::Client::2_0::Direct::Cat object which can be used to retrieve simple to read text info for debugging and monitoring an Elasticsearch cluster.
These methods allow you to perform create, index, update and delete requests for single documents:
index()
$response = $e->index( index => 'index_name', # required type => 'type_name', # required id => 'doc_id', # optional, otherwise auto-generated body => { document } # required );
The index() method is used to index a new document or to reindex an existing document.
Query string parameters: consistency, op_type, parent, refresh, routing, timeout, timestamp, ttl, version, version_type
consistency
op_type
parent
refresh
routing
timeout
timestamp
ttl
version
version_type
See the index docs for more information.
create()
$response = $e->create( index => 'index_name', # required type => 'type_name', # required id => 'doc_id', # optional, otherwise auto-generated body => { document } # required );
The create() method works exactly like the "index()" method, except that it will throw a Conflict error if a document with the same index, type and id already exists.
Conflict
index
type
id
See the create docs for more information.
get()
$response = $e->get( index => 'index_name', # required type => 'type_name', # required id => 'doc_id', # required );
The get() method will retrieve the document with the specified index, type and id, or will throw a Missing error.
Missing
Query string parameters: _source, _source_exclude, _source_include, fields, parent, preference, realtime, refresh, routing, version, version_type
_source_exclude
_source_include
fields
preference
realtime
See the get docs for more information.
get_source()
$response = $e->get_source( index => 'index_name', # required type => 'type_name', # required id => 'doc_id', # required );
The get_source() method works just like the "get()" method except that it returns just the _source field (the value of the body parameter in the "index()" method) instead of returning the _source field plus the document metadata, ie the _index, _type etc.
_type
Query string parameters: _source, _source_exclude, _source_include, parent, preference, realtime, refresh, routing, version, version_type
See the get_source docs for more information.
exists()
$response = $e->exists( index => 'index_name', # required type => 'type_name', # required id => 'doc_id', # required );
The exists() method returns 1 if a document with the specified index, type and id exists, or an empty string if it doesn't.
Query string parameters: parent, preference, realtime, refresh, routing
See the exists docs for more information.
delete()
$response = $e->delete( index => 'index_name', # required type => 'type_name', # required id => 'doc_id', # required );
The delete() method will delete the document with the specified index, type and id, or will throw a Missing error.
Query string parameters: consistency, parent, refresh, routing, timeout, version, version_type
See the delete docs for more information.
update()
$response = $e->update( index => 'index_name', # required type => 'type_name', # required id => 'doc_id', # required body => { update } # required );
The update() method updates a document with the corresponding index, type and id if it exists. Updates can be performed either by:
providing a partial document to be merged in to the existing document:
$response = $e->update( ..., body => { doc => { new_field => 'new_value'}, } );
with an inline script:
$response = $e->update( ..., body => { script => { inline => "ctx._source.counter += incr", params => { incr => 5 } } } );
Make sure you enable dynamic scripting and know its implications.
with an indexed script:
$response = $e->update( ..., body => { script => { id => $id, params => { incr => 5 } } } );
See indexed scripts for more information.
with a script stored as a file:
$response = $e->update( ..., body => { script => { file => 'counter', lang => 'groovy', params => { incr => 5 } } } );
See scripting docs for more information.
Query string parameters: consistency, detect_noop, fields, lang, parent, realtime, refresh, retry_on_conflict, routing, script, script_id, scripted_upsert, timeout, timestamp, ttl, version, version_type
detect_noop
lang
retry_on_conflict
script
script_id
scripted_upsert
See the update docs for more information.
termvectors()
$results = $e->termvectors( index => $index, # required type => $type, # required id => $id, # optional body => {...} # optional )
The termvectors() method retrieves term and field statistics, positions, offsets and payloads for the specified document, assuming that termvectors have been enabled.
Query string parameters: dfs, field_statistics, fields, offsets, parent, payloads, positions, preference, realtime, routing, term_statistics, version, version_type
dfs
field_statistics
offsets
payloads
positions
term_statistics
See the termvector docs for more information.
The bulk document CRUD methods are used for running multiple CRUD actions within a single request. By reducing the number of network requests that need to be made, bulk requests greatly improve performance.
bulk()
$response = $e->bulk( index => 'index_name', # required if type specified type => 'type_name', # optional body => [ actions ] # required );
See Search::Elasticsearch::Bulk and "bulk_helper()" for a helper module that makes bulk indexing simpler to use.
The bulk() method can perform multiple "index()", "create()", "delete()" or "update()" actions with a single request. The body parameter expects an array containing the list of actions to perform.
An action consists of an initial metadata hash ref containing the action type, plus the associated metadata, eg :
{ delete => { _index => 'index', _type => 'type', _id => 123 }}
The index and create actions then expect a hashref containing the document itself:
create
{ create => { _index => 'index', _type => 'type', _id => 123 }}, { title => "A newly created document" }
And the update action expects a hashref containing the update commands, eg:
update
{ update => { _index => 'index', _type => 'type', _id => 123 }}, { script => "ctx._source.counter+=1" }
Each action can include the same parameters that you would pass to the equivalent "index()", "create()", "delete()" or "update()" request, except that _index, _type and _id must be specified with the preceding underscore. All other parameters can be specified with or without the underscore.
For instance:
$response = $e->bulk( index => 'index_name', # default index name type => 'type_name', # default type name body => [ # create action { create => { _index => 'not_the_default_index', _type => 'not_the_default_type', _id => 123 }}, { title => 'Foo' }, # index action { index => { _id => 124 }}, { title => 'Foo' }, # delete action { delete => { _id => 125 }}, # update action { update => { _id => 126 }}, { script => "ctx._source.counter+1" } ] );
Each action is performed separately. One failed action will not cause the others to fail as well.
Query string parameters: consistency, fields, refresh, routing, timeout
See the bulk docs for more information.
bulk_helper()
$bulk_helper = $e->bulk_helper( @args );
Returns a new instance of the class specified in the "bulk_helper_class", which defaults to Search::Elasticsearch::Bulk.
mget()
$results = $e->mget( index => 'default_index', # optional, required when type specified type => 'default_type', # optional body => { docs or ids } # required );
The mget() method will retrieve multiple documents with a single request. The body consists of an array of documents to retrieve:
$results = $e->mget( index => 'default_index', type => 'default_type', body => { docs => [ { _id => 1}, { _id => 2, _type => 'not_the_default_type' } ] } );
You can also pass any of the other parameters that the "get()" request accepts.
If you have specified an index and type, you can just include the ids of the documents to retrieve:
ids
$results = $e->mget( index => 'default_index', type => 'default_type', body => { ids => [ 1, 2, 3] } );
Query string parameters: _source, _source_exclude, _source_include, fields, preference, realtime, refresh
See the mget docs for more information.
mtermvectors()
$results = $e->mtermvectors( index => $index, # required if type specified type => $type, # optional body => { } # optional )
Runs multiple "termvector()" requests in a single request, eg:
$results = $e->mtermvectors( index => 'test', body => { docs => [ { _type => 'test', _id => 1, fields => ['text'] }, { _type => 'test', _id => 2, payloads => 1 }, ] } );
Query string parameters: field_statistics, fields, ids, offsets, parent, payloads, positions, preference, realtime, routing, term_statistics, version, version_type
See the mtermvectors docs for more information.
The search methods are used for querying documents in one, more or all indices and of one, more or all types:
search()
$results = $e->search( index => 'index' | \@indices, # optional type => 'type' | \@types, # optional body => { search params } # optional );
The search() method searches for matching documents in one or more indices. It is just as easy to search a single index as it is to search all the indices in your cluster. It can also return aggregations highlighted snippets and did-you-mean or search-as-you-type suggestions.
The lite version of search allows you to specify a query string in the q parameter, using the Lucene query string syntax:
q
$results = $e->search( q => 'title:(elasticsearch clients)');
However, the preferred way to search is by using the Query DSL to create a query, and passing that query in the request body:
query
$results = $e->search( body => { query => { match => { title => 'Elasticsearch clients'} } } );
Query string parameters: _source, _source_exclude, _source_include, allow_no_indices, analyze_wildcard, analyzer, default_operator, df, expand_wildcards, explain, fielddata_fields, fields, from, ignore_unavailable, lenient, lowercase_expanded_terms, preference, q, request_cache, routing, scroll, search_type, size, sort, stats, suggest_field, suggest_mode, suggest_size, suggest_text, terminate_after, timeout, track_scores, version
allow_no_indices
analyze_wildcard
analyzer
default_operator
df
expand_wildcards
explain
fielddata_fields
from
ignore_unavailable
lenient
lowercase_expanded_terms
request_cache
scroll
search_type
size
sort
stats
suggest_field
suggest_mode
suggest_size
suggest_text
terminate_after
track_scores
See the search reference for more information.
Also see "send_get_body_as" in Search::Elasticsearch::Transport.
search_exists()
The search_exists() method is a quick version of search which can be used to find out whether there are matching search results or not. It doesn't return any results itself.
$results = $e->search_exists( index => 'index' | \@indices, # optional type => 'type' | \@types, # optional body => { search params } # optional );
Query string parameters: allow_no_indices, analyze_wildcard, analyzer, default_operator, df, expand_wildcards, ignore_unavailable, lenient, lowercase_expanded_terms min_score, preference, q, routing
min_score
See the search exists reference for more information.
count()
$results = $e->count( index => 'index' | \@indices, # optional type => 'type' | \@types, # optional body => { query } # optional )
The count() method returns the total count of all documents matching the query:
$results = $e->count( body => { query => { match => { title => 'Elasticsearch clients' } } } );
See the count docs for more information.
search_template()
$results = $e->search_template( index => 'index' | \@indices, # optional type => 'type' | \@types, # optional body => { search params } # optional );
Perform a search by specifying a template (either predefined or defined within the body) and parameters to use with the template, eg:
$results = $e->search_template( body => { inline => { query => { match => { "{{my_field}}" => "{{my_value}}" } }, size => "{{my_size}}" }, params => { my_field => 'foo', my_value => 'bar', my_size => 5 } } );
See the search template docs for more information.
Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable, preference, scroll, search_type
render_search_template()
$response = $e->render_search_template( id => 'id', # optional body => { template } # optional );
Renders the template, filling in the passed-in parameters and returns the resulting JSON, eg:
$results = $e->render_search_template( body => { inline => { query => { match => { "{{my_field}}" => "{{my_value}}" } }, size => "{{my_size}}" }, params => { my_field => 'foo', my_value => 'bar', my_size => 5 } } );
scroll()
$results = $e->scroll( scroll => '1m', scroll_id => $id );
When a "search()" has been performed with the scroll parameter, the scroll() method allows you to keep pulling more results until the results are exhausted.
NOTE: you will almost always want to set the search_type to scan in your original search() request.
scan
See "scroll_helper()" and Search::Elasticsearch::Scroll for a helper utility which makes managing scroll requests much easier.
Query string parameters: scroll, scroll_id
scroll_id
See the scroll docs and the search_type docs for more information.
clear_scroll()
$response = $e->clear_scroll( scroll_id => $id | \@ids # required );
Or
$response = $e->clear_scroll( body => $id );
The clear_scroll() method can clear unfinished scroll requests, freeing up resources on the server.
scroll_helper()
$scroll_helper = $e->scroll_helper( @args );
Returns a new instance of the class specified in the "scroll_helper_class", which defaults to Search::Elasticsearch::Scroll.
msearch()
$results = $e->msearch( index => 'default_index' | \@indices, # optional type => 'default_type' | \@types, # optional body => [ searches ] # required );
The msearch() method allows you to perform multiple searches in a single request. Similar to the "bulk()" request, each search request in the body consists of two hashes: the metadata hash then the search request hash (the same data that you'd specify in the body of a "search()" request). For instance:
$results = $e->msearch( index => 'default_index', type => ['default_type_1', 'default_type_2'], body => [ # uses defaults {}, { query => { match_all => {} }}, # uses a custom index { index => 'not_the_default_index' }, { query => { match_all => {} }} ] );
Query string parameters: search_type
See the msearch docs for more information.
explain()
$response = $e->explain( index => 'my_index', # required type => 'my_type', # required id => 123, # required body => { search } # required );
The explain() method explains why the specified document did or did not match a query, and how the relevance score was calculated. For instance:
$response = $e->explain( index => 'my_index', type => 'my_type', id => 123, body => { query => { match => { title => 'Elasticsearch clients' } } } );
Query string parameters: _source, _source_exclude, _source_include, analyze_wildcard, analyzer, default_operator, df, fields, lenient, lowercase_expanded_terms, parent, preference, q, routing
See the explain docs for more information.
field_stats()
$response = $e->field_stats( index => 'index' | \@indices, # optional fields => 'field' | \@fields, # optional level => 'cluster' | 'indices', # optional body => { filters } # optional );
The field-stats API returns statistical properties of a field (such as min and max values) without executing a search.
field-stats
Query string parameters: allow_no_indices, expand_wildcards, fields, ignore_unavailable, level
level
See the field-stats docs for more information.
search_shards()
$response = $e->search_shards( index => 'index' | \@indices, # optional type => 'type' | \@types, # optional )
The search_shards() method returns information about which shards on which nodes will execute a search request.
Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable, local, preference, routing
local
See the search-shards docs for more information.
delete_by_query()
$response = $e->delete_by_query( index => 'index' | \@indices, # optional type => 'type' | \@types, # optional, body => { delete-by-query } # optional );
The delete_by_query() method (available with the delete-by-query plugin) deletes all documents which match the specified query.
Query string parameters: allow_no_indices, analyzer, default_operator, df, expand_wildcards, filter_path, ignore_unavailable, q, routing, timeout
See the delete-by-query docs for more information.
reindex()
$response = $e->reindex( body => { reindex } # required );
The reindex() API is used to index documents from one index or multiple indices to a new index.
Query string parameters: consistency, refresh, timeout, wait_for_completion
wait_for_completion
See the reindex docs for more information.
update_by_query()
$response = $e->update_by_query( index => 'index' | \@indices, # optional type => 'type' | \@types, # optional, body => { update-by-query } # optional );
The update_by_query() API is used to bulk update documents from one index or multiple indices using a script.
Query string parameters: _source, _source_exclude, _source_include, allow_no_indices, analyze_wildcard, analyzer, conflicts, consistency, default_operator, df, expand_wildcards, explain, fielddata_fields, fields, from, ignore_unavailable, lenient, lowercase_expanded_terms, preference, q, refresh, request_cache, routing, scroll, scroll_size, search_timeout, search_type, size, sort, stats, suggest_field, suggest_mode, suggest_size, suggest_text, terminate_after, timeout, track_scores, version, version_type, wait_for_completion
conflicts
scroll_size
search_timeout
See the update_by_query docs for more information.
percolate()
$results = $e->percolate( index => 'my_index', # required type => 'my_type', # required body => { percolation } # required );
Percolation is search inverted: instead of finding docs which match a particular query, it finds queries which match a particular document, eg for alert-me-when functionality.
The percolate() method runs a percolation request to find the queries matching a particular document. In the body you should pass the _source field of the document under the doc key:
doc
$results = $e->percolate( index => 'my_index', type => 'my_type', body => { doc => { title => 'Elasticsearch rocks' } } );
Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable, percolate_format, percolate_index, percolate_preference, percolate_routing, percolate_type, preference, routing, version, version_type
percolate_format
percolate_index
percolate_preference
percolate_routing
percolate_type
See the percolate docs for more information.
count_percolate()
$results = $e->count_percolate( index => 'my_index', # required type => 'my_type', # required body => { percolation } # required );
The "count_percolate()" request works just like the "percolate()" request except that it returns a count of all matching queries, instead of the queries themselves.
$results = $e->count_percolate( index => 'my_index', type => 'my_type', body => { doc => { title => 'Elasticsearch rocks' } } );
Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable, percolate_index, percolate_type, preference, routing, version, version_type
mpercolate()
$results = $e->mpercolate( index => 'my_index', # required if type type => 'my_type', # optional body => [ percolation requests ] # required );
Multi-percolation allows multiple "percolate()" requests to be run in a single request.
$results = $e->mpercolate( index => 'my_index', type => 'my_type', body => [ # first request { percolate => { index => 'twitter', type => 'tweet' }}, { doc => {message => 'some_text' }}, # second request { percolate => { index => 'twitter', type => 'tweet', id => 1 }}, {}, ] );
Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable
See the mpercolate docs for more information.
suggest()
$results = $e->suggest( index => 'index' | \@indices, # optional body => { suggest request } # required );
The suggest() method is used to run did-you-mean or search-as-you-type suggestion requests, which can also be run as part of a "search()" request.
$results = $e->suggest( index => 'my_index', body => { my_suggestions => { phrase => { text => 'johnny walker', field => 'title' } } } );
Query string parameters: allow_no_indices, expand_wildcards, ignore_unavailable, preference, routing
If dynamic scripting is enabled, Elasticsearch allows you to store scripts in an internal index known as .scripts and reference them by id. The methods to manage indexed scripts are as follows:
.scripts
put_script()
$result = $e->put_script( lang => 'lang', # required id => 'id', # required body => { script } # required );
The put_script() method is used to store a script in the .scripts index. For instance:
$result = $e->put_scripts( lang => 'groovy', id => 'hello_world', body => { script => q(return "hello world"); } );
Query string parameters: op_type, version, version_type
See the indexed scripts docs for more.
get_script()
$script = $e->get_script( lang => 'lang', # required id => 'id', # required );
Retrieve the indexed script from the .scripts index.
Query string parameters: version, version_type
delete_script()
$script = $e->delete_script( lang => 'lang', # required id => 'id', # required );
Delete the indexed script from the .scripts index.
Mustache templates can be used to create search requests. These templates can be stored in the .scripts index and retrieved by ID. The methods to manage indexed scripts are as follows:
put_template()
$result = $e->put_template( id => 'id', # required body => { template } || "template" # required );
The put_template() method is used to store a template in the .scripts index. For instance:
$result = $e->put_template( id => 'hello_world', body => { template => { query => { match => { title => "hello world" } } } } );
Query string parameters: None
See the indexed search template docs for more.
get_template()
$script = $e->get_template( id => 'id', # required );
Retrieve the indexed template from the .scripts index.
delete_template()
$script = $e->delete_template( id => 'id', # required );
Delete the indexed template from the .scripts index.
Clinton Gormley <drtech@cpan.org>
This software is Copyright (c) 2016 by Elasticsearch BV.
This is free software, licensed under:
The Apache License, Version 2.0, January 2004
To install Search::Elasticsearch, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Search::Elasticsearch
CPAN shell
perl -MCPAN -e shell install Search::Elasticsearch
For more information on module installation, please visit the detailed CPAN module installation guide.