elasticsearch-js/docs/introduction.asciidoc

[[introduction]]
== Introduction

This is the official Node.js client for {es}. This page gives a quick overview 
about the features of the client.


[discrete]
=== Features

* One-to-one mapping with REST API.
* Generalized, pluggable architecture.
* Configurable, automatic discovery of cluster nodes.
* Persistent, Keep-Alive connections.
* Load balancing across all available nodes.
* Child client support.
* TypeScript support out of the box.


[discrete]
[[js-compatibility-matrix]]
=== Compatibility matrix

The minimum supported version of Node.js is `v8`.

The library is compatible with all {es} versions since 5.x. We recommend you to
use the same major version of the client as the {es} instance that you are
using.


[%header,cols=2*]
|===
|{es} Version
|Client Version

|`master`
|`master`

|`7.x`
|`7.x`

|`6.x`
|`6.x`

|`5.x`
|`5.x`
|===


[discrete]
==== Browser

WARNING: There is no official support for the browser environment. It exposes
your {es} instance to everyone, which could lead to security issues. We
recommend you to write a lightweight proxy that uses this client instead.


[discrete]
=== Quick start

First of all, require, then initialize the client:

[source,js]
----
const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })
----


You can use both the callback API and the promise API, both behave the same way.

[source,js]
----
// promise API
const result = await client.search({
  index: 'my-index',
  body: {
    query: {
      match: { hello: 'world' }
    }
  }
})

// callback API
client.search({
  index: 'my-index',
  body: {
    query: {
      match: { hello: 'world' }
    }
  }
}, (err, result) => {
  if (err) console.log(err)
})
----


The returned value of **every** API call is formed as follows:

[source,ts]
----
{
  body: object | boolean
  statusCode: number
  headers: object
  warnings: [string]
  meta: object
}
----


Let's see a complete example!

[source,js]
----
'use strict'

const { Client } = require('@elastic/elasticsearch')
const client = new Client({ node: 'http://localhost:9200' })

async function run () {
  // Let's start by indexing some data
  await client.index({
    index: 'game-of-thrones',
    // type: '_doc', // uncomment this line if you are using {es} ≤ 6
    body: {
      character: 'Ned Stark',
      quote: 'Winter is coming.'
    }
  })

  await client.index({
    index: 'game-of-thrones',
    // type: '_doc', // uncomment this line if you are using {es} ≤ 6
    body: {
      character: 'Daenerys Targaryen',
      quote: 'I am the blood of the dragon.'
    }
  })

  await client.index({
    index: 'game-of-thrones',
    // type: '_doc', // uncomment this line if you are using {es} ≤ 6
    body: {
      character: 'Tyrion Lannister',
      quote: 'A mind needs books like a sword needs a whetstone.'
    }
  })

  // We need to force an index refresh at this point, otherwise we will not
  // get any result in the consequent search
  await client.indices.refresh({ index: 'game-of-thrones' })

  // Let's search!
  const { body } = await client.search({
    index: 'game-of-thrones',
    // type: '_doc', // uncomment this line if you are using {es} ≤ 6
    body: {
      query: {
        match: { quote: 'winter' }
      }
    }
  })

  console.log(body.hits.hits)
}

run().catch(console.log)
----

[discrete]
==== Install multiple versions

If you are using multiple versions of {es}, you need to use multiple versions of
the client as well. In the past, installing multiple versions of the same
package was not possible, but with `npm v6.9`, you can do it via aliasing.

To install different version of the client, run the following command:

[source,sh]
----
npm install <alias>@npm:@elastic/elasticsearch@<version>
----


For example, if you need to install `7.x` and `6.x`, run the following commands:

[source,sh]
----
npm install es6@npm:@elastic/elasticsearch@6
npm install es7@npm:@elastic/elasticsearch@7
----


Your `package.json` will look similar to the following example:

[source,json]
----
"dependencies": {
  "es6": "npm:@elastic/elasticsearch@^6.7.0",
  "es7": "npm:@elastic/elasticsearch@^7.0.0"
}
----


Require the packages from your code by using the alias you have defined.

[source,js]
----
const { Client: Client6 } = require('es6')
const { Client: Client7 } = require('es7')

const client6 = new Client6({ node: 'http://localhost:9200' })
const client7 = new Client7({ node: 'http://localhost:9201' })

client6.info(console.log)
client7.info(console.log)
----


Finally, if you want to install the client for the next version of {es} (the one
that lives in the {es} master branch), use the following command:

[source,sh]
----
npm install esmaster@github:elastic/elasticsearch-js
----
WARNING: This command installs the master branch of the client which is not
considered stable.