Working with tasks

In this tutorial, you’ll use the Meilisearch API to add documents to an index, and then monitor its status.

Many Meilisearch operations are processed asynchronously in a task. Asynchronous tasks allow you to make resource-intensive changes to your Meilisearch project without any downtime for users.

In this tutorial, you’ll use the Meilisearch API to add documents to an index, and then monitor its status.

Requirements

• a running Meilisearch project
• a command-line console

Adding a task to the task queue

Operations that require indexing, such as adding and updating documents or changing an index’s settings, will always generate a task.

Start by creating an index, then add a large number of documents to this index:

cURL

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/documents'\
  -H 'Content-Type: application/json' \
  --data-binary @movies.json

Instead of processing your request immediately, Meilisearch will add it to a queue and return a summarized task object:

{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentAdditionOrUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

The summarized task object is confirmation your request has been accepted. It also gives you information you can use to monitor the status of your request, such as the taskUid.

You can add documents to a new Meilisearch Cloud index using the Cloud interface. To get the taskUid of this task, visit the “Task” overview and look for a “Document addition or update” task associated with your newly created index.

Monitoring task status

Meilisearch processes tasks in the order they were added to the queue. You can check the status of a task using the Meilisearch Cloud interface or the Meilisearch API.

Monitoring task status in the Meilisearch Cloud interface

Log into your Meilisearch Cloud account and navigate to your project. Click the “Tasks” link in the project menu:

This will lead you to the task overview. Look for your request’s taskUid in the “Uid” column:

When the task status changes to succeeded, Meilisearch has finished processing your request.

If the task status changes to failed, Meilisearch was not able to fulfill your request. Check the task object’s error field for more information.

Monitoring task status with the Meilisearch API

Use the taskUid from your request’s response to check the status of a task:

cURL

curl \
  -X GET 'MEILISEARCH_URL/tasks/1'

This will return the full task object:

{
  "uid": 4,
  "indexUid" :"movie",
  "status": "succeeded",
  "type": "documentAdditionOrUpdate",
  "canceledBy": null,
  "details": {
    …
  },
  "error": null,
  "duration": "PT0.001192S",
  "enqueuedAt": "2022-08-04T12:28:15.159167Z",
  "startedAt": "2022-08-04T12:28:15.161996Z",
  "finishedAt": "2022-08-04T12:28:15.163188Z"
}

If the task is still enqueued or processing, wait a few moments and query the database once again. If you are working with a self-hosted Meilisearch instance, you may also set up a webhook listener.

When status changes to succeeded, Meilisearch has finished processing your request.

If the task status changes to failed, Meilisearch was not able to fulfill your request. Check the task object’s error field for more information.

Conclusion

You have seen what happens when an API request adds a task to the task queue, and how to check the status of a that task. Consult the task API reference and the asynchronous operations explanation for more information on how tasks work.