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

{
  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: {
    query: {
      match: { hello: 'world' }
    }
  }
})

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

Aborting a requestedit

If needed, you can abort a running request by calling the request.abort() method returned by the API.

If you abort a request, the request will fail with a RequestAbortedError.

const request = client.search({
  index: 'my-index',
  body: {
    query: {
      match: { hello: 'world' }
    }
  }
}, {
  ignore: [404],
  maxRetries: 3
}, (err, result) => {
  if (err) {
    console.log(err) // RequestAbortedError
  } else {
    console.log(result)
  }
})

request.abort()

The same behavior is valid for the promise style API as well.

const request = client.search({
  index: 'my-index',
  body: {
    query: {
      match: { hello: 'world' }
    }
  }
}, {
  ignore: [404],
  maxRetries: 3
})

request
  .then(result => console.log(result))
  .catch(err => console.log(err)) // RequestAbortedError

request.abort()

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: {
    query: {
      match: { hello: 'world' }
    }
  }
}, {
  ignore: [404],
  maxRetries: 3
})

// callback API
client.search({
  index: 'my-index',
  body: {
    query: {
      match: { hello: 'world' }
    }
  }
}, {
  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 in milliseconds, 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

Connecting through a proxyedit

Added in v7.10.0

If you need to pass through an http(s) proxy for connecting to Elasticsearch, the client offers out of the box a handy configuration for helping you with it. Under the hood it uses the hpagent module.

const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http://localhost:8080'
})

Basic authentication is supported as well:

const client = new Client({
  node: 'http://localhost:9200',
  proxy: 'http:user:pwd@//localhost:8080'
})

If you are connecting through a not http(s) proxy, such as a socks5 or pac, you can use the agent option to configure it.

const SocksProxyAgent = require('socks-proxy-agent')
const client = new Client({
  node: 'http://localhost:9200',
  agent () {
    return new SocksProxyAgent('socks://127.0.0.1:1080')
  }
})

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.

Error

Description

Properties

ElasticsearchClientError

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

  • name - string
  • message - string

TimeoutError

Generated when a request exceeds the requestTimeout option.

  • name - string
  • message - string
  • meta - object, contains all the information about the request

ConnectionError

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

  • name - string
  • message - string
  • meta - object, contains all the information about the request

RequestAbortedError

Generated if the user calls the request.abort() method.

  • name - string
  • message - string
  • meta - object, contains all the information about the request

NoLivingConnectionsError

Given the configuration, the ConnectionPool was not able to find a usable Connection for this request.

  • name - string
  • message - string
  • meta - object, contains all the information about the request

SerializationError

Generated if the serialization fails.

  • name - string
  • message - string
  • data - object, the object to serialize

DeserializationError

Generated if the deserialization fails.

  • name - string
  • message - string
  • data - string, the string to deserialize

ConfigurationError

Generated if there is a malformed configuration or parameter.

  • name - string
  • message - string

ResponseError

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

  • name - string
  • message - string
  • meta - object, contains all the information about the request
  • body - object, the response body
  • statusCode - object, the response headers
  • headers - object, the response status code