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.
Breaking changes
editBreaking 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
, anderror
. -
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
, andheaders
for callbacks and just thebody
for promises. The new returned value will be a unique object containing thebody
,statusCode
,headers
,warnings
, andmeta
, 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
orNotFound
). There is instead a singleResponseError
. Each error class has been renamed, and now each is suffixed withError
at the end. -
Errors that have been removed:
RequestTypeError
,Generic
, and all the status code specific errors (such asBadRequest
orNotFound
). -
Errors that have been added:
ConfigurationError
(in case of bad configurations) andResponseError
, which contains all the data you may need to handle the specific error, such asstatusCode
,headers
,body
, andmessage
. -
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 theclient.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
andmaxRetries
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 thequery
key, but thequerystring
key instead (which can be a string or an object), furthermore, you need to send a bulk-like request, instead of thebody
key, you should use thebulkBody
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) })