diff --git a/docs/reference/api-reference.md b/docs/reference/api-reference.md
index c446c3b4a..b91c22313 100644
--- a/docs/reference/api-reference.md
+++ b/docs/reference/api-reference.md
@@ -980,6 +980,7 @@ PUT my-index-000001/_doc/1?version=2&version_type=external
"id": "elkbee"
}
}
+```
In this example, the operation will succeed since the supplied version of 2 is higher than the current document version of 1.
If the document was already updated and its version was set to 2 or higher, the indexing command will fail and result in a conflict (409 HTTP status code).
diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md
index 82a537260..6c7d75505 100644
--- a/docs/reference/basic-config.md
+++ b/docs/reference/basic-config.md
@@ -82,8 +82,6 @@ auth: {
}
```
----
-
### `maxRetries`
Type: `number`
@@ -91,8 +89,6 @@ Default: `3`
Max number of retries for each request.
----
-
### `requestTimeout`
Type: `number`
@@ -100,8 +96,6 @@ Default: `No value`
Max request timeout in milliseconds for each request.
----
-
### `pingTimeout`
Type: `number`
@@ -109,8 +103,6 @@ Default: `3000`
Max ping request timeout in milliseconds for each request.
----
-
### `sniffInterval`
Type: `number, boolean`
@@ -122,8 +114,6 @@ Perform a sniff operation every `n` milliseconds.
Sniffing might not be the best solution. Before using the various `sniff` options, review this [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how).
:::
----
-
### `sniffOnStart`
Type: `boolean`
@@ -131,8 +121,6 @@ Default: `false`
Perform a sniff once the client is started. Be sure to review the sniffing best practices [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how).
----
-
### `sniffEndpoint`
Type: `string`
@@ -140,8 +128,6 @@ Default: `'_nodes/_all/http'`
Endpoint to ping during a sniff. Be sure to review the sniffing best practices [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how).
----
-
### `sniffOnConnectionFault`
Type: `boolean`
@@ -149,8 +135,6 @@ Default: `false`
Perform a sniff on connection fault. Be sure to review the sniffing best practices [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how).
----
-
### `resurrectStrategy`
Type: `string`
@@ -159,8 +143,6 @@ Default: `'ping'`
Configure the node resurrection strategy.
Options: `'ping'`, `'optimistic'`, `'none'`
----
-
### `suggestCompression`
Type: `boolean`
@@ -168,8 +150,6 @@ Default: `false`
Adds an `accept-encoding` header to every request.
----
-
### `compression`
Type: `string, boolean`
@@ -178,8 +158,6 @@ Default: `false`
Enables gzip request body compression.
Options: `'gzip'`, `false`
----
-
### `tls`
Type: `http.SecureContextOptions`
@@ -187,8 +165,6 @@ Default: `null`
The [tls configuraton](https://nodejs.org/api/tls.html).
----
-
### `proxy`
Type: `string, URL`
@@ -208,8 +184,6 @@ const client = new Client({
})
```
----
-
### `agent`
Type: `http.AgentOptions, function`
@@ -237,8 +211,6 @@ const client = new Client({
})
```
----
-
### `nodeFilter`
Type: `function`
@@ -260,8 +232,6 @@ function defaultNodeFilter (conn) {
}
```
----
-
### `nodeSelector`
Type: `function`
@@ -279,8 +249,6 @@ function nodeSelector (connections) {
}
```
----
-
### `generateRequestId`
Type: `function`
@@ -297,8 +265,6 @@ function generateRequestId (params, options) {
}
```
----
-
### `name`
Type: `string, symbol`
@@ -306,8 +272,6 @@ Default: `elasticsearch-js`
The name to identify the client instance in the events.
----
-
### `opaqueIdPrefix`
Type: `string`
@@ -316,8 +280,6 @@ Default: `null`
A string that will be use to prefix any `X-Opaque-Id` header.
See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details.
----
-
### `headers`
Type: `object`
@@ -325,8 +287,6 @@ Default: `{}`
A set of custom headers to send in every request.
----
-
### `context`
Type: `object`
@@ -334,8 +294,6 @@ Default: `null`
A custom object that you can use for observability in your events. It will be merged with the API level context option.
----
-
### `enableMetaHeader`
Type: `boolean`
@@ -343,8 +301,6 @@ Default: `true`
If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data, such as the client and platform version.
----
-
### `cloud`
Type: `object`
@@ -366,16 +322,12 @@ const client = new Client({
})
```
----
-
### `disablePrototypePoisoningProtection`
Default: `true`
`boolean`, `'proto'`, `'constructor'` - The client can protect you against prototype poisoning attacks. For more information, refer to [Square Brackets are the Enemy](https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08). If needed, you can enable prototype poisoning protection entirely (`false`) or one of the two checks (`'proto'` or `'constructor'`). For performance reasons, it is disabled by default. To learn more, refer to the [`secure-json-parse` documentation](https://github.com/fastify/secure-json-parse).
----
-
### `caFingerprint`
Type: `string`
@@ -383,8 +335,6 @@ Default: `null`
If configured, verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied fingerprint. Only accepts SHA256 digest fingerprints.
----
-
### `maxResponseSize`
Type: `number`
@@ -392,8 +342,6 @@ Default: `null`
When configured, `maxResponseSize` verifies that the uncompressed response size is lower than the configured number. If it’s higher, the request will be canceled. The `maxResponseSize` cannot be higher than the value of `buffer.constants.MAX_STRING_LENGTH`.
----
-
### `maxCompressedResponseSize`
Type: `number`
@@ -401,8 +349,6 @@ Default: `null`
When configured, `maxCompressedResponseSize` verifies that the compressed response size is lower than the configured number. If it’s higher, the request will be canceled. The `maxCompressedResponseSize` cannot be higher than the value of `buffer.constants.MAX_STRING_LENGTH`.
----
-
### `redaction`
Type: `object`
@@ -414,8 +360,6 @@ Options for how to redact potentially sensitive data from metadata attached to `
[Read about redaction](/reference/advanced-config.md#redaction) for more details
::::
----
-
### `serverMode`
Type: `string`
diff --git a/docs/reference/client-helpers.md b/docs/reference/client-helpers.md
index c80562db4..731df31cc 100644
--- a/docs/reference/client-helpers.md
+++ b/docs/reference/client-helpers.md
@@ -51,18 +51,120 @@ console.log(result)
To create a new instance of the Bulk helper, access it as shown in the example above, the configuration options are:
-| | |
-| --- | --- |
-| `datasource` | An array, async generator or a readable stream with the data you need to index/create/update/delete. It can be an array of strings or objects, but also a stream of json strings or JavaScript objects.
If it is a stream, we recommend to use the [`split2`](https://www.npmjs.com/package/split2) package, that splits the stream on new lines delimiters.
This parameter is mandatory.
```js
const { createReadStream } = require('fs')
const split = require('split2')
const b = client.helpers.bulk({
// if you just use split(), the data will be used as array of strings
datasource: createReadStream('./dataset.ndjson').pipe(split())
// if you need to manipulate the data, you can pass JSON.parse to split
datasource: createReadStream('./dataset.ndjson').pipe(split(JSON.parse))
})
```
|
-| `onDocument` | A function that is called for each document of the datasource. Inside this function you can manipulate the document and you must return the operation you want to execute with the document. Look at the [Bulk API documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) to see the supported operations.
This parameter is mandatory.
```js
const b = client.helpers.bulk({
onDocument (doc) {
return {
index: { _index: 'my-index' }
}
}
})
```
|
-| `onDrop` | A function that is called for everytime a document can’t be indexed and it has reached the maximum amount of retries.
```js
const b = client.helpers.bulk({
onDrop (doc) {
console.log(doc)
}
})
```
|
-| `onSuccess` | A function that is called for each successful operation in the bulk request, which includes the result from Elasticsearch along with the original document that was sent, or `null` for delete operations.
```js
const b = client.helpers.bulk({
onSuccess ({ result, document }) {
console.log(`SUCCESS: Document ${result.index._id} indexed to ${result.index._index}`)
}
})
```
|
-| `flushBytes` | The size of the bulk body in bytes to reach before to send it. Default of 5MB.
*Default:* `5000000`
```js
const b = client.helpers.bulk({
flushBytes: 1000000
})
```
|
-| `flushInterval` | How much time (in milliseconds) the helper waits before flushing the body from the last document read.
*Default:* `30000`
```js
const b = client.helpers.bulk({
flushInterval: 30000
})
```
|
-| `concurrency` | How many request is executed at the same time.
*Default:* `5`
```js
const b = client.helpers.bulk({
concurrency: 10
})
```
|
-| `retries` | How many times a document is retried before to call the `onDrop` callback.
*Default:* Client max retries.
```js
const b = client.helpers.bulk({
retries: 3
})
```
|
-| `wait` | How much time to wait before retries in milliseconds.
*Default:* 5000.
```js
const b = client.helpers.bulk({
wait: 3000
})
```
|
-| `refreshOnCompletion` | If `true`, at the end of the bulk operation it runs a refresh on all indices or on the specified indices.
*Default:* false.
```js
const b = client.helpers.bulk({
refreshOnCompletion: true
// or
refreshOnCompletion: 'index-name'
})
```
|
+
+`datasource`
+: An array, async generator or a readable stream with the data you need to index/create/update/delete. It can be an array of strings or objects, but also a stream of json strings or JavaScript objects.
+ If it is a stream, we recommend to use the [`split2`](https://www.npmjs.com/package/split2) package, that splits the stream on new lines delimiters.
+ This parameter is mandatory.
+
+ ```js
+ const { createReadStream } = require('fs')
+ const split = require('split2')
+ const b = client.helpers.bulk({
+ // if you just use split(), the data will be used as array of strings
+ datasource: createReadStream('./dataset.ndjson').pipe(split())
+ // if you need to manipulate the data, you can pass JSON.parse to split
+ datasource: createReadStream('./dataset.ndjson').pipe(split(JSON.parse))
+ })
+ ```
+
+`onDocument`
+: A function that is called for each document of the datasource. Inside this function you can manipulate the document and you must return the operation you want to execute with the document. Look at the [Bulk API documentation](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-bulk) to see the supported operations.
+ This parameter is mandatory.
+
+ ```js
+ const b = client.helpers.bulk({
+ onDocument (doc) {
+ return {
+ index: { _index: 'my-index' }
+ }
+ }
+ })
+ ```
+
+`onDrop`
+: A function that is called for everytime a document can’t be indexed and it has reached the maximum amount of retries.
+
+ ```js
+ const b = client.helpers.bulk({
+ onDrop (doc) {
+ console.log(doc)
+ }
+ })
+ ```
+
+`onSuccess`
+: A function that is called for each successful operation in the bulk request, which includes the result from Elasticsearch along with the original document that was sent, or `null` for delete operations.
+
+ ```js
+ const b = client.helpers.bulk({
+ onSuccess ({ result, document }) {
+ console.log(`SUCCESS: Document ${result.index._id} indexed to ${result.index._index}`)
+ }
+ })
+ ```
+
+`flushBytes`
+: The size of the bulk body in bytes to reach before to send it. Default of 5MB.
+ *Default:* `5000000`
+
+ ```js
+ const b = client.helpers.bulk({
+ flushBytes: 1000000
+ })
+ ```
+
+`flushInterval`
+: How much time (in milliseconds) the helper waits before flushing the body from the last document read.
+ *Default:* `30000`
+
+ ```js
+ const b = client.helpers.bulk({
+ flushInterval: 30000
+ })
+ ```
+
+`concurrency`
+: How many request is executed at the same time.
+ *Default:* `5`
+
+ ```js
+ const b = client.helpers.bulk({
+ concurrency: 10
+ })
+ ```
+
+`retries`
+: How many times a document is retried before to call the `onDrop` callback.
+ *Default:* Client max retries.
+
+ ```js
+ const b = client.helpers.bulk({
+ retries: 3
+ })
+ ```
+
+`wait`
+: How much time to wait before retries in milliseconds.
+ *Default:* 5000.
+
+ ```js
+ const b = client.helpers.bulk({
+ wait: 3000
+ })
+ ```
+
+`refreshOnCompletion`
+: If `true`, at the end of the bulk operation it runs a refresh on all indices or on the specified indices.
+ *Default:* false.
+
+ ```js
+ const b = client.helpers.bulk({
+ refreshOnCompletion: true
+ // or
+ refreshOnCompletion: 'index-name'
+ })
+ ```
### Supported operations [_supported_operations]
@@ -255,13 +357,55 @@ m.search(
To create a new instance of the multi search (msearch) helper, you should access it as shown in the example above, the configuration options are:
-| | |
-| --- | --- |
-| `operations` | How many search operations should be sent in a single msearch request.
*Default:* `5`
```js
const m = client.helpers.msearch({
operations: 10
})
```
|
-| `flushInterval` | How much time (in milliseconds) the helper waits before flushing the operations from the last operation read.
*Default:* `500`
```js
const m = client.helpers.msearch({
flushInterval: 500
})
```
|
-| `concurrency` | How many request is executed at the same time.
*Default:* `5`
```js
const m = client.helpers.msearch({
concurrency: 10
})
```
|
-| `retries` | How many times an operation is retried before to resolve the request. An operation is retried only in case of a 429 error.
*Default:* Client max retries.
```js
const m = client.helpers.msearch({
retries: 3
})
```
|
-| `wait` | How much time to wait before retries in milliseconds.
*Default:* 5000.
```js
const m = client.helpers.msearch({
wait: 3000
})
```
|
+`operations`
+: How many search operations should be sent in a single msearch request.
+ *Default:* `5`
+
+ ```js
+ const m = client.helpers.msearch({
+ operations: 10
+ })
+ ```
+
+`flushInterval`
+: How much time (in milliseconds) the helper waits before flushing the operations from the last operation read.
+ *Default:* `500`
+
+ ```js
+ const m = client.helpers.msearch({
+ flushInterval: 500
+ })
+ ```
+
+`concurrency`
+: How many request is executed at the same time.
+ *Default:* `5`
+
+ ```js
+ const m = client.helpers.msearch({
+ concurrency: 10
+ })
+ ```
+
+`retries`
+: How many times an operation is retried before to resolve the request. An operation is retried only in case of a 429 error.
+ *Default:* Client max retries.
+
+ ```js
+ const m = client.helpers.msearch({
+ retries: 3
+ })
+ ```
+
+`wait`
+: How much time to wait before retries in milliseconds.
+ *Default:* 5000.
+
+ ```js
+ const m = client.helpers.msearch({
+ wait: 3000
+ })
+ ```
### Stopping the msearch helper [_stopping_the_msearch_helper]
diff --git a/docs/reference/connecting.md b/docs/reference/connecting.md
index 887dc587d..82a121584 100644
--- a/docs/reference/connecting.md
+++ b/docs/reference/connecting.md
@@ -332,21 +332,22 @@ The supported request specific options are:
| Option | Description |
| --- | ----------- |
| `ignore` | `number[]` - HTTP status codes which should not be considered errors for this request.
*Default:* `null` |
-| `requestTimeout` | `number` or `string` - Max request timeout for the request in milliseconds. This overrides the client default, which is to not time out at all. See [Elasticsearch best practices for HTML clients](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#_http_client_configuration) for more info.
_Default:* No timeout |
+| `requestTimeout` | `number` or `string` - Max request timeout for the request in milliseconds. This overrides the client default, which is to not time out at all. See [Elasticsearch best practices for HTML clients](elasticsearch://reference/elasticsearch/configuration-reference/networking-settings.md#_http_client_configuration) for more info.
_Default:_ No timeout |
| `retryOnTimeout` | `boolean` - Retry requests that have timed out.*Default:* `false` |
| `maxRetries` | `number` - Max number of retries for the request, it overrides the client default.
*Default:* `3` |
| `compression` | `string` or `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` |
+| `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` |
-| `opaqueId` | `string` - Set the `X-Opaque-Id` HTTP header. See [X-Opaque-Id HTTP header](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#x-opaque-id) *Default:* `null` |
+| `opaqueId` | `string` - Set the `X-Opaque-Id` HTTP header. See [X-Opaque-Id HTTP header](elasticsearch://reference/elasticsearch/rest-apis/api-conventions.md#x-opaque-id)
*Default:* `null` |
| `maxResponseSize` | `number` - When configured, it verifies that the uncompressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_STRING_LENTGH
*Default:* `null` |
| `maxCompressedResponseSize` | `number` - When configured, it verifies that the compressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_LENTGH
*Default:* `null` |
| `signal` | `AbortSignal` - The AbortSignal instance to allow request abortion.
*Default:* `null` |
| `meta` | `boolean` - Rather than returning the body, return an object containing `body`, `statusCode`, `headers` and `meta` keys
*Default*: `false` |
-| `redaction` | `object` - Options for redacting potentially sensitive data from error metadata. See [Redaction of potentially sensitive data](/reference/advanced-config.md#redaction). | `retryBackoff` |
+| `redaction` | `object` - Options for redacting potentially sensitive data from error metadata. See [Redaction of potentially sensitive data](/reference/advanced-config.md#redaction). |
+| `retryBackoff` | `(min: number, max: number, attempt: number) => number;` - A function that calculates how long to sleep, in seconds, before the next request retry
_Default:_ A built-in function that uses exponential backoff with jitter. |
## Using the Client in a Function-as-a-Service Environment [client-faas-env]
@@ -461,9 +462,8 @@ 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
|