Refactors JS client helper documentation #1358

kolchfa-aws · 2022-09-29T00:51:44Z

Description

Refactors js client helper documentation.

Checklist

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Fix #823 Signed-off-by: Robert Da Silva <[email protected]>

Signed-off-by: Robert Da Silva <[email protected]>

…-website into robdasilva-main

kolchfa-aws · 2022-09-29T00:53:32Z

@robdasilva -- could you please look over the PR for technical accuracy? Thank you!

nhtruong · 2022-09-29T19:55:55Z

_clients/javascript/helpers.md

+| `refreshOnCompletion` | Boolean | Whether a refresh should be run on all affected indices at the end of the bulk operation. Optional. Default is false.
+| `retries` | Integer | The number of times an operation is retried before `onDrop` is called for that document. Optional. Defaults to the client's  `maxRetries` value.
+| `wait` | Integer | Time in milliseconds to wait before retrying an operation. Optional. Default is 5,000.
+


Can we bubble the required params to the top of this list, and make it easier to see that they are required? One way of doing this is having a column called required / default that either states that param is required or a default value, if any, when it's optional:

Option Data type Required / Default Description

datasource An array, async generator or a readable stream of strings or objects REQUIRED Represents the documents you need to create, delete, index or update.

concurrency Integer 5 The number of requests to be executed in parallel.

flushBytes Integer 5,000,000. Maximum bulk body size to send in bytes.

Thank you and great work :-)

nhtruong · 2022-09-29T20:16:37Z

_clients/javascript/index.md

- `enabled`: A Boolean used to turn the Circuit Breaker on or off. Defaults to `false`.
- `maxPercentage`: The threshold that determines whether the Circuit Breaker engages. The input range must be between `[0 ,1]`. Any number that exceeds that range will correct to `1.0`.
+- `enabled`: A Boolean used to turn the circuit breaker on or off. Defaults to `false`.
+- `maxPercentage`: The threshold that determines whether the circuit breaker engages. Valid values are [0, 1]. Any value that exceeds that range will correct to `1.0`.


I think Valid values are [0, 1] can easily be interpreted as only 0 and 1 are valid values when maxPercentage can be any real number between 0.0 and 1.0

Signed-off-by: Fanit Kolchina <[email protected]>

nhtruong

LGTM 🚀
And thank you for your work!

Naarcha-AWS

Let's add an introduction to helpers, even if it's a short sentence.

Otherwise, LGTM

Naarcha-AWS · 2022-09-30T19:24:09Z

_clients/javascript/helpers.md

+
+# Helper methods
+
+This section is currently incomplete. It does not yet cover all helper methods and their options.


Suggested change

This section is currently incomplete. It does not yet cover all helper methods and their options.

Helper methods allow you to abstract certain API tasks.

This section is currently incomplete. It does not yet cover all helper methods and their options.

Signed-off-by: Fanit Kolchina <[email protected]>

_clients/javascript/helpers.md

alicejw1 · 2022-09-30T20:04:34Z

_clients/javascript/helpers.md

