Helper methods

Helper methods simplify the use of complicated API tasks.

Bulk helper

The bulk helper simplifies making complex bulk API requests.

Usage

The following code creates a bulk helper instance:

  1. const { Client } = require('@opensearch-project/opensearch')
  2. const documents = require('./docs.json')
  3. const client = new Client({ ... })
  4. const result = await client.helpers.bulk({
  5. datasource: documents,
  6. onDocument (doc) {
  7. return {
  8. index: { _index: 'example-index' }
  9. }
  10. }
  11. })
  12. console.log(result)

Bulk helper operations return an object with the following fields:

  1. {
  2. total: number,
  3. failed: number,
  4. retry: number,
  5. successful: number,
  6. time: number,
  7. bytes: number,
  8. aborted: boolean
  9. }

Bulk helper configuration options

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

OptionData typeRequired/DefaultDescription
datasourceAn array, async generator or a readable stream of strings or objectsRequiredRepresents the documents you need to create, delete, index, or update.
onDocumentFunctionRequiredA function to be invoked with each document in the given datasource. It returns the operation to be executed for this document. Optionally, the document can be manipulated for create and index operations by returning a new document as part of the function’s result.
concurrencyIntegerOptional. Default is 5.The number of requests to be executed in parallel.
flushBytesIntegerOptional. Default is 5,000,000.Maximum bulk body size to send in bytes.
flushIntervalIntegerOptional. Default is 30,000.Time in milliseconds to wait before flushing the body after the last document has been read.
onDropFunctionOptional. Default is noop.A function to be invoked for every document that can’t be indexed after reaching the maximum number of retries.
refreshOnCompletionBooleanOptional. Default is false.Whether or not a refresh should be run on all affected indexes at the end of the bulk operation.
retriesIntegerOptional. Defaults to the client’s maxRetries value.The number of times an operation is retried before onDrop is called for that document.
waitIntegerOptional. Default is 5,000.Time in milliseconds to wait before retrying an operation.

Examples

The following examples illustrate the index, create, update, and delete bulk helper operations.

Index

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

The following bulk operation indexes documents into example-index:

  1. client.helpers.bulk({
  2. datasource: arrayOfDocuments,
  3. onDocument (doc) {
  4. return {
  5. index: { _index: 'example-index' }
  6. }
  7. }
  8. })

The following bulk operation indexes documents into example-index with document overwrite:

  1. client.helpers.bulk({
  2. datasource: arrayOfDocuments,
  3. onDocument (doc) {
  4. return [
  5. {
  6. index: { _index: 'example-index' }
  7. },
  8. { ...doc, createdAt: new Date().toISOString() }
  9. ]
  10. }
  11. })

Create

The create operation creates a new document only if the document does not already exist.

The following bulk operation creates documents in the example-index:

  1. client.helpers.bulk({
  2. datasource: arrayOfDocuments,
  3. onDocument (doc) {
  4. return {
  5. create: { _index: 'example-index', _id: doc.id }
  6. }
  7. }
  8. })

The following bulk operation creates documents in the example-index with document overwrite:

  1. client.helpers.bulk({
  2. datasource: arrayOfDocuments,
  3. onDocument (doc) {
  4. return [
  5. {
  6. create: { _index: 'example-index', _id: doc.id }
  7. },
  8. { ...doc, createdAt: new Date().toISOString() }
  9. ]
  10. }
  11. })

Update

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

The following bulk operation updates documents in the arrayOfDocuments:

  1. client.helpers.bulk({
  2. datasource: arrayOfDocuments,
  3. onDocument (doc) {
  4. // The update operation always requires a tuple to be returned, with the
  5. // first element being the action and the second being the update options.
  6. return [
  7. {
  8. update: { _index: 'example-index', _id: doc.id }
  9. },
  10. { doc_as_upsert: true }
  11. ]
  12. }
  13. })

The following bulk operation updates documents in the arrayOfDocuments with document overwrite:

  1. client.helpers.bulk({
  2. datasource: arrayOfDocuments,
  3. onDocument (doc) {
  4. return [
  5. {
  6. update: { _index: 'example-index', _id: doc.id }
  7. },
  8. {
  9. doc: { ...doc, createdAt: new Date().toISOString() },
  10. doc_as_upsert: true
  11. }
  12. ]
  13. }
  14. })

Delete

The delete operation deletes a document.

The following bulk operation deletes documents from the example-index:

  1. client.helpers.bulk({
  2. datasource: arrayOfDocuments,
  3. onDocument (doc) {
  4. return {
  5. delete: { _index: 'example-index', _id: doc.id }
  6. }
  7. }
  8. })