Usageedit

Using the client is straightforward, it supports all the public APIs of Elasticsearch, and every method exposes the same signature.

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

// promise API
const result = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
})

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

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

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

The body is a boolean value when you use HEAD APIs.

The above value is returned even if there is an error during the execution of the request, this means that you can safely use the destructuring assignment.

The meta key contains all the information about the request, such as attempt, options, and the connection that has been used.

// promise API
const { body } = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
})

// callback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, (err, { body }) => {
  if (err) console.log(err)
})

Aborting a requestedit

When using the callback style API, the function also returns an object that allows you to abort the API request.

// calback API
const request = client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
}, (err, { body }) => {
  if (err) console.log(err)
})

request.abort()

Aborting a request with the promise style API is not supported, but you can achieve that with convenience wrapper.

function abortableRequest (params, options) {
  var request = null
  const promise = new Promise((resolve, reject) => {
    request = client.search(params, options, (err, result) => {
      err ? reject(err) : resolve(res)
    })
  })
  return {
    promise,
    abort: () => request.abort()
  }
}

const request = abortableRequest({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
})

request.abort()
// access the promise with `request.promise.[method]`

Request specific optionsedit

If needed you can pass request specific options in a second object:

// promise API
const result = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
})

// calback API
client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404],
  maxRetries: 3
}, (err, { body }) => {
  if (err) console.log(err)
})

The supported request specific options are:

ignore

[number] -  HTTP status codes which should not be considered errors for this request. Default: null

requestTimeout

number - Max request timeout for the request, it overrides the client default. Default: 30000

maxRetries

number - Max number of retries for the request, it overrides the client default. Default: 3

compression

string, boolean - Enables body compression for the request. Options: false, 'gzip' Default: false

asStream

boolean - Instead of getting the parsed body back, you get the raw Node.js stream of data. Default: false

headers

object - Custom headers for the request. Default: null

querystring

object - Custom querystring for the request. Default: null

id

any - Custom request id. (overrides the top level request id generator) Default: null

context

any - Custom object per request. (you can use it to pass data to the clients events) Default: null

Error handlingedit

The client exposes a variety of error objects that you can use to enhance your error handling. You can find all the error objects inside the errors key in the client.

const { errors } = require('@elastic/elasticsearch')
console.log(errors)

You can find the errors exported by the client in the table below.

ElasticsearchClientErrors

Every error inherits from this class, it is the basic error generated by the client.

TimeoutError

Generated when a request exceeds the requestTimeout option.

ConnectionError

Generated when an error occurs during the request, it can be a connection error or a malformed stream of data.

NoLivingConnectionsError

Generated in case of all connections present in the connection pool are dead.

SerializationError

Generated if the serialization fails.

DeserializationError

Generated if the deserialization fails.

ConfigurationError

Generated if there is a malformed configuration or parameter.

ResponseError

Generated when in case of a 4xx or 5xx response.