+  aborted: boolean
+}
+```
+


Suggested change

#### Helper configuration options

_clients/javascript/helpers.md

alicejw1

Really great work Fanit!
i only had a couple minor suggestions

Co-authored-by: Alice Williams <[email protected]>

Signed-off-by: Fanit Kolchina <[email protected]>

natebower

@kolchfa-aws Please see my changes and comments and let me know if you have any questions. Thanks!

natebower · 2022-10-11T13:38:32Z

_clients/index.md


-OpenSearch provides clients for several popular programming languages, with more coming. In general, clients are compatible with clusters running the same major version of OpenSearch (`major.minor.patch`).
+OpenSearch provides clients for several popular programming languages, with more coming. 


Suggested change

OpenSearch provides clients for several popular programming languages, with more coming.

OpenSearch provides clients for several popular programming languages, with more to come.

natebower · 2022-10-11T13:41:44Z

_clients/javascript/helpers.md

+
+When creating a new bulk helper instance, you can use the following configuration options.
+
+| Option | Data type | Required/Default | Description 


I've seen "Data Type" (both words capitalized) in other tables. Let's make consistent.

natebower · 2022-10-11T13:42:31Z

_clients/javascript/helpers.md

+
+| Option | Data type | Required/Default | Description 
+| :--- | :--- | :--- | :---
+| `datasource` | An array, async generator or a readable stream of strings or objects | Required | Represents the documents you need to create, delete, index or update. 


natebower · 2022-10-11T13:46:08Z

_clients/javascript/helpers.md

+| `concurrency` | Integer | Optional. Default is 5. | The number of requests to be executed in parallel. 
+| `flushBytes` | Integer |  Optional. Default is 5,000,000. | Maximum bulk body size to send in bytes.
+| `flushInterval` | Integer |  Optional. Default is 30,000. | Time in milliseconds to wait before flushing the body after the last document has been read.
+| `onDrop` | Function | Optional. Default is `noop`. | A function to be invoked for every document that can’t be indexed after reaching the maximum amount of retries. 


natebower · 2022-10-11T13:51:44Z

_clients/javascript/helpers.md

+| `flushBytes` | Integer |  Optional. Default is 5,000,000. | Maximum bulk body size to send in bytes.
+| `flushInterval` | Integer |  Optional. Default is 30,000. | Time in milliseconds to wait before flushing the body after the last document has been read.
+| `onDrop` | Function | Optional. Default is `noop`. | A function to be invoked for every document that can’t be indexed after reaching the maximum amount of retries. 
+| `refreshOnCompletion` | Boolean | Optional. Default is false. | Whether or not a refresh should be run on all affected indices at the end of the bulk operation. 


natebower · 2022-10-11T13:56:25Z

_clients/javascript/helpers.md

+
+#### Index
+
+The index operation creates a new document if it doesn’t exist, and recreates the document if it already exists.


Suggested change

The index operation creates a new document if it doesn’t exist, and recreates the document if it already exists.

The index operation creates a new document if it doesn’t exist and recreates the document if it already exists.

natebower · 2022-10-11T13:57:29Z

_clients/javascript/helpers.md

+
+#### Update
+
+The update operation updates the document with the the fields being sent. The document must already exist in the index.


Suggested change

The update operation updates the document with the the fields being sent. The document must already exist in the index.

The update operation updates the document with the fields being sent. The document must already exist in the index.

Signed-off-by: Fanit Kolchina <[email protected]>

* Fix Circuit Breaker section in JS client docs Fix #823 Signed-off-by: Robert Da Silva <[email protected]> * Add documentation for JS client bulk helper Signed-off-by: Robert Da Silva <[email protected]> * Refactors js client helper documentation * Incorporated tech review comments Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated doc review comments Signed-off-by: Fanit Kolchina <[email protected]> * Update _clients/javascript/helpers.md Co-authored-by: Alice Williams <[email protected]> * Update _clients/javascript/helpers.md Co-authored-by: Alice Williams <[email protected]> * Update helpers.md * Incorporated tech review feedback Signed-off-by: Fanit Kolchina <[email protected]> * Implemented editorial comments Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: Robert Da Silva <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Co-authored-by: Robert Da Silva <[email protected]> Co-authored-by: Alice Williams <[email protected]> (cherry picked from commit 89f966a)

* Fix Circuit Breaker section in JS client docs Fix #823 Signed-off-by: Robert Da Silva <[email protected]> * Add documentation for JS client bulk helper Signed-off-by: Robert Da Silva <[email protected]> * Refactors js client helper documentation * Incorporated tech review comments Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated doc review comments Signed-off-by: Fanit Kolchina <[email protected]> * Update _clients/javascript/helpers.md Co-authored-by: Alice Williams <[email protected]> * Update _clients/javascript/helpers.md Co-authored-by: Alice Williams <[email protected]> * Update helpers.md * Incorporated tech review feedback Signed-off-by: Fanit Kolchina <[email protected]> * Implemented editorial comments Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: Robert Da Silva <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Co-authored-by: Robert Da Silva <[email protected]> Co-authored-by: Alice Williams <[email protected]> (cherry picked from commit 89f966a) Co-authored-by: kolchfa-aws <[email protected]>

robdasilva and others added 4 commits July 21, 2022 23:32

Fix Circuit Breaker section in JS client docs

74f80d3

Fix #823 Signed-off-by: Robert Da Silva <[email protected]>

Add documentation for JS client bulk helper

83c1e06

Signed-off-by: Robert Da Silva <[email protected]>

Merge branch 'main' of github.com:robdasilva/opensearch-documentation…

9038fe2

…-website into robdasilva-main

Refactors js client helper documentation

a45fe0c

kolchfa-aws requested a review from a team as a code owner September 29, 2022 00:51

kolchfa-aws self-assigned this Sep 29, 2022

kolchfa-aws changed the title ~~Robdasilva main~~ Refactors JS client helper documentation Sep 29, 2022

nhtruong reviewed Sep 29, 2022

View reviewed changes

Incorporated tech review comments

9d254c4

Signed-off-by: Fanit Kolchina <[email protected]>

nhtruong approved these changes Sep 30, 2022

View reviewed changes

Naarcha-AWS approved these changes Sep 30, 2022

View reviewed changes

Incorporated doc review comments

3a06071

Signed-off-by: Fanit Kolchina <[email protected]>

alicejw1 reviewed Sep 30, 2022

View reviewed changes

_clients/javascript/helpers.md Outdated Show resolved Hide resolved

alicejw1 reviewed Sep 30, 2022

View reviewed changes

_clients/javascript/helpers.md Outdated Show resolved Hide resolved

alicejw1 approved these changes Sep 30, 2022

View reviewed changes

kolchfa-aws and others added 3 commits September 30, 2022 16:51

Update _clients/javascript/helpers.md

496d178

Co-authored-by: Alice Williams <[email protected]>

Update _clients/javascript/helpers.md

83c2c54

Co-authored-by: Alice Williams <[email protected]>

Update helpers.md

c66bc13

kolchfa-aws mentioned this pull request Oct 4, 2022

Start documentation for Client Helpers #827

Closed

kolchfa-aws added the backport 2.3 PR: Backport label for 2.3 label Oct 6, 2022

Incorporated tech review feedback

884a6bb

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws added the 5 - Editorial review PR: Editorial review in progress label Oct 10, 2022

natebower reviewed Oct 11, 2022

View reviewed changes

natebower removed the 5 - Editorial review PR: Editorial review in progress label Oct 11, 2022

Implemented editorial comments

9830bbb

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws merged commit 89f966a into main Oct 11, 2022

opensearch-trigger-bot bot mentioned this pull request Oct 11, 2022

[Backport 2.3] Refactors JS client helper documentation #1511

Merged

Naarcha-AWS deleted the robdasilva-main branch December 13, 2022 19:53

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactors JS client helper documentation #1358

Refactors JS client helper documentation #1358

kolchfa-aws commented Sep 29, 2022 •

edited by Naarcha-AWS

Loading

kolchfa-aws commented Sep 29, 2022

nhtruong Sep 29, 2022

kolchfa-aws Sep 30, 2022

nhtruong Sep 29, 2022 •

edited

Loading

kolchfa-aws Sep 30, 2022

nhtruong left a comment

Naarcha-AWS left a comment

Naarcha-AWS Sep 30, 2022

kolchfa-aws Sep 30, 2022

alicejw1 Sep 30, 2022

kolchfa-aws Sep 30, 2022

alicejw1 left a comment

natebower left a comment

natebower Oct 11, 2022

natebower Oct 11, 2022

natebower Oct 11, 2022

natebower Oct 11, 2022

natebower Oct 11, 2022

natebower Oct 11, 2022

natebower Oct 11, 2022

Option	Data type	Required / Default	Description
`datasource`	An array, async generator or a readable stream of strings or objects	REQUIRED	Represents the documents you need to create, delete, index or update.
`concurrency`	Integer	5	The number of requests to be executed in parallel.
`flushBytes`	Integer	5,000,000.	Maximum bulk body size to send in bytes.


		# Helper methods

		This section is currently incomplete. It does not yet cover all helper methods and their options.


		OpenSearch provides clients for several popular programming languages, with more coming. In general, clients are compatible with clusters running the same major version of OpenSearch (`major.minor.patch`).
		OpenSearch provides clients for several popular programming languages, with more coming.


		When creating a new bulk helper instance, you can use the following configuration options.

		\| Option \| Data type \| Required/Default \| Description

	\| `datasource` \| An array, async generator or a readable stream of strings or objects \| Required \| Represents the documents you need to create, delete, index or update.
	\| `datasource` \| An array, async generator, or readable stream of strings or objects \| Required \| Represents the documents you need to create, delete, index, or update.

	\| `onDrop` \| Function \| Optional. Default is `noop`. \| A function to be invoked for every document that can’t be indexed after reaching the maximum amount of retries.
	\| `onDrop` \| Function \| Optional. Default is `noop`. \| A function to be invoked for every document that can’t be indexed after reaching the maximum number of retries.

	\| `refreshOnCompletion` \| Boolean \| Optional. Default is false. \| Whether or not a refresh should be run on all affected indices at the end of the bulk operation.
	\| `refreshOnCompletion` \| Boolean \| Optional. Default is false. \| Whether or not a refresh should be run on all affected indexes at the end of the bulk operation.


		#### Index

		The index operation creates a new document if it doesn’t exist, and recreates the document if it already exists.


		#### Update

		The update operation updates the document with the the fields being sent. The document must already exist in the index.

Refactors JS client helper documentation #1358

Refactors JS client helper documentation #1358

Conversation

kolchfa-aws commented Sep 29, 2022 • edited by Naarcha-AWS Loading

Description

Checklist

kolchfa-aws commented Sep 29, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nhtruong Sep 29, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nhtruong left a comment

Choose a reason for hiding this comment

Naarcha-AWS left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alicejw1 left a comment

Choose a reason for hiding this comment

natebower left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kolchfa-aws commented Sep 29, 2022 •

edited by Naarcha-AWS

Loading

nhtruong Sep 29, 2022 •

edited

Loading