Announcing Elasticsearch.js for Node.js and the Browser

By
Spencer Alger

A few months ago we released client libraries for PHP, Ruby, Python, and Perl and today we add another to the family, JavaScript! This new client runs in Node.js and modern browsers, and aims to solve the same problems that the others do:

  • provide access to the entire Elasticsearch REST API
  • play nice with clusters
  • automatically discover nodes when desired
  • intelligently handle node failure
  • be easily extendable, so that you can really have it behave just the way you want

If you didn’t know that we are developing our own clients you should check out this post from the first round of releases. In that post Clint explains why we decided to go down this road, as well as some of the goals of the project.

Just like our other clients, Elasticsearch.js is licensed under Apache 2.0 and hosted on Github. Getting started with Elasticsearch.js is almost easier than getting started with Elasticsearch itself.

Getting the Node.js module

To install the module into an existing Node.js project use npm:

npm install elasticsearch

Getting the browser client

For a browser-based projects, builds for modern browsers are available here. Download one of the archives, and extract it. Inside you’ll find three files, pick the one that best matches your environment:

  • elasticsearch.jquery.js – use this build if you are already using jQuery
  • elasticsearch.angular.js – use this build in Angular projects
  • elasticsearch.js – in all other cases, use this build

Each of the library specific builds tie into the AJAX and Promise creation facilities provided by their respective libraries. This is an example of how Elasticsearch.js can be extended to provide a more opinionated approach when appropriate.

Setting up the client

Now you are ready to get busy! First thing you’ll need to do is create an instance of elasticsearch.Client. Here are several examples of configuration parameters you can use when creating that instance. For a full list of configuration options see the configuration docs.

var elasticsearch = require('elasticsearch');

// Connect to localhost:9200 and use the default settings
var client = new elasticsearch.Client();

// Connect the client to two nodes, requests will be
// load-balanced between them using round-robin
var client = elasticsearch.Client({
  hosts: [
    'elasticsearch1:9200',
    'elasticsearch2:9200'
  ]
});

// Connect to the this host's cluster, sniff
// for the rest of the cluster right away, and
// again every 5 minutes
var client = elasticsearch.Client({
  host: 'elasticsearch1:9200',
  sniffOnStart: true,
  sniffInterval: 300000
});

// Connect to this host using https, basic auth,
// a path prefix, and static query string values
var client = new elasticsearch.Client({
  host: 'https://user:password@elasticsearch1/search?app=blog'
});

Setting up the client in the browser

The params accepted by the Client constructor are the same in the browser versions of the client, but how you access the Client constructor is different based on the build you are using. Below is an example of instantiating a client in each build.

// elasticsearch.js adds the elasticsearch namespace to the window
var client = elasticsearch.Client({ ... });

// elasticsearch.jquery.js adds the es namespace to the jQuery object
var client = jQuery.es.Client({ ... });

// elasticsearch.angular.js creates an elasticsearch
// module, which provides an esFactory
var app = angular.module('app', ['elasticsearch']);
app.service('es', function (esFactory) {
  return esFactory({ ... });
});

Using the client instance to make API calls.

Once you create the client, making API calls is simple.

// get the current status of the entire cluster.
// Note: params are always optional, you can just send a callback
client.cluster.health(function (err, resp) {
  if (err) {
    console.error(err.message);
  } else {
    console.dir(resp);
  }
});

// index a document
client.index({
  index: 'blog',
  type: 'post',
  id: 1,
  body: {
    title: 'JavaScript Everywhere!',
    content: 'It all started when...',
    date: '2013-12-17'
  }
}, function (err, resp) {
  // ...
});

// search for documents (and also promises!!)
client.search({
  index: 'users',
  size: 50,
  body: {
    query: {
      match: {
        profile: 'elasticsearch'
      }
    }
  }
}).then(function (resp) {
  var hits = resp.body.hits;
});

Entering Construction Zone

This release of Elasticsearch.js should be considered beta. Please install it, try it out and give us feedback. What doesn’t work? What is missing? What can we do better? We are excited to receive your issues and pull requests!

We will be actively working to squash bugs as soon as they pop-up, and plan to do a full performance audit (it’s quick already, but we want to be certain that it’s also efficient as possible). We are also interested in creating wrappers for this library which might include plugins for other ORM modules like Mongoose or Bookshelf, helpers for some of the more complex parts of the API. If you would like to see anything specific let us know in a Github issue!

Happy searching!