* [DOCS] Reviews Client helpers section in the Node.JS book. * [DOCS] Changes link. * Update docs/index.asciidoc
This commit is contained in:
István Zoltán Szabó
committed by
GitHub
GitHub
parent
7a83df8445
commit
b812c51dce
@ -1,22 +1,26 @@
|
||||
[[client-helpers]]
|
||||
== Client Helpers
|
||||
== Client helpers
|
||||
|
||||
The client comes with an handy collection of helpers to give you a more comfortable experience with some APIs.
|
||||
The client comes with an handy collection of helpers to give you a more
|
||||
comfortable experience with some APIs.
|
||||
|
||||
CAUTION: The client helpers are experimental, and the API may change in the next minor releases.
|
||||
The helpers will not work in any Node.js version lower than 10.
|
||||
CAUTION: The client helpers are experimental, and the API may change in the next
|
||||
minor releases. The helpers will not work in any Node.js version lower than 10.
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Bulk Helper
|
||||
[[bulk-helper]]
|
||||
=== Bulk helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
|
||||
Running Bulk requests can be complex due to the shape of the API, this helper aims to provide a nicer developer experience around the Bulk API.
|
||||
Running bulk requests can be complex due to the shape of the API, this helper
|
||||
aims to provide a nicer developer experience around the Bulk API.
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Usage
|
||||
|
||||
[source,js]
|
||||
----
|
||||
const { createReadStream } = require('fs')
|
||||
@ -45,13 +49,14 @@ console.log(result)
|
||||
// }
|
||||
----
|
||||
|
||||
To create a new instance of the Bulk helper, you should access it as shown in the example above, the configuration options are:
|
||||
To create a new instance of the Bulk helper, access it as shown in the example
|
||||
above, the configuration options are:
|
||||
[cols=2*]
|
||||
|===
|
||||
|`datasource`
|
||||
a|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 https://www.npmjs.com/package/split2[`split2`] package, that will split the stream on new lines delimiters. +
|
||||
If it is a stream, we recommend to use the https://www.npmjs.com/package/split2[`split2`] package, that splits the stream on new lines delimiters. +
|
||||
This parameter is mandatory.
|
||||
[source,js]
|
||||
----
|
||||
@ -66,7 +71,7 @@ const b = client.helpers.bulk({
|
||||
----
|
||||
|
||||
|`onDocument`
|
||||
a|A function that will be 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 link:{ref}/docs-bulk.html[Bulk API documentation] to see the supported operations. +
|
||||
a|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 link:{ref}/docs-bulk.html[Bulk API documentation] to see the supported operations. +
|
||||
This parameter is mandatory.
|
||||
[source,js]
|
||||
----
|
||||
@ -80,7 +85,7 @@ const b = client.helpers.bulk({
|
||||
----
|
||||
|
||||
|`onDrop`
|
||||
a|A function that will be called for everytime a document can't be indexed and it has reached the maximum amount of retries.
|
||||
a|A function that is called for everytime a document can't be indexed and it has reached the maximum amount of retries.
|
||||
[source,js]
|
||||
----
|
||||
const b = client.helpers.bulk({
|
||||
@ -101,7 +106,7 @@ const b = client.helpers.bulk({
|
||||
----
|
||||
|
||||
|`flushInterval`
|
||||
a|How much time (in milliseconds) the helper will wait before flushing the body from the last document read. +
|
||||
a|How much time (in milliseconds) the helper waits before flushing the body from the last document read. +
|
||||
_Default:_ `30000`
|
||||
[source,js]
|
||||
----
|
||||
@ -111,7 +116,7 @@ const b = client.helpers.bulk({
|
||||
----
|
||||
|
||||
|`concurrency`
|
||||
a|How many request will be executed at the same time. +
|
||||
a|How many request is executed at the same time. +
|
||||
_Default:_ `5`
|
||||
[source,js]
|
||||
----
|
||||
@ -121,7 +126,7 @@ const b = client.helpers.bulk({
|
||||
----
|
||||
|
||||
|`retries`
|
||||
a|How many times a document will be retried before to call the `onDrop` callback. +
|
||||
a|How many times a document is retried before to call the `onDrop` callback. +
|
||||
_Default:_ Client max retries.
|
||||
[source,js]
|
||||
----
|
||||
@ -141,7 +146,7 @@ const b = client.helpers.bulk({
|
||||
----
|
||||
|
||||
|`refreshOnCompletion`
|
||||
a|If `true`, at the end of the bulk operation it will run a refresh on all indices or on the specified indices. +
|
||||
a|If `true`, at the end of the bulk operation it runs a refresh on all indices or on the specified indices. +
|
||||
_Default:_ false.
|
||||
[source,js]
|
||||
----
|
||||
@ -161,6 +166,7 @@ const b = client.helpers.bulk({
|
||||
|
||||
[discrete]
|
||||
===== Index
|
||||
|
||||
[source,js]
|
||||
----
|
||||
client.helpers.bulk({
|
||||
@ -176,6 +182,7 @@ client.helpers.bulk({
|
||||
|
||||
[discrete]
|
||||
===== Create
|
||||
|
||||
[source,js]
|
||||
----
|
||||
client.helpers.bulk({
|
||||
@ -228,9 +235,12 @@ client.helpers.bulk({
|
||||
[discrete]
|
||||
==== Abort a bulk operation
|
||||
|
||||
If needed, you can abort a bulk operation at any time. The bulk helper returns a https://promisesaplus.com/[thenable], which has an `abort` method.
|
||||
If needed, you can abort a bulk operation at any time. The bulk helper returns a
|
||||
https://promisesaplus.com/[thenable], which has an `abort` method.
|
||||
|
||||
NOTE: The abort method will stop the execution of the bulk operation, but if you are using a concurrency higher than one, the operations that are already running will not be stopped.
|
||||
NOTE: The abort method stops the execution of the bulk operation, but if you
|
||||
are using a concurrency higher than one, the operations that are already running
|
||||
will not be stopped.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -258,8 +268,9 @@ console.log(await b)
|
||||
[discrete]
|
||||
==== Passing custom options to the Bulk API
|
||||
|
||||
You can pass any option supported by the link:{ref}/docs-bulk.html#docs-bulk-api-query-params[Bulk API] to the helper, and the helper will use those options in conjuction with the Bulk
|
||||
API call.
|
||||
You can pass any option supported by the link:
|
||||
{ref}/docs-bulk.html#docs-bulk-api-query-params[Bulk API] to the helper, and the
|
||||
helper uses those options in conjunction with the Bulk API call.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -308,13 +319,16 @@ console.log(result)
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Multi Search Helper
|
||||
[[multi-search-helper]]
|
||||
=== Multi search helper
|
||||
|
||||
~Added~ ~in~ ~`v7.8.0`~
|
||||
|
||||
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.
|
||||
If you send search request at a high rate, this helper might be useful
|
||||
for you. It uses the multi 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.
|
||||
|
||||
|
||||
[discrete]
|
||||
@ -346,7 +360,8 @@ m.search(
|
||||
)
|
||||
----
|
||||
|
||||
To create a new instance of the Msearch helper, you should access it as shown in the example above, the configuration options are:
|
||||
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:
|
||||
[cols=2*]
|
||||
|===
|
||||
|`operations`
|
||||
@ -360,7 +375,7 @@ const m = client.helpers.msearch({
|
||||
----
|
||||
|
||||
|`flushInterval`
|
||||
a|How much time (in milliseconds) the helper will wait before flushing the operations from the last operation read. +
|
||||
a|How much time (in milliseconds) the helper waits before flushing the operations from the last operation read. +
|
||||
_Default:_ `500`
|
||||
[source,js]
|
||||
----
|
||||
@ -370,7 +385,7 @@ const m = client.helpers.msearch({
|
||||
----
|
||||
|
||||
|`concurrency`
|
||||
a|How many request will be executed at the same time. +
|
||||
a|How many request is executed at the same time. +
|
||||
_Default:_ `5`
|
||||
[source,js]
|
||||
----
|
||||
@ -380,7 +395,7 @@ const m = client.helpers.msearch({
|
||||
----
|
||||
|
||||
|`retries`
|
||||
a|How many times an operation will be retried before to resolve the request. An operation will be retried only in case of a 429 error. +
|
||||
a|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.
|
||||
[source,js]
|
||||
----
|
||||
@ -403,15 +418,21 @@ const m = client.helpers.msearch({
|
||||
|
||||
|
||||
[discrete]
|
||||
==== Stopping the Msearch Helper
|
||||
==== Stopping the msearch helper
|
||||
|
||||
If needed, you can stop a msearch processor at any time. The msearch helper returns a https://promisesaplus.com/[thenable], which has an `stop` method.
|
||||
If needed, you can stop an msearch processor at any time. The msearch helper
|
||||
returns a https://promisesaplus.com/[thenable], which has an `stop` method.
|
||||
|
||||
If you are creating multiple msearch helpers instances and using them for a limitied period of time, remember to always use the `stop` method once you have finished using them, otherwise your application will start leaking memory.
|
||||
If you are creating multiple msearch helpers instances and using them for a
|
||||
limitied period of time, remember to always use the `stop` method once you have
|
||||
finished using them, otherwise your application will start leaking memory.
|
||||
|
||||
The `stop` method accepts an optional error, that will be dispatched every subsequent search request.
|
||||
The `stop` method accepts an optional error, that will be dispatched every
|
||||
subsequent search request.
|
||||
|
||||
NOTE: The stop method will stop the execution of the msearch processor, but if you are using a concurrency higher than one, the operations that are already running will not be stopped.
|
||||
NOTE: The stop method stops the execution of the msearch processor, but if
|
||||
you are using a concurrency higher than one, the operations that are already
|
||||
running will not be stopped.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -439,12 +460,15 @@ setImmediate(() => m.stop())
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Search Helper
|
||||
[[search-helper]]
|
||||
=== Search helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
|
||||
A simple wrapper around the search API. Instead of returning the entire `result` object it will return only the search documents source.
|
||||
For improving the performances, this helper automatically adds `filter_path=hits.hits._source` to the querystring.
|
||||
A simple wrapper around the search API. Instead of returning the entire `result`
|
||||
object it returns only the search documents source. For improving the
|
||||
performances, this helper automatically adds `filter_path=hits.hits._source` to
|
||||
the query string.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -466,12 +490,16 @@ for (const doc of documents) {
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Scroll Search Helper
|
||||
[[scroll-search-helper]]
|
||||
=== Scroll search helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
|
||||
This helpers offers a simple and intuitive way to use the scroll search API. Once called, it returns an https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for-await...of[async iterator] which can be used in conjuction with a for-await...of. +
|
||||
It handles automatically the `429` error and uses the client's `maxRetries` option.
|
||||
This helpers offers a simple and intuitive way to use the scroll search API.
|
||||
Once called, it returns an
|
||||
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function[async iterator]
|
||||
which can be used in conjuction with a for-await...of. It handles automatically
|
||||
the `429` error and uses the `maxRetries` option of the client.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -510,7 +538,8 @@ for await (const result of scrollSearch) {
|
||||
[discrete]
|
||||
==== Quickly getting the documents
|
||||
|
||||
If you only need the documents from the result of a scroll search, you can access them via `result.documents`:
|
||||
If you only need the documents from the result of a scroll search, you can
|
||||
access them via `result.documents`:
|
||||
|
||||
[source,js]
|
||||
----
|
||||
@ -521,12 +550,15 @@ for await (const result of scrollSearch) {
|
||||
|
||||
|
||||
[discrete]
|
||||
=== Scroll Documents Helper
|
||||
[[scroll-documents-helper]]
|
||||
=== Scroll documents helper
|
||||
|
||||
~Added~ ~in~ ~`v7.7.0`~
|
||||
|
||||
It works in the same way as the scroll search helper, but it returns only the documents instead. Note, every loop cycle will return you a single document, and you can't use the `clear` method.
|
||||
For improving the performances, this helper automatically adds `filter_path=hits.hits._source` to the querystring.
|
||||
It works in the same way as the scroll search helper, but it returns only the
|
||||
documents instead. Note, every loop cycle returns a single document, and you
|
||||
can't use the `clear` method. For improving the performances, this helper
|
||||
automatically adds `filter_path=hits.hits._source` to the query string.
|
||||
|
||||
[source,js]
|
||||
----
|
||||
|
||||
Reference in New Issue
Block a user