Banner

 

elasticsearch-js

Overview

Official low-level client for Elasticsearch. Its goal is to provide common ground for all Elasticsearch-related code in JavaScript; because of this it tries to be opinion-free and very extendable.

The full documentation is available at http://elasticsearch.github.io/elasticsearch-js

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 - for projects that already use jQuery
  • elasticsearch.angular.js - for Angular projects
  • elasticsearch.js - generic build for all other projects

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