Create a task

A task connects one source table to one Meilisearch index. The wizard walks through six steps; every option it shows maps to a field of the task JSON used by the API and the tasks file.

Open Tasks → New task (admin role). The steps are Connector, Source, Mapping, Index, Sync & safety and Review. Errors are shown on the step they belong to, and the review lists anything left to fix.

1. Connector

Pick the saved connector to read from, or add one from the side panel without leaving the wizard. Credentials live in the connector only; the task never repeats them. See Connectors.

2. Source

Basics, then what to sync:

Test connection (moderator) connects through the connector, reads the table's schema and transforms five sample rows with the current mapping, so you see real documents before anything is written. It uses POST /api/v1/tasks/test. For PostgreSQL, testing also creates the task's publication if it does not exist yet.

3. Mapping

The mapping turns rows into documents.

Document identity

How document ids are built

• A single integer key is written as a number (42).
• Other single keys are written as strings. Values made only of a-z A-Z 0-9 - (integers, UUIDs, slugs) are kept as they are. Anything else is escaped into Meilisearch's id alphabet: _ becomes __ and every other byte becomes _XX (hex). For example user@example.com becomes user_40example_2Ecom. Escaped ids always contain _ and raw ones never do, so two different keys never collide.
• Composite keys join their escaped parts with - (a - inside a part is escaped too): (7, "fr") becomes 7-fr.
• Ids longer than 511 bytes are replaced by h- and a SHA-256 hex digest.
• A row without a value for a key column cannot become a document; it goes to the dead letter queue as a transform entry and the checkpoint moves on.

Two tasks may write to the same index (with the upsert write mode, to merge fields from several tables), but only with the same primary key field: saving a task whose key field differs from another task on that index and destination fails with 409.

Fields

Transforms

Static fields

mapping.static adds the same fields to every document, for example {"tenant": "acme", "source": "eu-db"}. This is handy for multi-tenant indexes fed by several tasks. Static fields overwrite source columns of the same name; the primary key field always wins.

4. Index

5. Sync & safety

Sync mode

Batching

Within a batch, changes to the same document are coalesced and only the final state is sent. Confirmations are processed in order, so checkpoints never skip an unconfirmed batch. See Performance and tuning.

Retry

Network errors, Meilisearch 5xx, 429 and 408 are retried. A payload that is too large is split in half. Documents Meilisearch rejects are isolated into the dead letter queue. Configuration errors (a bad API key, an index whose primary key differs) stop the task as failed. When the attempts run out, the pipeline restarts with its own backoff (1 s up to 1 minute) and the task shows retrying.

Safety guards

A held task has stopped before applying the risky batch, so nothing was lost and nothing was deleted. Look at the source, then Resume (the batch is retried, and holds again if the guard still applies), raise the guard, or Resync. The hold reason is in the task's status, for example safety hold: a single batch would delete 5000 of 8000 documents (62% > 20% limit) or safety hold: the source table was truncated; enable safety.allowTruncate or resync the task. The delete guard reads the index size at most every 10 seconds.

6. Review

The review summarises the task, shows its JSON and lists any field that needs attention. Create saves it stopped; Create & start starts it right away (API: POST /api/v1/tasks?start=true). Validation errors come back as 422 with one message per problem.

Task JSON reference

The full shape accepted by POST /api/v1/tasks, PUT /api/v1/tasks/{id}, import and the tasks file. Defaults are applied when a field is empty or zero.

{
  "id": "products",
  "name": "Postgres products",
  "description": "Catalog search",
  "tags": ["shop"],
  "desiredState": "running",
  "source": {
    "connectorId": "pg-main",
    "type": "postgres",
    "dsn": "postgres://cdc:secret@db:5432/shop",
    "database": "",
    "schema": "public",
    "table": "products",
    "slot": "",
    "publication": "",
    "serverId": 0,
    "region": "", "endpoint": "", "accessKeyId": "", "secretAccessKey": "",
    "brokers": [], "groupId": "",
    "driver": "", "cursorColumn": "", "pollInterval": "2s",
    "webhookSecret": ""
  },
  "mapping": {
    "primaryKey": ["id"],
    "primaryKeyField": "id",
    "keepKeyColumns": false,
    "include": [], "exclude": ["internal_notes"],
    "rename": {"customer_email": "email"},
    "softDeleteColumn": "deleted_at", "softDeleteValue": "",
    "geo": {"lat": "lat", "lng": "lng"},
    "timeFormat": "unix",
    "static": {"tenant": "acme"}
  },
  "index": {
    "uid": "products",
    "destinationId": "",
    "writeMode": "replace",
    "manageSettings": true,
    "settings": {"filterableAttributes": ["category"], "sortableAttributes": ["price"]}
  },
  "sync": {
    "mode": "snapshot_stream",
    "batchSize": 1000, "flushInterval": "1s", "maxInflight": 4,
    "retry": {"maxAttempts": 8, "initialBackoff": "200ms", "maxBackoff": "30s"},
    "safety": {
      "maxDeleteRatio": 0.2, "minDocsForDeleteGuard": 1000,
      "allowTruncate": false, "zeroDowntimeResync": true, "dumpBeforeResync": false
    }
  }
}

• Use connectorId or the inline connection fields (type, dsn, …), not both: with a connector, the connector's connection fields are used and type is taken from it.
• Durations are strings ("500ms", "2s"); a plain number is read as milliseconds.
• desiredState is running, stopped or paused; the API sets it through actions, the tasks file through this field.
• Responses add createdAt, updatedAt and a status object, and mask secrets as ••••••. Sending a masked value back keeps the stored secret.