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

.. code:: sh

    npm install elasticsearch

Getting the browser client
--------------------------

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

.. code:: 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.

.. code:: 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.

.. code:: 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.
