Release notes

edit

7.17.14

edit

Fixes

edit

Stops retrying timed-out requests by default. Re-enabling the old behavior can be done by providing a retryOnTimeout option when instantiating the client. #2293

7.17.13

edit

Fixes

edit

Fixes a bug where newly-added nodes that don’t have HTTP information yet should be skipped during sniffing, to prevent an unexpected TypeError. #1230

7.17.12

edit

Notes

edit

This is the first 7.x release where patch versions of the client will no longer (intentionally) align with patch versions of Elasticsearch. The latest patch release of the client will always be compatible with the corresponding minor release of Elasticsearch.

Fixes

edit
TypeScript build failure
edit

Fixes a type declaration bug that caused TypeScript builds to fail. #1927

Add TypeScript type declarations to exports
edit

Adds TypeScript type declarations file to package.json exports #1930

7.17.11

edit

Features

edit
Support for Elasticsearch v7.17.11
edit

You can find all the API changes here.

Fixes

edit
Fix index drift bug in bulk helper #1759
edit

Fixes a bug in the bulk helper that would cause onDrop to send back the wrong JSON document or error on a nonexistent document when an error occurred on a bulk HTTP request that contained a delete action.

7.17.0

edit

Features

edit
Support for Elasticsearch v7.17
edit

You can find all the API changes here.

7.16.0

edit

Features

edit
Support for Elasticsearch v7.16
edit

You can find all the API changes here.

Fixes

edit
Fixed "Cannot read property then of null" #1594
edit
Fixed export field deprecation log #1593
edit

7.15.0

edit

Features

edit
Support for Elasticsearch v7.15
edit

You can find all the API changes here.

Support mapbox content type #1500
edit

If you call an API that returns a mapbox content type, the response body will be a buffer.

Support CA fingerprint validation #1499
edit

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
  }
})
Show the body as string if the response error can’t be read as ES error #1509
edit

Useful if the errored response does not come from Elasticsearch, but a proxy in the middle for example.

Always display request params and options in request event #1531
edit

In some edge cases the params and options weren’t available in observabilty events, now they are always defined.

Always emit request aborted event #1534
edit

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

edit

Features

edit
Support for Elasticsearch v7.14
edit

You can find all the API changes here.

Verify connection to Elasticsearch #1487
edit

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.

Add api compatibility header support #1478
edit

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.

Add support for bearer auth #1488
edit

Bearer authentication, useful for service account tokens. Be aware that it does not handle automatic token refresh:

auth: {
  bearer: 'token'
}
Bulk update improvements #1428
edit

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

edit

Breaking changes

edit
Remove Node.js v10 support #1471
edit

According to our support matrix.

Features

edit
Support for Elasticsearch v7.13
edit

You can find all the API changes here.

Added new TypeScript definitions
edit

The 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.

Improve response error message #1457
edit

In case of Elasticsearch errors, now the error message show more info about the underlying issue, improving the debugging experience.

Fixes

edit
Catch HEAD errors #1460
edit

In 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

edit

Breaking changes

edit
Remove Node.js v8 support #1402
edit

According to our support matrix.

Features

edit
Support for Elasticsearch v7.12
edit

You can find all the API changes here.

Add support for transport options to all helpers #1400
edit

You can now pass Transport specific options to the helpers as well.

Fixes

edit
Add .finally method to the Promise API #1415
edit

The client returns a thenable object when you are not configuring a callback. Now the thenable offers a .finally method as well.

7.11.0

edit

Features

edit
Support for Elasticsearch v7.11
edit

You can find all the API changes here.

Added new observability events #1365
edit

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
Added x-elastic-client-meta header #1373
edit

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

edit
Fixes req.abort() with a body that is a stream calls callback(err) twice #1376
edit

When 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

edit

Features

edit
Support for Elasticsearch v7.10.
edit

You can find all the API changes here.

Added proxy support #1260
edit

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

edit
Scroll search should clear the scroll at the end #1331
edit

From now on the scroll search helper will automatically close the scroll on Elasticsearch, by doing so, Elasticsearch will free resources faster.

Handle connectivity issues while reading the body #1343
edit

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

edit
Add warning log about nodejs version support #1349
edit

7.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

edit

Fixes

edit
Improve child performances #1314
edit

The 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.

Throw all errors asynchronously #1295
edit

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).

Fix maxRetries request option handling #1296
edit

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.

Fix RequestOptions.body type to include null #1300
edit

