elasticsearch/docs/javascript/index.asciidoc

= 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:

[source,sh]
------------------------------------
npm install elasticsearch
------------------------------------

=== Getting the browser client

For a browser-based projects, builds for modern browsers are available http://elasticsearch.github.io/elasticsearch-js#browser-builds[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 http://elasticsearch.github.io/elasticsearch-js/index.html#configuration[the configuration docs].

[source,javascript]
------------------------------------
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.

[source,javascript]
------------------------------------
// 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.

[source,javascript]
------------------------------------
// 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;
});
------------------------------------

== Copyright and License

This software is Copyright (c) 2013 by Elasticsearch BV.

This is free software, licensed under The Apache License Version 2.0.