From 6fe03bd388971cc676065185d6ec817d1546c67b Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 18 Nov 2025 19:21:08 +0100 Subject: [PATCH 1/4] add info on search personalization --- .code-samples.meilisearch.yaml | 2 +- docs.json | 1 + .../making_personalized_search_queries.mdx | 54 +++++++++++++++++++ .../search_personalization.mdx | 8 ++- .../experimental_features_overview.mdx | 1 + .../configure_meilisearch_at_launch.mdx | 9 ++++ reference/api/search.mdx | 15 ++++++ 7 files changed, 88 insertions(+), 2 deletions(-) create mode 100644 learn/personalization/making_personalized_search_queries.mdx diff --git a/.code-samples.meilisearch.yaml b/.code-samples.meilisearch.yaml index 33b8f35b72..81c50bf266 100644 --- a/.code-samples.meilisearch.yaml +++ b/.code-samples.meilisearch.yaml @@ -1295,7 +1295,7 @@ analytics_event_conversion_1: |- curl \ -X POST 'https://PROJECT_URL/events' \ -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' + -H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \ --data-binary '{ "eventType": "conversion", "eventName": "Product Added To Cart", diff --git a/docs.json b/docs.json index 1b1ecbef23..764f848db7 100644 --- a/docs.json +++ b/docs.json @@ -191,6 +191,7 @@ { "group": "Personalization", "pages": [ + "learn/personalization/making_personalized_search_queries", "learn/personalization/search_personalization" ] }, diff --git a/learn/personalization/making_personalized_search_queries.mdx b/learn/personalization/making_personalized_search_queries.mdx new file mode 100644 index 0000000000..c99f88870f --- /dev/null +++ b/learn/personalization/making_personalized_search_queries.mdx @@ -0,0 +1,54 @@ +--- +title: Performing personalized search queries +description: Search personalization uses context about the person performing the search to provide results more relevant to that specific user. This tutorial guides you through configuring and performing personalized search queries. +--- + +## Requirements + +- A Meilisearch project +- Self-hosted Meilisearch users: a Cohere API key + +## Activate personalized search + +### Cloud users + +Open a support ticket requesting Meilisearch to activate search personalization for your project. + +### Self-hosted users + +Relaunch your instance using the search personalization instance option: + +```sh +meilisearch --experimental-personalization-api-key="COHERE_API_KEY" +``` + +## Generating user context + +Search personalization requires a description about the user performing the search. Meilisearch does not currently provide automated generation of user context. + +You’ll need to **generate a dynamically plain-text user description** for each search request. This should summarize relevant traits, such as: + +- Category preferences like brand and size +- Price sensitivity +- Possible use cases +- Other information regarding user interests + +The re-ranking model is optimized to favor positive signals. For best results, focus on affirmatively stated preferences, behaviors, and affinities, such as "likes the color red" and "prefers cheaper brands" over "dislikes blue" and "is not interested in luxury brands". + +## Perform a personalized search + +Once search personalization is active and you have a pipeline in place to generate user profiles, you are ready to perform personalized searches. + +Submit a search query and include the `personalize` search parameter in your query. `personalize` must be an object with a single field, `userContext`. Use the description in `userContext`: + +```sh +curl \ + -X POST 'MEILISEARCH_URL/indexes/INDEX_NAME/search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "q": "wireless keyboard", + "personalize": { + "userContext": "The user prefers compact mechanical keyboards from Keychron or Logitech, with a mid-range budget and quiet keys for remote work." + } + }' +``` diff --git a/learn/personalization/search_personalization.mdx b/learn/personalization/search_personalization.mdx index 23cf0d836c..1fc5cedd38 100644 --- a/learn/personalization/search_personalization.mdx +++ b/learn/personalization/search_personalization.mdx @@ -20,6 +20,12 @@ For example, in an e-commerce site, someone who often shops for sportswear might ## How can I enable search personalization in Meilisearch? -Search personalization is still in early development and not publicly available. +Search personalization is an experimental feature. + +If you are a Meilisearch Cloud user, contact support to activate it for your projects. + +If you are self-hosting Meilisearch, relaunch it using the [search personalization instance option](/learn/self_hosted/configure_meilisearch_at_launch#search-personalization). + +early development and not publicly available. If you are a Cloud customer and would like to try it out, [get in touch](https://meetings-eu1.hubspot.com/guillaume-mourier/search-personalization)! diff --git a/learn/resources/experimental_features_overview.mdx b/learn/resources/experimental_features_overview.mdx index 536c71aa0e..25ef051c38 100644 --- a/learn/resources/experimental_features_overview.mdx +++ b/learn/resources/experimental_features_overview.mdx @@ -62,3 +62,4 @@ Activating or deactivating experimental features this way does not require you t | [Multimodal search](/reference/api/settings) | Enable multimodal search | API route | | [Disable new indexer](/learn/self_hosted/configure_meilisearch_at_launch) | Use previous settings indexer | CLI flag or environment variable | | [Experimental vector store](/reference/api/settings) | Enables index setting to use experimental vector store | API route | +| [Search personalization](/learn/personalization/making_personalized_search_queries) | Enables search personalization | CLI flag or environment variable | diff --git a/learn/self_hosted/configure_meilisearch_at_launch.mdx b/learn/self_hosted/configure_meilisearch_at_launch.mdx index d947ed4b83..255d90d0fa 100644 --- a/learn/self_hosted/configure_meilisearch_at_launch.mdx +++ b/learn/self_hosted/configure_meilisearch_at_launch.mdx @@ -552,6 +552,15 @@ Helps running Meilisearch in cluster environments. It does this by modifying tas Falls back to previous settings indexer. +### Search personalization + +**Environment variable**: `MEILI_EXPERIMENTAL_PERSONALIZATION_API_KEY`
+**CLI option**: `--experimental-personalization-api-key`
+**Default value**: `None`
+**Expected value**: a Cohere API key + +Enables search personalization. Must be a valid Cohere API key in string format. + ### S3 options #### Bucket URL diff --git a/reference/api/search.mdx b/reference/api/search.mdx index 5fc0cfaa07..6b38cbf244 100644 --- a/reference/api/search.mdx +++ b/reference/api/search.mdx @@ -99,6 +99,7 @@ By default, [this endpoint returns a maximum of 1000 results](/learn/resources/k | **[`retrieveVectors`](#display-_vectors-in-response)** | Boolean | `false` | Return document and query vector data | | **[`locales`](#query-locales)** | Array of strings | `null` | Explicitly specify languages used in a query | | **[`media`](#media)** | Object | `null` | Perform AI-powered search queries with multimodal content | +| **[`personalize`](#search-personalization)** | Object | `null` | Perform AI-powered searches that return different results based on a user's profile | ### Response @@ -1371,3 +1372,17 @@ It is mandatory to specify an embedder when using `media`. `media` is incompatib … } ``` + +### Search personalization + +**Parameter**: `personalize`
+**Expected value**: Object
+**Default value**: `null` + + +This is an experimental feature. Contact Meilisearch Cloud support to enable it for your projects. If self-hosting, relaunch your instance providing a Cohere key to the search personalization instance option. + + +Adds user context to [personalize search results according to user profile](/learn/personalization/making_personalized_search_queries). + +`personalize` must be an object. It must include a single field, `userContext`.`userContext` must be a string describing the user performing the search. From 90af32732aab631721110c8ad29da5fa1e54ccfd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 18 Nov 2025 18:21:49 +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 60b4f45f9a135151ab00795a80c6a3e48b1f8baa Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 19 Nov 2025 13:10:29 +0100 Subject: [PATCH 3/4] improve wording --- .../making_personalized_search_queries.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/learn/personalization/making_personalized_search_queries.mdx b/learn/personalization/making_personalized_search_queries.mdx index c99f88870f..207b97c8a6 100644 --- a/learn/personalization/making_personalized_search_queries.mdx +++ b/learn/personalization/making_personalized_search_queries.mdx @@ -1,6 +1,6 @@ --- title: Performing personalized search queries -description: Search personalization uses context about the person performing the search to provide results more relevant to that specific user. This tutorial guides you through configuring and performing personalized search queries. +description: Search personalization uses context about the person performing the search to provide results more relevant to that specific user. This article guides you through configuring and performing personalized search queries. --- ## Requirements @@ -26,12 +26,12 @@ meilisearch --experimental-personalization-api-key="COHERE_API_KEY" Search personalization requires a description about the user performing the search. Meilisearch does not currently provide automated generation of user context. -You’ll need to **generate a dynamically plain-text user description** for each search request. This should summarize relevant traits, such as: +You’ll need to **dynamically generate a plain-text user description** for each search request. This should summarize relevant traits, such as: -- Category preferences like brand and size -- Price sensitivity -- Possible use cases -- Other information regarding user interests +- Category preferences, like brand or size +- Price sensitivity, like budget-conscious +- Possible use cases, such as fitness and sport +- Other assorted information, such as general interests or location The re-ranking model is optimized to favor positive signals. For best results, focus on affirmatively stated preferences, behaviors, and affinities, such as "likes the color red" and "prefers cheaper brands" over "dislikes blue" and "is not interested in luxury brands". @@ -39,7 +39,7 @@ The re-ranking model is optimized to favor positive signals. For best results, f Once search personalization is active and you have a pipeline in place to generate user profiles, you are ready to perform personalized searches. -Submit a search query and include the `personalize` search parameter in your query. `personalize` must be an object with a single field, `userContext`. Use the description in `userContext`: +Submit a search query and include the `personalize` search parameter. `personalize` must be an object with a single field, `userContext`. Use the description you generated in the previous step as the value for `userContext`: ```sh curl \ From 7077505f707200f2f587018ca559fdbea6307a17 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 19 Nov 2025 13:12:41 +0100 Subject: [PATCH 4/4] remove unused text from final draft --- learn/personalization/search_personalization.mdx | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/learn/personalization/search_personalization.mdx b/learn/personalization/search_personalization.mdx index 1fc5cedd38..c0f1812094 100644 --- a/learn/personalization/search_personalization.mdx +++ b/learn/personalization/search_personalization.mdx @@ -18,7 +18,7 @@ For example, in an e-commerce site, someone who often shops for sportswear might 3. Meilisearch retrieves documents based on the user's query as usual 4. Finally, the re-ranking model reorders results based on the user context you provided in the first step -## How can I enable search personalization in Meilisearch? +## How to enable search personalization in Meilisearch? Search personalization is an experimental feature. @@ -26,6 +26,4 @@ If you are a Meilisearch Cloud user, contact support to activate it for your pro If you are self-hosting Meilisearch, relaunch it using the [search personalization instance option](/learn/self_hosted/configure_meilisearch_at_launch#search-personalization). -early development and not publicly available. - -If you are a Cloud customer and would like to try it out, [get in touch](https://meetings-eu1.hubspot.com/guillaume-mourier/search-personalization)! +Consult the [search personalization guide](/learn/personalization/making_personalized_search_queries) for more information on how to implement it in your application.