elastica

Elastica

A flexible chaining API for ElasticSearch

Raison D'être

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.

Contents

Request

• Search
• Update
• Index
• Bulk

Response

• Raw
• Hits
• Value Aggregation
• Multi Value Aggregation
• Count Aggregation
• Multi Count Aggregation
• Aggregation Expression

Installation

npm install elastica

Usage

Initialization

Initialize Elastica with the config you'd typically use in the ES Javascript API.

var elastica = require('elastica')(config.es)

Requests

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.

#### Search

Used to make search queries. All search callbacks pass an Elastica Response Object.

Examples

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

Update works very much like search with three additional operations: doc, with, and withScript. Update's callback returns the raw elasticsearch reponse.

Examples

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

Index's callback returns the raw elasticsearch reponse.

Examples

Document Update

elastica.index
  .for('myDocType')
  .in('myIndex1')
  .doc({field: 'value')
  .id(docId) //optional
  .parent(parentId) //optional
  .exec(function(err, response) {})

#### Bulk

Bulk's only operation is add, which takes Elastica operations. Currently, only update operations are supported. Its callback also returns the raw elasticsearch response.

Examples

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) {})

Responses

The Elastica response object exists primarily to marshall relevant values from the elastic search response. It has the following properties:

#### Raw

A 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.
})

#### Hits

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

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__

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__

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 } }

__Multi Count Aggregations__

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 }

__Aggregation Expression__

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}}
// ]

What's next?

• Interface for building queries.
• Support for add operations
• Support for delete operations