A flexible chaining API for ElasticSearch
Elasticsearch is an amazing tool. However, we find that it's hard to maintain a clean service layer to handle your ES requests. This library aims to make it easier to send requests and marshall responses from ES. The current version focuses on querying and marshaling aggregations. We'd like to add more features as we or the community needs them.
- Raw
- Hits
- Value Aggregation
- Multi Value Aggregation
- Count Aggregation
- Multi Count Aggregation
- Aggregation Expression
npm install elastica
Initialize Elastica with the config you'd typically use in the ES Javascript API.
var elastica = require('elastica')(config.es)
Elastica uses a chained interface to simplify the creation of requests. Every function call returns a new request object. These objects are immutable, and can be saved and reused for convienience. Subsequent method calls will not change their state.
#### SearchUsed to make search queries. All search callbacks pass an Elastica Response Object.
Simple Search
The simple search uses for to describe the document type and in to describe the index range the search takes place in.
var query = '{"filter": { "term": { "field": "searchValue"} } }'
elastica.search
.for('myDocType')
.in('myIndex1,myIndex2')
.exec(query, function(err, response) {
})
Search With Compile
Compiled templates use erb syntax to build the search query.
var template = '{"filter": { "term": { "field": "<%= myField %>"} } }'
elastica.search
.for('myDocType')
.in('myIndex1,myIndex2')
.compile(template)
.exec({myField: 'searchValue'},function(err, response) {
})
Request Reuse
var template = '{"filter": { "term": { "field": "<%= myField %>"} } }'
var search = elastica.search.for('myDocType').compile(template)
search.in('myIndex1').exec({myField: 'searchValue1'},function(err, response) {})
search.in('myIndex2').exec({myField: 'searchValue2'},function(err, response) {})
Search Options
Search takes an optional parameter that is passed to ES API, in order to qualify the search. In the following example we pass search_type and ignore_unavailable optional parameters to Elasticsearch.
var template = '{"filter": { "term": { "field": "<%= myField %>"} } }'
elastica.search
.for('myDocType')
.in('myIndex1,myIndex2')
.compile(template)
.exec({myField: 'searchValue'}, {
search_type: 'count',
ignore_unavailable: true
}, function(err, response) {
})
Update works very much like search with three additional operations: doc, with, and withScript. Update's callback returns the raw elasticsearch reponse.
Document Update
elastica.update
.for('myDocType')
.in('myIndex1')
.doc('documentId')
.with({updateField: 'updateValue'})
.exec(function(err, response) {})
Script Update
elastica.update
.for('myDocType')
.in('myIndex1')
.doc('documentId')
.withScript('scriptNameOrContents', {scriptParam1: 'scriptValue1'})
.exec(function(err, response) {})
Index's callback returns the raw elasticsearch reponse.
Document Update
elastica.index
.for('myDocType')
.in('myIndex1')
.doc({field: 'value')
.id(docId) //optional
.parent(parentId) //optional
.exec(function(err, response) {})
Bulk's only operation is add, which takes Elastica operations. Currently, only update operations are supported. Its callback also returns the raw elasticsearch response.
var update = elastica.update.for('myDocType').in('myIndex1')
elastica.bulk
.add(update.doc('document1').with({update: 'value1'}))
.add(update.doc('document2').with({update: 'value2'}))
.exec(function(err, response) {})
// *Add* can also take an array of operations.
// The code below is equivalent to the code above.
elastica.bulk
.add([
update.doc('document1').with({update: 'value1'}),
update.doc('document2').with({update: 'value2'})
]).exec(function(err, response) {})
The Elastica response object exists primarily to marshall relevant values from the elastic search response. It has the following properties:
#### RawA field containing the raw response from elasticsearch.
elastica.search.exec(query, function(err, res) {
console.dir(res.raw) // This will print the unmodified response body.
})
A function that returns the array of documents retrieved.
elastica.search.exec(query, function(err, res) {
console.dir(res.hits()) // This will print the documents returned.
})
Aggs is an object that provides functions to pull relevant data from the aggregations portion of the Elasticsearch response. There are four types of Elastica aggregations which map to ES aggregations.
__Value Aggregations__Value aggregations map to the avg, sum, max, and min elasticsearch aggregations. The return value will be a key/value pair where the key is the aggregation name and the value is the aggregation value.
// Elasticsearch response is:
// { aggregations: { totalSales: { value: 400 } } }
res.aggs.sum('totalSales') //Returns { totalSales: 400 }
Multi value aggregations map to the percentiles elasticsearch aggregation.
// Elasticsearch response is:
// { aggregations: { salesPercentages: { values: { 25: 100, 50: 350, 75: 450 } } } }
res.aggs.percentiles('salesPercentages')
// Returns { salesPercentages: { 25: 100, 50: 350, 75: 450 } }
res.aggs.percentiles('salesPercentages', {asArray: true})
// Returns
// {
// salesPercentages: [
// {key: 25, value: 100},
// {key: 50, value: 350},
// {key: 75, value: 450}
// ]
// }
Count aggregations map to the nested and filtered elasticsearch aggregations.
// Elasticsearch response is:
// { aggregations: { highValuedSales: { doc_count: 500 } }
res.aggs.filter('highValuedSales')
// Returns { highValuedSales: { count: 500 } }
Count aggregations map to the ranges, terms, histogram, and geohashGrid elasticsearch aggregations.
// Elasticsearch response is:
// {
// aggregations: {
// name: { buckets: [{key: 'Alice', doc_count: 100}, {key: 'Bob', doc_count: 200}]
// }
// }
res.aggs.terms('name')
// Returns [{name: 'Alice', count: 100}, {name: 'Bob', count: 200}]
aggs.terms('artists', {with: 'range[transactions.revenue sales]'}
Dot notation
If you have deeply nested single count aggregations, you can use dot notation to access deeply nested child values.
// Elasticsearch response is:
// {
// aggregations: {
// successfulTransactions: {
// doc_count: 500, highValued: { doc_count: 100, grossRevenue: {value: 1000000 } }
// }
// }
// }
res.aggs.sum('successfulTransactions.highValued.grossRevenue')
// Returns { grossRevenue: 10000000 }
Aggregations can also be built from an aggregation expression. This allows quick and easy access for multiple aggregations at different levels of the response body. An expression can also be passed into Count and Multicount aggs as the with option in the second parameter.
Subaggregation expressions follow the EBNF grammar below:
expression = {subagg}
subagg = [type:]name[buckets]
buckets = "["{subagg}"]"
// Elasticsearch response is:
// aggregations: {
// name: {
// buckets: [
// {
// key: "Alice",
// doc_count: 300,
// conversionRate: { value: 0.56 },
// transactions: {
// doc_count: 200,
// highValued: { value: 68 }
// }
// },
// {
// key: "Bob",
// doc_count: 200,
// conversionRate: { value: 0.78 },
// transactions: {
// doc_count: 350,
// highValued: { value: 42 }
// }
// }
// ]
// }
// }
res.aggs.fromExpression('name[nested:transactions conversionRate transactions.highValued]')
// Returns
// {
// names: [
// {name: "Alice", total: 300, conversionRate: 0.56, highValued: 68, transactions: {total: 200}},
// {name: "Bob", total: 200, conversionRate: 0.78, highValued: 42, transactions: {total: 350}}
// ]
// }
res.aggs.multiCount('name', {with: 'nested:transactions conversionRate transactions.highValued'})
// Returns [
// {name: "Alice", total: 300, conversionRate: 0.56, highValued: 68, transactions: {total: 200}},
// {name: "Bob", total: 200, conversionRate: 0.78, highValued: 42, transactions: {total: 350}}
// ]
- Interface for building queries.
- Support for add operations
- Support for delete operations