Add or update documents

Add a list of documents or update them if they already exist.

If you send an already existing document (same id) the old document will be only partially updated according to the fields of the new document. Thus, any fields not present in the new document are kept and remained unchanged.

If the provided index does not exist, it will be created.

To completely overwrite a document, see add or replace documents route.

Use the reserved _geo object to add geo coordinates to a document. _geo is an object made of lat and lng field.

PUT /indexes/{indexUid}/documents

cURL

cURL

curl \
  -X PUT 'MEILISEARCH_URL/indexes/movies/documents' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    {
      "id": 287947,
      "title": "Shazam ⚡️",
      "genres": "comedy"
    }
  ]'

202

{
  "taskUid": 147,
  "indexUid": null,
  "status": "enqueued",
  "type": "documentAdditionOrUpdate",
  "enqueuedAt": "2024-08-08T17:05:55.791772Z"
}

Authorizations

Authorization · string · header · required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

const client = new MeiliSearch({
  host: 'MEILISEARCH_URL',
  apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});

Path Parameters

indexUid · string · required

Unique identifier of the index.

Query Parameters

primaryKey · string

The primary key field for uniquely identifying each document. This parameter is optional and can only be set the first time documents are added to an index. Subsequent attempts to specify it will be ignored if the primary key has already been set.

csvDelimiter · string · default: ,

Customize the csv delimiter when importing CSV documents.

customMetadata · string

A string that can be used to identify and filter tasks. This metadata is stored with the task and returned in task responses. Useful for tracking tasks from external systems or associating tasks with specific operations in your application.

skipCreation · boolean

When set to true, only updates existing documents and skips creating new ones. Documents that don't already exist in the index will be ignored. This is useful for partial updates where you only want to modify existing records without adding new ones.

Body

application/json

The body is of type any.

Response

202

application/json

Task successfully enqueued.

A summarized view of a task, returned when a task is enqueued

taskUid · integer<u-int32> · required

Unique sequential identifier of the task.

Required range: x >= 0

status · enum<string> · required

Status of the task. Possible values are enqueued, processing, succeeded, failed, and canceled.

Available options: enqueued, processing, succeeded, failed, canceled

Example:

"processing"

type · enum<string> · required

Type of operation performed by the task.

Available options: documentAdditionOrUpdate, documentEdition, documentDeletion, settingsUpdate, indexCreation, indexDeletion, indexUpdate, indexSwap, taskCancelation, taskDeletion, dumpCreation, snapshotCreation, export, upgradeDatabase, indexCompaction, networkTopologyChange

Example:

"documentAdditionOrUpdate"

enqueuedAt · string<date-time> · required

Date and time when the task was enqueued.

indexUid · string | null

Unique identifier of the targeted index. Null for global tasks.

customMetadata · string | null

Custom metadata attached to this task at creation. Use it to associate tasks with external systems or add application-specific information.