WARNING: Version 5.x has passed its EOL date.

This documentation is no longer being maintained and may be removed. If you are running this version, we strongly advise you to upgrade. For the latest information, see the current release documentation.

« Don’t panic! Talk is cheap. Show me the code. »

› ›

Breaking changes

edit

Breaking changes

edit

Minimum supported version of Node.js is v8.
Everything has been rewritten using ES6 classes to help users extend the defaults more easily.
There is no longer an integrated logger. The client now is an event emitter that emits the following events: request, response, and error.
The code is no longer shipped with all the versions of the API, but only that of the package’s major version, This means that if you are using Elasticsearch v6, you will be required to install @elastic/elasticsearch@6, and so on.
The internals are completely different, so if you used to tweak them a lot, you will need to refactor your code. The public API should be almost the same.
No more browser support, for that will be distributed via another module, @elastic/elasticsearch-browser. This module is intended for Node.js only.
The returned value of an API call will no longer be the body, statusCode, and headers for callbacks and just the body for promises. The new returned value will be a unique object containing the body, statusCode, headers, warnings, and meta, for both callback and promises.

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

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

// after
const { body, statusCode, headers, warnings } = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
})

client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, (err, { body, statusCode, headers, warnings }) => {
  if (err) console.log(err)
})

Errors: there is no longer a custom error class for every HTTP status code (such as BadRequest or NotFound). There is instead a single ResponseError. Each error class has been renamed, and now each is suffixed with Error at the end.
Errors that have been removed: RequestTypeError, Generic, and all the status code specific errors (such as BadRequest or NotFound).
Errors that have been added: ConfigurationError (in case of bad configurations) and ResponseError, which contains all the data you may need to handle the specific error, such as statusCode, headers, body, and message.
Errors that has been renamed:
- RequestTimeout (408 statusCode) ⇒ TimeoutError
- ConnectionFault ⇒ ConnectionError
- NoConnections ⇒ NoLivingConnectionsError
- Serialization ⇒ SerializationError
- Serialization ⇒ DeserializationError
You must specify the port number in the configuration. In the previous version you can specify the host and port in a variety of ways, with the new client there is only one via the node parameter.
The plugins option has been removed, if you want to extend the client now you should use the client.extend API.

// before
const { Client } = require('elasticsearch')
const client = new Client({ plugins: [...] })

// after
const { Client } = require('@elastic/elasticsearch')
const client = new Client({ ... })
client.extend(...)

There is a clear distinction between the API related parameters and the client related configurations, the parameters ignore, headers, requestTimeout and maxRetries are no longer part of the API object, and you should specify them in a second option object.

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

client.search({
  index: 'my-index',
  body: { foo: 'bar' },
  ignore: [404]
}, (err, body, statusCode, headers) => {
  if (err) console.log(err)
})

// after
const { body, statusCode, headers, warnings } = await client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404]
})

client.search({
  index: 'my-index',
  body: { foo: 'bar' }
}, {
  ignore: [404]
}, (err, { body, statusCode, headers, warnings }) => {
  if (err) console.log(err)
})

The transport.request method will no longer accept the query key, but the querystring key instead (which can be a string or an object), furthermore, you need to send a bulk-like request, instead of the body key, you should use the bulkBody key. Also in this method, the client specific parameters should be passed as a second object.

// before
const body = await client.transport.request({
  method: 'GET',
  path: '/my-index/_search',
  body: { foo: 'bar' },
  query: { bar: 'baz' }
  ignore: [404]
})

client.transport.request({
  method: 'GET',
  path: '/my-index/_search',
  body: { foo: 'bar' },
  query: { bar: 'baz' }
  ignore: [404]
}, (err, body, statusCode, headers) => {
  if (err) console.log(err)
})

// after
const { body, statusCode, headers, warnings } = await client.transport.request({
  method: 'GET',
  path: '/my-index/_search',
  body: { foo: 'bar' },
  querystring: { bar: 'baz' }
}, {
  ignore: [404]
})

client.transport.request({
  method: 'GET',
  path: '/my-index/_search',
  body: { foo: 'bar' },
  querystring: { bar: 'baz' }
}, {
  ignore: [404]
}, (err, { body, statusCode, headers, warnings }) => {
  if (err) console.log(err)
})

« Don’t panic! Talk is cheap. Show me the code. »