One-to-one mapping with REST API and other language clients
Generalized, pluggable architecture. See [replacing core components](TODO: details the peices that are replaceable)
Configurable, automatic discovery of cluster nodes
Persistent, Keep-Alive connections
Load balancing (with pluggable selection strategy) across all available nodes.

Node and the browser

elasticsearch.js works great in node, as well as modern browsers (many thanks to browserify!!).

Node:

Browsers (see browser builds):

Install in Node

npm install --save elasticsearch

Browser Builds

Download one of these browser-ready builds, or install them with bower

NOTE: The entire API is compatible with IE 10+, Chrome, Firefox, Safari, and Opera. IE 8 & 9 only support GET and POST requests cross-domain which is how the 'XhrConnection' class makes it's requests.

elasticsearch.js - dev
- uses the browser's native XMLHttpRequest object
- Node style callbacks or promises provided by when.js

bower install elasticsearch

elasticsearch.angular.js - dev
- Uses Angular's $http service
- Returns promises using Angular's $q service (Adds an abort() method)

bower install elasticsearch-angular

elasticsearch.jquery.js - dev
- Uses jQuery's .ajax() method
- Returns jQuery deferred objects (Adds an abort() method)

bower install elasticsearch-jquery

Configuration

The Client constructor accepts a single object as it's argument, and the following keys can be used to configure that client instance:

var elasticsearch = require('elasticsearch');
var es = new elasticsearch.Client({
  ...
});

### hosts
Type: `String`, `String[]` or `Object[]`

Default:
```js
hosts: [
  {
    host: 'localhost', port: '9200', protocol: 'http'
  }
]

Specify the list of hosts that this client will connect to. If sniffing is enabled, or you call sniff, this list will be used as seeds for discovery of the rest of the cluster.

log

Type: String, String[], Object, Object[], or Constructor

Default:

log: {
  type: 'stdio',
  levels: ['error', 'warning']
}

Unless a constructor is specified, this sets the output settings for the bundled logger. See [setting up logging](TODO: detail logging why) for more information.

connectionClass

Type: String, Constructor

Default:

Node: 'http'
Browser: 'xhr'
Angular Build: 'angular'
jQuery Build: 'jquery'

Defines the class that will be created once for each node/host that the client communicates with. If you are looking to implement a protocol besides HTTP you will probably start by writing a Connection class and specifying it here.

selector

Type: String, Function

Default: 'roundRobin'

Options:

'roundRobin'
'random'

This function will be used to select a connection from the ConnectionPool. It should received a single argument, the list of "active" connections, and return the connection to use. Use this selector to implement special logic for your client such as preferring nodes in a certain rack or data-center.

To make this function asynchronous, accept a second argument which will be the callback to use. The callback should be called Node-style, a possible error like cb(err, selectedConnection).

sniffOnStart

Type: Boolean

Default: false

Should the client attempt to detect the rest of the cluster when it is first instantiated?

sniffAfterRequests

Type: Number or false

Default: false

After n requests, perform a sniff operation and ensure out list of nodes is up to date.

sniffOnConnectionFail

Type: Boolean

Default: false

Should the client immediately sniff for a more current list of nodes when a connection dies? (see node death)

maxRetries

Type: Number

Defailt: 3

How many times should the client try to connect to other nodes before returning a [ConnectionFault](TODO: error types) error. (see node death)

timeout

Type: Number

Default: 10000

How many milliseconds can the connection take before the request is aborted and retried. (TODO: timeout errors shouldn't cause a retry).

deadTimeout

Type: Number

Default: 30000

How many milliseconds should a dead a connection/node sit and wait before it is ping-ed? (see node death)

maxSockets

Type: Number

Default: 10

How many sockets should a connection/node keep to the server? These sockets are currently kept alive forever (not like nodes current "keep alive" sockets).

nodesToHostCallback

Type: Function

Default: simple, not much going on here.

This function will receive a list of nodes received during a sniff. The list of nodes should be transformed into an array of objects which will be fed to the Host class. (TODO: allow this function to be async).

API

To maintain consistency across all the low-level clients (PHP, Python, Ruby, Perl), all API methods accept an object with parameters and a callback. If you don't pass the callback, the functions will return a promise.

Generic Params

Several parameters work on all API methods, and control the way that those requests are carried out:

ignore

Type: Number or Number[]

Default: null

Don't treat these HTTP status codes as "errors". Example use cases could be ignore: 404 or ignore: [404]

timeout

Type: Number

Default: client.config.timeout

The number of milliseconds this request has to complete. It defaults to the timeout specified at the client level, which defaults to 10 seconds.

Methods

All the methods can be seen [here](TODO: api docs), or take a look at api.js.

Examples

create the client

var es = new elasticsearch.Client({
  hosts: [
    'localhost:9200'
  ],
  log: 'trace',
  sniffOnStart: true
});

call an endpoint

es.cluster.nodeInfo({
  clear: true,
  jvm: true,
  os: ture
}, function (err, resp, status) {
    // do your thing
})

skip the callback to get a promise back

es.search({
  q: 'pants'
}).then(function (resp) {
  // use resp.body and resp.status
}, function (err) {
  // freak out!
})

abort a request

var req = es.search({
  q: 'robots'
}, function (err, body, status) {
  clearTimeout(timeout);
  // do something
});

var timeout = setTimeout(function () {
  req.abort();
}, 200);

or just use the timeout param

es.search({
  q: '*',
  timeout: 200
}).then(function (resp) {
  // Iterate all the hits
})

FAQ

dead nodes

Q: When is a connection/node considered dead?

A; A connection is considered dead when a request to it does not complete properly. If the server responds with any status, even 500, it is not considered dead.