Release notes
editRelease notes
edit7.16.0
editFeatures
editSupport for Elasticsearch v7.16
editYou can find all the API changes here.
Fixes
edit7.15.0
editFeatures
editSupport for Elasticsearch v7.15
editYou can find all the API changes here.
If you call an API that returns a mapbox conten type, the response body will be a buffer.
You can configure the client to only trust certificates that are signed by a specific CA certificate ( CA certificate pinning ) by providing a caFingerprint
option. This will verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied value.
a caFingerprint
option, which will verify the supplied certificate authority fingerprint.
You must configure a SHA256 digest.
const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'https://example.com' auth: { ... }, // the fingerprint (SHA256) of the CA certificate that is used to sign the certificate that the Elasticsearch node presents for TLS. caFingerprint: '20:0D:CA:FA:76:...', ssl: { // might be required if it's a self-signed certificate rejectUnauthorized: false } })
Useful if the errored response does not come from Elasticsearch, but a proxy in the middle for example.
In some edge cases the params and options weren’t available in observabilty events, now they are always defined.
If the client is busy running an async operation, the .abort()
call might be executed before sending the actual request. In such case, the error was swallowed, now it will always be emitted, either in the request
or response
event.
7.14.0
editFeatures
editSupport for Elasticsearch v7.14
editYou can find all the API changes here.
The client will verify if it’s working with a supported release of Elasticsearch. Elastic language clients are guaranteed to be able to communicate with Elasticsearch or Elastic solutions running on the same major version and greater or equal minor version.
Language clients are forward compatible; meaning that clients support communicating with greater minor versions of Elasticsearch. Elastic language clients are not guaranteed to be backwards compatible.
If you configure the ELASTIC_CLIENT_APIVERSIONING
to true
the client will send a compatibility header
to allow you to use a 7.x client against a 8.x cluster. In this way it will be easier to migrate your code to a newer release of Elasticsearch.
Bearer authentication, useful for service account tokens. Be aware that it does not handle automatic token refresh:
auth: { bearer: 'token' }
The final stats object will let you know how many noop
operations happened.
Also, a new .stats
getter has been added to allow you to read the stats before
the operation finishes.
const b = client.helpers.bulk({ ... }) ... console.log(b.stats)
7.13.0
editBreaking changes
editAccording to our support matrix.
Features
editSupport for Elasticsearch v7.13
editYou can find all the API changes here.
Added new TypeScript definitions
editThe new type definition is more advanced compared to the legacy one. In the legacy type definitions you were expected to configure via generics both request and response bodies. The new type definitions comes with a complete type definition for every Elasticsearch endpoint.
You can see how to use them now here.
In case of Elasticsearch errors, now the error message show more info about the underlying issue, improving the debugging experience.
Fixes
editIn case of http errors in HEAD request, the client was swalling the response body. This is now fixed and in case of error you will get the full body response.
7.12.0
editBreaking changes
editAccording to our support matrix.
Features
editSupport for Elasticsearch v7.12
editYou can find all the API changes here.
You can now pass Transport specific options to the helpers as well.
Fixes
editThe client returns a thenable object when you are not configuring a callback.
Now the thenable offers a .finally
method as well.
7.11.0
editFeatures
editSupport for Elasticsearch v7.11
editYou can find all the API changes here.
Two new observability events has been introduced: serialization
and
deserialization
. The event order is described in the following graph, in some
edge cases, the order is not guaranteed. You can find in
test/acceptance/events-order.test.js
how the order changes based on the situation.
serialization │ │ (serialization and compression happens between those two events) │ └─▶ request │ │ (actual time spent over the wire) │ └─▶ deserialization │ │ (deserialization and decompression happens between those two events) │ └─▶ response
Adds the x-elastic-client-meta
HTTP header which is used by Elastic Cloud and
can be disabled with the enableMetaHeader
parameter set to false
.
Fixes
editWhen using a body that is a stream to client.search(), and calling req.abort(), the callback is called twice. Once for the RequestAbortedError, as expected, and once for a "premature close" error from end-of-stream, used by pump, used by the client. This issue has now been fixed.
7.10.0
editFeatures
editSupport for Elasticsearch v7.10
.
editYou can find all the API changes here.
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' })
Fixes
editFrom now on the scroll search helper will automatically close the scroll on Elasticsearch, by doing so, Elasticsearch will free resources faster.
It might happen that the underlying socket stops working due to an external
cause while reading the body. This could lead to an unwanted
DeserialzationError
. From now, this will be handled as a generic
ConnectionError
.
Warnings
edit7.11
will be the last version of the client that will support Node.js v8,
while 7.12
will be the last one that supports Node.js v10. If you are using
this versions you will see a DeprecationWaring
in your logs. We strongly
recommend to upgrade to newer versions of Node.js as usng an EOL version will
expose you to securty risks.
Please refer to ela.st/nodejs-support for additional information.
7.9.1
editFixes
editThe client code has been refactored to speed up the performances of the child method. Before this pr, creating many children per second would have caused a high memory consumption and a spike in CPU usage. This pr changes the way the client is created by refactoring the code generation, now the clients methods are no longer added to the instance with a for loop but via prototypal inheritance. Thus, the overall performances are way better, now creating a child is ~5 times faster, and it consumes ~70% less memory.
This change should not cause any breaking change unless you were mocking the client methods. In such case you should refactor it, or use elasticsearch-js-mock.
Finally, this change should also fix once and of all the bundlers support.
Some validation errors were thrown synchronously, causing the callback to be called in th same tick. This issue is known as "The release fo Zalgo" (see here).
The maxRetries
parameter can be configured on a per requets basis, if set to
zero it was defaulting to the client default. Now the client is honoring the
request specific configuration.
The Connection requets option types were not accepting null
as valid value.
The size
parameter was being passed too the scroll request, which was causing
an error. Value of maxRetries
set to 0 was resulting in no request at all.
7.9.0
editFeatures
editIf needed, the http agent can be disabled by setting it to false
.
const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'http://localhost:9200'. agent: false })
Before this, you could set a context
option in each request, but there was no
way of setting it globally. Now you can by configuring the context
object in
the global configuration, that will be merged with the local one.
const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'http://localhost:9200'. context: { meta: 'data' } })
If you are using ES Modules, now you can easily import the client!
import { Client } from '@elastic/elasticsearch'
Fixes
editIt was possible in plain JavaScript, but not in TypeScript, now you can do it in TypeScript as well.
const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'http://localhost:9200', name: Symbol('unique') })
Only Record<string, any>
was allowed. Now string
is allowed as well.
-
The
transport.request
defintion was incorrect, it was returning aPromise<T>
instead ofTransportRequestPromise<T>
. -
The
refresh
parameter of most APIs was declared as'true' | 'false' | 'wait_for'
, which was clunky. Now is'wait_for' | boolean
.
All HEAD request will have the body casted to a boolean value, true
in case of
a 200 response, false
in case of a 404 response. The type definitions were not
reflecting this behavior.
import { Client } from '@elastic/elasticsearch' const client = new Client({ node: 'http://localhost:9200' }) const { body } = await client.exist({ index: 'my-index', id: 'my-id' }) console.log(body) // either `true` or `false`
Internals
editAdded the scheduling: lifo option to the default HTTP agent configuration to avoid maximizing the open sockets against Elasticsearch and lowering the risk of encountering socket timeouts. This feature is only available from Node v14.5+, but it should be backported to v10 and v12 (nodejs/node#33278).
This pr introduce two changes which should not impact the surface API:
-
Refactored the
client.child
API to allocate fewer objects, this change improves memory consumption over time and improves the child creation performances by ~12%. -
The client no longer inherits from the EventEmitter class, but instead has an
internal event emitter and exposes only the API useful for the users, namely
emit, `on
,once
, andoff
. The type definitions have been updated accordingly.
7.8.0
editFeatures
editSupport for Elasticsearch v7.8
.
editYou can find all the API changes here.
If you are sending search request at a high rate, this helper might be useful
for you. It will use the mutli search API under the hood to batch the requests
and improve the overall performances of your application. The result
exposes a
documents
property as well, which allows you to access directly the hits
sources.
const { Client } = require('@elastic/elasticsearch') const client = new Client({ node: 'http://localhost:9200' }) const m = client.helpers.msearch() // promise style API m.search( { index: 'stackoverflow' }, { query: { match: { title: 'javascript' } } } ) .then(result => console.log(result.body)) // or result.documents .catch(err => console.error(err)) // callback style API m.search( { index: 'stackoverflow' }, { query: { match: { title: 'ruby' } } }, (err, result) => { if (err) console.error(err) console.log(result.body)) // or result.documents } )
If there is a slow producer, the bulk helper might send data with a very large
period of time, and if the process crashes for any reason, the data would be
lost. This pr introduces a flushInterval
option in the bulk helper to avoid
this issue. By default, the bulk helper will flush the data automatically every
30 seconds, unless the threshold has been reached before.
const b = client.helpers.bulk({ flushInterval: 30000 })
The same problem might happen with the multi search helper, where the user is
not sending search requests fast enough. A flushInterval
options has been
added as well, with a default value of 500 milliseconds.
const m = client.helpers.msearch({ flushInterval: 500 })
Internals
editFrom now on, all he search helpers will use the filter_path
option
automatically when needed to retrieve only the hits source. This change will
result in less netwprk traffic and improved deserialization performances.
Before this, the documents
key that you can access in any search helper was
computed as soon as we got the search result from Elasticsearch. With this
change the documents
key is now a getter, which makes this process lazy,
resulting in better performances and lower memory impact.
7.7.1
editFixes
editThe client helpers can’t be used in Node.js < 10 because it needs a custom flag to be able to use them. Given that not every provider allows the user to specify custom Node.js flags, the Helpers has been disabled completely in Node.js < 10.
Now all the user-provided headers names will be lowercased by default, so there will be no conflicts in case of the same header with different casing.
7.7.0
editFeatures
editSupport for Elasticsearch v7.7
.
editYou can find all the API changes here.
From now on, the client comes with an handy collection of helpers to give you a more comfortable experience with some APIs.
The client helpers are experimental, and the API may change in the next minor releases.
The following helpers has been introduced:
-
client.helpers.bulk
-
client.helpers.search
-
client.helpers.scrollSearch
-
client.helpers.scrollDocuments
What does this mean? It means that you will see less NoLivingConnectionError
,
which now can only be caused if you set a selector/filter too strict. For
improving the debugging experience, the NoLivingConnectionsError
error message
has been updated.
From now on, it will be possible to abort a request generated with the
promise-styl API. If you abort a request generated from a promise, the promise
will be rejected with a RequestAbortedError
.
const promise = client.search({ body: { query: { match_all: {} } } }) promise .then(console.log) .catch(console.log) promise.abort()
Now every API makes better use of the generics and overloading, so you can (or
not, by default request/response bodies are Record<string, any>
) define the
request/response bodies in the generics.
// request and response bodies are generics client.search(...) // response body is `SearchResponse` and request body is generic client.search<SearchResponse>(...) // request body is `SearchBody` and response body is `SearchResponse` client.search<SearchResponse, SearchBody>(...)
This should not be a breaking change, as every generics defaults to any
. It
might happen to some users that the code breaks, but our test didn’t detect any
of it, probably because they were not robust enough. However, given the gigantic
improvement in the developer experience, we have decided to release this change
in the 7.x line.
Fixes
editIt can happen in a situation where we are updating the connections list and
running sniff, leaving the dead
list in a dirty state. Now the
ConnectionPool.update
cleans up the dead
list every time, which makes way
more sense given that all the new connections are alive.
It might happen that markDead is called just after a pool update, and in such case, the client was adding the dead list a node that no longer exists, causing unhandled exceptions later.
The client should not retry if it’s sending a stream body, because it should store in memory a copy of the stream to be able to send it again, but since it doesn’t know in advance the size of the stream, it risks to take too much memory. Furthermore, copying everytime the stream is very an expensive operation.
Until now, aborting a request was blocking the HTTP request, but never calling
the callback or resolving the promise to notify the user. This is a bug because
it could lead to dangerous memory leaks. From now on if the user calls the
request.abort()
method, the callback style API will be called with a
RequestAbortedError
, the promise will be rejected with RequestAbortedError
as well.
7.6.1
editFixes:
Documentation:
- Fix typo in api reference - #1109
7.6.0
editSupport for Elasticsearch v7.6
.
7.5.1
editFixes:
Documentation:
7.5.0
editSupport for Elasticsearch v7.5
.
Features
- X-Opaque-Id support #997
7.4.0
editSupport for Elasticsearch v7.4
.
Fixes:
- Fix issue; node roles are defaulting to true when undefined is breaking usage of nodeFilter option - #967
Documentation:
Internals:
- Update code generation #969
7.3.0
editSupport for Elasticsearch v7.3
.
Features:
Fixes:
- fix(Typings): sniffInterval can also be boolean - #914
Internals:
- Refactored connection pool - #913
Documentation:
7.2.0
editSupport for Elasticsearch v7.2
Fixes:
- Remove auth data from inspect and toJSON in connection class - #887
7.1.0
editSupport for Elasticsearch v7.1
Fixes:
7.0.1
editFixes:
7.0.0
editSupport for Elasticsearch v7.0
- Stable release.
"appendix",role="exclude",id="redirects"] = Deleted pages
The following pages have moved or been deleted.