The Connection requets option types were not accepting null as valid value.

Fixed size and maxRetries parameters in helpers #1284
edit

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

edit

Features

edit
Add ability to disable the http agent #1251
edit

If 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
})
Add support for a global context option #1256
edit

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' }
})
ESM support #1235
edit

If you are using ES Modules, now you can easily import the client!

import { Client } from '@elastic/elasticsearch'

Fixes

edit
Allow the client name to be a symbol #1254
edit

It 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')
})
Fixed transport.request querystring type #1240
edit

Only Record<string, any> was allowed. Now string is allowed as well.

Fixed type definitions #1263
edit
  • The transport.request defintion was incorrect, it was returning a Promise<T> instead of TransportRequestPromise<T>.
  • The refresh parameter of most APIs was declared as 'true' | 'false' | 'wait_for', which was clunky. Now is 'wait_for' | boolean.
Generate response type as boolean if the request is HEAD only #1275
edit

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

edit
Updated default http agent configuration #1242
edit

Added 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).

Improve child API #1245
edit

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, and off. The type definitions have been updated accordingly.

7.8.0

edit

Features

edit
Support for Elasticsearch v7.8.
edit

You can find all the API changes here.

Added multi search helper #1186
edit

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
  }
)
Added timeout support in bulk and msearch helpers #1206
edit

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

edit
Use filter_path for improving the search helpers performances #1199
edit

From 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.

Search helpers documents getter #1186
edit

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

edit

Fixes

edit
Disable client Helpers in Node.js < 10 - #1194
edit

The 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.

Force lowercase in all headers - #1187
edit

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

edit

Features

edit
Support for Elasticsearch v7.7.
edit

You can find all the API changes here.

Introduced client helpers - #1107
edit

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
The ConnectionPool.getConnection now always returns a Connection - #1127
edit

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.

Abortable promises - #1141
edit

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()
Major refactor of the Type Definitions - #1119 #1130 #1132
edit

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

edit
The ConnectionPool.update method now cleans the dead list - #1122 #1127
edit

It 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.

ConnectionPoolmarkDead should ignore connections that no longer exists - #1159
edit

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.

Do not retry a request if the body is a stream - #1143
edit

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.

Return an error if the request has been aborted - #1141
edit

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

edit

Fixes:

  • Secure json parsing - #1110
  • ApiKey should take precedence over basic auth - #1115

Documentation:

  • Fix typo in api reference - #1109

7.6.0

edit

Support for Elasticsearch v7.6.

7.5.1

edit

Fixes:

  • Skip compression in case of empty string body - #1080
  • Fix typo in NoLivingConnectionsError - #1045
  • Change TransportRequestOptions.ignore to number[] - #1053
  • ClientOptions["cloud"] should have optional auth fields - #1032

Documentation:

  • Docs: Return super in example Transport subclass - #980
  • Add examples to reference - #1076
  • Added new examples - #1031

7.5.0

edit

Support for Elasticsearch v7.5.

Features

  • X-Opaque-Id support #997

7.4.0

edit

Support for Elasticsearch v7.4.

Fixes:

  • Fix issue; node roles are defaulting to true when undefined is breaking usage of nodeFilter option - #967

Documentation:

  • Updated API reference doc - #945, #969
  • Fix inaccurate description sniffEndpoint - #959

Internals:

  • Update code generation #969

7.3.0

edit

Support for Elasticsearch v7.3.

Features:

  • Added auth option - #908
  • Added support for ApiKey authentication - #908

Fixes:

  • fix(Typings): sniffInterval can also be boolean - #914

Internals:

  • Refactored connection pool - #913

Documentation:

  • Better reference code examples - #920
  • Improve README - #909

7.2.0

edit

Support for Elasticsearch v7.2

Fixes:

  • Remove auth data from inspect and toJSON in connection class - #887

7.1.0

edit

Support for Elasticsearch v7.1

Fixes:

  • Support for non-friendly chars in url username and password - #858
  • Patch deprecated parameters - #851

7.0.1

edit

Fixes:

  • Fix TypeScript export (issue #841) - #842
  • Fix http and https port handling (issue #843) - #845
  • Fix TypeScript definiton (issue #803) - #846
  • Added toJSON method to Connection class (issue #848) - #849

7.0.0

edit

Support for Elasticsearch v7.0

  • Stable release.

"appendix",role="exclude",id="redirects"] = Deleted pages

The following pages have moved or been deleted.