Skip to content

Add info on custom metadata for document tasks #3401

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Nov 19, 2025
Merged

Add info on custom metadata for document tasks #3401

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
af2c8a8
add info on custom metadata for document tasks
guimachiavelli Nov 17, 2025
aeeb172
Update code samples [skip ci]
github-actions[bot] Nov 17, 2025
f61fa7e
improve wording
guimachiavelli Nov 17, 2025
f69ef6b
Merge branch 'exp-698-task-custom-metadata' of github.com:meilisearch…
guimachiavelli Nov 17, 2025
2e078ff
improve wording, address reviewer feedback
guimachiavelli Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 27 additions & 0 deletions reference/api/documents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -256,6 +256,7 @@ This endpoint accepts the following content types:
| :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **`primaryKey`** | `null` | [Primary key](/learn/getting_started/primary_key#primary-field) of the index |
| **`csvDelimiter`** | `","` | Configure the character separating CSV fields. Must be a string containing [one ASCII character](https://www.rfc-editor.org/rfc/rfc20). |
| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) |

<Warning>
Configuring `csvDelimiter` and sending data with a content type other than CSV will cause Meilisearch to throw an error.
Expand Down Expand Up @@ -378,6 +379,7 @@ This endpoint accepts the following content types:
| :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **`primaryKey`** | `null` | [Primary key](/learn/getting_started/primary_key#primary-field) of the documents |
| **`csvDelimiter`** | `","` | Configure the character separating CSV fields. Must be a string containing [one ASCII character](https://www.rfc-editor.org/rfc/rfc20). |
| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) |

<Warning>
Configuring `csvDelimiter` and sending data with a content type other than CSV will cause Meilisearch to throw an error.
Expand Down Expand Up @@ -451,6 +453,7 @@ curl \
| **`function`** | `null` | A string containing a RHAI function |
| **`filter`** | `null` | A string containing a filter expression |
| **`context`** | `null` | An object with data Meilisearch should make available for the editing function |
| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) |

#### `function`

Expand Down Expand Up @@ -487,6 +490,12 @@ Delete all documents in the specified index.
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

### Query parameters

| Query Parameter | Default Value | Description |
| :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) |

### Example

<CodeSamplesDeleteAllDocuments1 />
Expand Down Expand Up @@ -518,6 +527,12 @@ Delete one document based on its unique id.
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |
| **`document_id`** * | String/Integer | [Document id](/learn/getting_started/primary_key#document-id) of the requested document |

### Query parameters

| Query Parameter | Default Value | Description |
| :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) |

### Example

<CodeSamplesDeleteOneDocument1 />
Expand Down Expand Up @@ -548,6 +563,12 @@ Delete a set of documents based on a filter.
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

### Query parameters

| Query Parameter | Default Value | Description |
| :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) |

### Body

A filter expression written as a string or array of array of strings for the documents to be deleted.
Expand Down Expand Up @@ -594,6 +615,12 @@ Delete a set of documents based on an array of document ids.
| :---------------- | :----- | :--------------------------------------------------------------------- |
| **`index_uid`** * | String | [`uid`](/learn/getting_started/indexes#index-uid) of the requested index |

### Query parameters

| Query Parameter | Default Value | Description |
| :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- |
| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) |

### Body

An array of numbers containing the unique ids of the documents to be deleted.
Expand Down
8 changes: 7 additions & 1 deletion reference/api/tasks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,8 @@ The `/tasks` route gives information about the progress of [asynchronous operati
"duration": "PT0.001192S",
"enqueuedAt": "2022-08-04T12:28:15.159167Z",
"startedAt": "2022-08-04T12:28:15.161996Z",
"finishedAt": "2022-08-04T12:28:15.163188Z"
"finishedAt": "2022-08-04T12:28:15.163188Z",
"customMetadata": null
}
```

Expand Down Expand Up @@ -250,6 +251,11 @@ curl \
**Type**: String<br />
**Description**: The date and time when the task finished `processing`, whether `failed`, `succeeded`, or `canceled`, in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format

### `customMetadata`

**Type**: String<br />
**Description**: An arbitrary string optionally configured for tasks adding, updating, and deleting documents. Commonly used to keep track of which documents were processed in a specific task.

### Summarized task object

When an API request triggers an asynchronous process, Meilisearch returns a summarized task object. This object contains the following fields:
Expand Down
5 changes: 4 additions & 1 deletion snippets/samples/code_samples_get_documents_1.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,10 @@ client.index('movies').getDocuments({
```

```python Python
client.index('movies').get_documents({'limit':2, 'filter': 'genres=action'})
client.index('movies').get_documents({
'limit':2, 'filter': 'genres=action',
'sort': ['rating:desc', 'release_date:asc'] # list format
})
```

```php PHP
Expand Down
3 changes: 2 additions & 1 deletion snippets/samples/code_samples_get_documents_post_1.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ client.index('books').getDocuments({
client.index('books').get_documents({
'limit':3,
'fields': ['title', 'genres', 'rating', 'language'],
'filter': '(rating > 3 AND (genres=Adventure OR genres=Fiction)) AND language=English'
'filter': '(rating > 3 AND (genres=Adventure OR genres=Fiction)) AND language=English',
'sort': 'rating:desc, title:asc' # comma-separated string format
})
```

Expand Down