Import

Create, update or delete large amount of documents as fast as possible.

This route is faster than the document:m* routes family (e.g. document:mCreate), but no real-time notifications will be generated, even if some of the documents in the import match subscription filters.

If some documents actions fail, the client will receive a PartialError error.


Copied to clipboard!
import (bulkData, [options])

Arguments Type Description
bulkData
object[]
List of documents to be added to the collection
options
object
Query options

bulkData

This API takes a JSON array containing a list of objects working in pairs. In each pair, the first object specifies the action to perform (the most common is create) and the second specifies the document itself, like in the example below:

Copied to clipboard!
[
  // The action object
  { create: { _id: 'id', _index: 'index', _type: 'collection' } },
  // The document object
  { myField: 'myValue', myOtherField: 'myOtherValue' },
  // Another action object
  { create: { _id: 'another-id', _index: 'index', _type: 'collection' } },
  // Another document object
  { myField: 'anotherValue', myOtherField: 'yetAnotherValue' }
];

Note that the action object always has an attribute whose key specifies the action to take and whose value is an object specifying the location of ano object in the database (the _index, _type and _id tuple). Also note that, in Elasticsearch, the field _type correspond to collection in Kuzzle.

Possible actions are create, index, update, delete.

Learn more at Elasticsearch Bulk API

options

Additional query options

Property Type
(default)
Description
queuable
boolean

(true)
If true, queues the request during downtime, until connected to Kuzzle again

Resolves

An object containing information about the import status for each document.

Property Type Description
errors
boolean
true if there is some errors with the import
items
object[]
Array of object containing document import statuses

Each object has the following structure:

Copied to clipboard!
{
  "<action>": {
    _id: "another-id",
    status: 201
  }
}

Usage

Copied to clipboard!
const bulkData = [
  { create: { _id: '1', _index: 'nyc-open-data', _type: 'yellow-taxi' } },
  { a: 'document', with: 'any', number: 'of fields' },
  { create: { _id: '2', _index: 'nyc-open-data', _type: 'yellow-taxi' } },
  { another: 'document' },
  { create: { _id: '3', _index: 'nyc-open-data', _type: 'yellow-taxi' } },
  { and: { another: 'one' } }
];

try {
  const response = await kuzzle.bulk.import(bulkData);
  console.log(response);
  /*
    { errors: false,
      items:
      [ {
        create: {
          _id: "uniq-id-1",
          status: 201
          }
        },
        {
          create: {
            _id: "uniq-id-2",
            status: 201
          }
        },
        {
          create: {
            _id: "uniq-id-3",
            status: 206
          }
        } ] }
  */
  const successfulImport = response.items.filter(item => item.create.status === 201);

  console.log(`Successfully imported ${successfulImport.length} documents`);
} catch (error) {
  console.error(error.message);
}