From af2c8a80d5d232ed41376a0982737a96e34873cc Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 17 Nov 2025 14:56:44 +0100 Subject: [PATCH 1/4] add info on custom metadata for document tasks --- reference/api/documents.mdx | 27 +++++++++++++++++++++++++++ reference/api/tasks.mdx | 8 +++++++- 2 files changed, 34 insertions(+), 1 deletion(-) diff --git a/reference/api/documents.mdx b/reference/api/documents.mdx index 69ad3776d9..efd359caad 100644 --- a/reference/api/documents.mdx +++ b/reference/api/documents.mdx @@ -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) | Configuring `csvDelimiter` and sending data with a content type other than CSV will cause Meilisearch to throw an error. @@ -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) | Configuring `csvDelimiter` and sending data with a content type other than CSV will cause Meilisearch to throw an error. @@ -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` @@ -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 @@ -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 @@ -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. @@ -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. diff --git a/reference/api/tasks.mdx b/reference/api/tasks.mdx index 6dbfd5ab2f..3b9b4c6d21 100644 --- a/reference/api/tasks.mdx +++ b/reference/api/tasks.mdx @@ -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 } ``` @@ -250,6 +251,11 @@ curl \ **Type**: String
**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
+**Description**: An arbitrary string optionally configured for `/document`-related tasks. 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: From aeeb172aee9215dc4057c8033799d6ff75c16d67 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Mon, 17 Nov 2025 13:57:22 +0000 Subject: [PATCH 2/4] Update code samples [skip ci] --- snippets/samples/code_samples_get_documents_1.mdx | 5 ++++- snippets/samples/code_samples_get_documents_post_1.mdx | 3 ++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/snippets/samples/code_samples_get_documents_1.mdx b/snippets/samples/code_samples_get_documents_1.mdx index f391ceffa3..199e8fe7cc 100644 --- a/snippets/samples/code_samples_get_documents_1.mdx +++ b/snippets/samples/code_samples_get_documents_1.mdx @@ -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 diff --git a/snippets/samples/code_samples_get_documents_post_1.mdx b/snippets/samples/code_samples_get_documents_post_1.mdx index a507357f04..6fac124c55 100644 --- a/snippets/samples/code_samples_get_documents_post_1.mdx +++ b/snippets/samples/code_samples_get_documents_post_1.mdx @@ -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 }) ``` From f61fa7e85b54b5b9cd247bd5022e8ca2c3b8ddec Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 17 Nov 2025 17:22:18 +0100 Subject: [PATCH 3/4] improve wording --- reference/api/tasks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/tasks.mdx b/reference/api/tasks.mdx index 3b9b4c6d21..d900756655 100644 --- a/reference/api/tasks.mdx +++ b/reference/api/tasks.mdx @@ -254,7 +254,7 @@ curl \ ### `customMetadata` **Type**: String
-**Description**: An arbitrary string optionally configured for `/document`-related tasks. Commonly used to keep track of which documents were processed in a specific task. +**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 From 2e078fff4dcf6dc82a08dd8ae4b4f96db967f82f Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 19 Nov 2025 17:54:21 +0100 Subject: [PATCH 4/4] improve wording, address reviewer feedback --- reference/api/documents.mdx | 14 +++++++------- reference/api/tasks.mdx | 9 ++------- 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/reference/api/documents.mdx b/reference/api/documents.mdx index efd359caad..aed9eb86af 100644 --- a/reference/api/documents.mdx +++ b/reference/api/documents.mdx @@ -256,7 +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) | +| **`customMetadata`** | `null` | An arbitrary string accessible via the [generated task object](/reference/api/tasks#custommetadata) | Configuring `csvDelimiter` and sending data with a content type other than CSV will cause Meilisearch to throw an error. @@ -379,7 +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) | +| **`customMetadata`** | `null` | An arbitrary string accessible via the [generated task object](/reference/api/tasks#custommetadata) | Configuring `csvDelimiter` and sending data with a content type other than CSV will cause Meilisearch to throw an error. @@ -453,7 +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) | +| **`customMetadata`** | `null` | An arbitrary string accessible via the [generated task object](/reference/api/tasks#custommetadata) | #### `function` @@ -494,7 +494,7 @@ Delete all documents in the specified index. | Query Parameter | Default Value | Description | | :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | -| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) | +| **`customMetadata`** | `null` | An arbitrary string accessible via the [generated task object](/reference/api/tasks#custommetadata) | ### Example @@ -531,7 +531,7 @@ Delete one document based on its unique id. | Query Parameter | Default Value | Description | | :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | -| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) | +| **`customMetadata`** | `null` | An arbitrary string accessible via the [generated task object](/reference/api/tasks#custommetadata) | ### Example @@ -567,7 +567,7 @@ Delete a set of documents based on a filter. | Query Parameter | Default Value | Description | | :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | -| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) | +| **`customMetadata`** | `null` | An arbitrary string accessible via the [generated task object](/reference/api/tasks#custommetadata) | ### Body @@ -619,7 +619,7 @@ Delete a set of documents based on an array of document ids. | Query Parameter | Default Value | Description | | :----------------- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------- | -| **`customMetadata`** | `null` | An arbitrary string accessible in the [generated task object](/reference/api/tasks#custommetadata) | +| **`customMetadata`** | `null` | An arbitrary string accessible via the [generated task object](/reference/api/tasks#custommetadata) | ### Body diff --git a/reference/api/tasks.mdx b/reference/api/tasks.mdx index d900756655..daa0e05fe8 100644 --- a/reference/api/tasks.mdx +++ b/reference/api/tasks.mdx @@ -35,8 +35,7 @@ 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", - "customMetadata": null + "finishedAt": "2022-08-04T12:28:15.163188Z" } ``` @@ -188,9 +187,7 @@ The `details` object is set to `null` for `snapshotCreation` tasks. | **`type`** | The [error type](/reference/errors/overview#errors) | | **`link`** | A link to the relevant section of the documentation | -### `network` - - +### `network` **Type**: Object
**Description**: If the task was replicated from another remote or to other remotes, `network` will contain information about the remote task uids corresponding to this task. Otherwise, missing in task object. @@ -229,8 +226,6 @@ curl \ ``` - - ### `duration` **Type**: String