From 67eff7e14de8c7ce63ad1d07676880875c46fc4b Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 26 Sep 2024 16:16:56 +0200 Subject: [PATCH 1/7] add federated search guide --- assets/datasets/crm-chats.json | 14 ++ assets/datasets/crm-profiles.json | 12 ++ assets/datasets/crm-tickets.json | 17 +++ config/sidebar-learn.json | 11 ++ learn/multi_search/federated_search_guide.mdx | 141 ++++++++++++++++++ 5 files changed, 195 insertions(+) create mode 100644 assets/datasets/crm-chats.json create mode 100644 assets/datasets/crm-profiles.json create mode 100644 assets/datasets/crm-tickets.json create mode 100644 learn/multi_search/federated_search_guide.mdx diff --git a/assets/datasets/crm-chats.json b/assets/datasets/crm-chats.json new file mode 100644 index 000000000..7b448c9d5 --- /dev/null +++ b/assets/datasets/crm-chats.json @@ -0,0 +1,14 @@ +[ + { + "id": 0, + "client_name": "Natasha Nguyen", + "message": "My email is natasha.nguyen@example.com", + "time": 1727349362 + }, + { + "id": 1, + "client_name": "Riccardo Rotondo", + "message": "No, I changed my email, it's no longer rotondino@example.com, the one you see on my profile is the right one", + "time": 1726344418 + } +] \ No newline at end of file diff --git a/assets/datasets/crm-profiles.json b/assets/datasets/crm-profiles.json new file mode 100644 index 000000000..204e38ddc --- /dev/null +++ b/assets/datasets/crm-profiles.json @@ -0,0 +1,12 @@ +[ + { + "id": 0, + "name": "Natasha Nguyen", + "email": "natasha.nguyen@example.com" + }, + { + "id": 1, + "name": "Riccardo Rotondo", + "email": "riccardo.rotondo@example.com" + } +] diff --git a/assets/datasets/crm-tickets.json b/assets/datasets/crm-tickets.json new file mode 100644 index 000000000..83505844d --- /dev/null +++ b/assets/datasets/crm-tickets.json @@ -0,0 +1,17 @@ +[ + { + "id": 0, + "time": 1727349362, + "client_name": "Natasha Nguyen", + "type": "complaint", + "title": "I'm not receiving any emails" + }, + { + "id": 1, + "time": 1701448312, + "client_name": "Riccardo Rotondo", + "type": "support", + "title": "Please remove my email from your mailing list" + } +] + diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index f8b4ed8d6..73e3fc507 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -253,6 +253,17 @@ } ] }, + { + "title": "Multi-search", + "slug": "multi_search", + "routes": [ + { + "source": "learn/multi_search/federated_search_guide.mdx", + "label": "Federated search guide", + "slug": "federated_search_guide" + } + ] + }, { "title": "Update and migration", "slug": "update_and_migration", diff --git a/learn/multi_search/federated_search_guide.mdx b/learn/multi_search/federated_search_guide.mdx new file mode 100644 index 000000000..eef5948bb --- /dev/null +++ b/learn/multi_search/federated_search_guide.mdx @@ -0,0 +1,141 @@ +--- +title: Federated search guide — Meilisearch API reference +description: +--- + +# Federated search guide + +A federated search is a multi-index search that returns results across multiple indexes in a single list. + +In this guide you will see how to create separate indexes containing different types of data from a CRM application. You will then perform a query searching all these indexes at the same time to obtain a single list of results. + +## Requirements + +- A running Meilisearch project +- A command-line console + +## Create three indexes + +Download the following datasets: `crm-chats.json`, `crm-profiles.json`, and `crm-tickets.json` containing customer interaction data. Add them to Meilisearch, creating three separate indexes, `profiles`, `chats`, and `tickets`: + +```sh +curl -X POST 'http://localhost:7700/indexes/profiles' -H 'Content-Type: application/json' --data-binary @crm-profiles.json && +curl -X POST 'http://localhost:7700/indexes/chats' -H 'Content-Type: application/json' --data-binary @crm-chats.json && +curl -X POST 'http://localhost:7700/indexes/tickets' -H 'Content-Type: application/json' --data-binary @crm-tickets.json +``` + +Use the tasks endpoint to check the indexing status. Once Meilisearch successfully indexed all three datasets, you are ready to perform a federated search. + +## Perform a federated search + +When you are looking for Natasha Nguyen's email address in your CRM application, you may not know whether you will find it in a chat log, among the existing customer profiles, or in a recent support ticket. In this situation, you can use federated search to search across all possible sources and receive a single list of results. + +Use the `/multi-search` endpoint with the `federation` parameter to query the three indexes simultaneously: + +```sh +curl \ + -X POST 'http://localhost:7700/multi-search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "federation": {}, + "queries": [ + { + "indexUid": "chats", + "q": "natasha" + }, + { + "indexUid": "profiles", + "q": "natasha" + }, + { + "indexUid": "tickets", + "q": "natasha" + } + ] + }' +``` + +Meilisearch should respond with a single list of search results: + +```json +{ + "hits": [ + { + "id": 0, + "client_name": "Natasha Nguyen", + "message": "My email is natasha.nguyen@example.com", + "time": 1727349362, + "_federation": { + "indexUid": "chats", + "queriesPosition": 0 + } + }, + … + ], + "processingTimeMs": 0, + "limit": 20, + "offset": 0, + "estimatedTotalHits": 3, + "semanticHitCount": 0 +} +``` + +## Promote results from an index + +Since this is a CRM application, it is likely your users have profiles where they specified their preferred contact information. If you want to search for Riccardo Rotondo's official preferred email, you can boost documents in the `profiles` index. + +Use the `weight` property of the `federation` parameter to boost results coming from a specific index: + +```sh +curl \ + -X POST 'http://localhost:7700/multi-search' \ + -H 'Content-Type: application/json' \ + --data-binary '{ + "federation": {}, + "queries": [ + { + "indexUid": "chats", + "q": "rotondo" + }, + { + "indexUid": "profiles", + "q": "rotondo", + "federationOptions": { + "weight": 1.2 + } + }, + { + "indexUid": "tickets", + "q": "rotondo" + } + ] + }' +``` + +This query will result in `profile` results ranking higher than documents in other indexes: + +```json +{ + "hits": [ + { + "id": 1, + "name": "Riccardo Rotondo", + "email": "riccardo.rotondo@example.com", + "_federation": { + "indexUid": "profiles", + "queriesPosition": 1 + } + }, + … + ], + "processingTimeMs": 0, + "limit": 20, + "offset": 0, + "estimatedTotalHits": 3, + "semanticHitCount": 0 +} +``` + +## Conclusion + +You have created three indexes, then performed a federated multi-index search to receive all results in a single list. You then used `weight` to boost results from the index most likely to contain the information you wanted. From 3d53cd41f408a7569e7c724304b6044dd0b1adad Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 26 Sep 2024 17:37:39 +0200 Subject: [PATCH 2/7] add fed vs multi search explanation --- config/sidebar-learn.json | 5 ++++ .../multi_search_vs_federated_search.mdx | 26 +++++++++++++++++++ 2 files changed, 31 insertions(+) create mode 100644 learn/multi_search/multi_search_vs_federated_search.mdx diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index 73e3fc507..a859b6439 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -261,6 +261,11 @@ "source": "learn/multi_search/federated_search_guide.mdx", "label": "Federated search guide", "slug": "federated_search_guide" + }, + { + "source": "learn/multi_search/multi_search_vs_federated_search.mdx", + "label": "Differences between multi-search and federated search", + "slug": "multi_search_vs_federated_search" } ] }, diff --git a/learn/multi_search/multi_search_vs_federated_search.mdx b/learn/multi_search/multi_search_vs_federated_search.mdx new file mode 100644 index 000000000..4deb835b0 --- /dev/null +++ b/learn/multi_search/multi_search_vs_federated_search.mdx @@ -0,0 +1,26 @@ +--- +title: Differences between multi-search and federated search — Meilisearch API reference +description: +--- + +# Differences between multi-search and federated search + +This article describes the different uses of federated search and multi-search. + +## What is multi-search? + +Multi-search, also called multi-index search, is a search operation that queries two or more indexes at the same time. Meilisearch returns a separated list results for each index. Use the `/multi-search` route to perform multi-searches. + +Multi-search favors discovery scenarios, where searches might have several valid results. + +## What is federated search? + +Federated search is a type of multi-index search. This operation also queries multiple indexes, but returns a single list with the most relevant results across all queried indexes. Use the `/multi-search` route and specify a non-null value for `federation` to perform a federated search. + +Federated search favors scenarios where users have a clear idea of what they need and expect a single best top result. + +## Use cases + +Because multi-search groups results by index, it is often useful when a document's index contains information relevant to your users. For example, a person searching for `shygirl` in a music streaming application is likely to appreciate seeing separate results for matching artists, albums, and individual tracks. + +Federated search is a better approach when the source of the information is not relevant to your users. For example, a person searching for a client's email in a CRM application is unlikely to care whether this email comes from chat logs, support tickets, or other data sources. \ No newline at end of file From 8e223c8c98dd51eb527b51e85be3bf2b590f4f38 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 30 Sep 2024 18:14:25 +0200 Subject: [PATCH 3/7] first drafts ready --- config/sidebar-learn.json | 6 +++--- .../multi_search_vs_federated_search.mdx | 14 ++++++------- ...de.mdx => performing_federated_search.mdx} | 20 ++++++++++--------- 3 files changed, 21 insertions(+), 19 deletions(-) rename learn/multi_search/{federated_search_guide.mdx => performing_federated_search.mdx} (70%) diff --git a/config/sidebar-learn.json b/config/sidebar-learn.json index a859b6439..b2debe918 100644 --- a/config/sidebar-learn.json +++ b/config/sidebar-learn.json @@ -258,9 +258,9 @@ "slug": "multi_search", "routes": [ { - "source": "learn/multi_search/federated_search_guide.mdx", - "label": "Federated search guide", - "slug": "federated_search_guide" + "source": "learn/multi_search/performing_federated_search.mdx", + "label": "Using multi-search to perform a federated search", + "slug": "performing_federated_search" }, { "source": "learn/multi_search/multi_search_vs_federated_search.mdx", diff --git a/learn/multi_search/multi_search_vs_federated_search.mdx b/learn/multi_search/multi_search_vs_federated_search.mdx index 4deb835b0..cfc9b8836 100644 --- a/learn/multi_search/multi_search_vs_federated_search.mdx +++ b/learn/multi_search/multi_search_vs_federated_search.mdx @@ -1,26 +1,26 @@ --- title: Differences between multi-search and federated search — Meilisearch API reference -description: +description: This article defines multi-search and federated search and then describes the different uses of each. --- # Differences between multi-search and federated search -This article describes the different uses of federated search and multi-search. +This article defines multi-search and federated search and then describes the different uses of each. ## What is multi-search? -Multi-search, also called multi-index search, is a search operation that queries two or more indexes at the same time. Meilisearch returns a separated list results for each index. Use the `/multi-search` route to perform multi-searches. +Multi-search, also called multi-index search, is a search operation that queries two or more indexes at the same time. Meilisearch then returns a separate list results for each index. Use the `/multi-search` route to perform multi-searches. -Multi-search favors discovery scenarios, where searches might have several valid results. +Multi-search favors discovery scenarios, where users might not have a clear idea of what they need and searches might have many valid results. ## What is federated search? -Federated search is a type of multi-index search. This operation also queries multiple indexes, but returns a single list with the most relevant results across all queried indexes. Use the `/multi-search` route and specify a non-null value for `federation` to perform a federated search. +Federated search is a type of multi-index search. This operation also queries multiple indexes, but returns a single list with the most relevant results from all queried indexes. Use the `/multi-search` route and specify a non-null value for `federation` to perform a federated search. Federated search favors scenarios where users have a clear idea of what they need and expect a single best top result. ## Use cases -Because multi-search groups results by index, it is often useful when a document's index contains information relevant to your users. For example, a person searching for `shygirl` in a music streaming application is likely to appreciate seeing separate results for matching artists, albums, and individual tracks. +Because multi-search groups results by index, it is often useful when the origin and type of document contain information relevant to your users. For example, a person searching for `shygirl` in a music streaming application is likely to appreciate seeing separate results for matching artists, albums, and individual tracks. -Federated search is a better approach when the source of the information is not relevant to your users. For example, a person searching for a client's email in a CRM application is unlikely to care whether this email comes from chat logs, support tickets, or other data sources. \ No newline at end of file +Federated search is a better approach when the source of the information is not relevant to your users. For example, a person searching for a client's email in a CRM application is unlikely to care whether this email comes from chat logs, support tickets, or other data sources. diff --git a/learn/multi_search/federated_search_guide.mdx b/learn/multi_search/performing_federated_search.mdx similarity index 70% rename from learn/multi_search/federated_search_guide.mdx rename to learn/multi_search/performing_federated_search.mdx index eef5948bb..0effaa623 100644 --- a/learn/multi_search/federated_search_guide.mdx +++ b/learn/multi_search/performing_federated_search.mdx @@ -1,13 +1,13 @@ --- -title: Federated search guide — Meilisearch API reference -description: +title: Using multi-search to perform a federated search — Meilisearch API reference +description: In this tutorial you will see how to perform a query searching multiple indexes at the same time to obtain a single list of results. --- -# Federated search guide +# Using multi-search to perform a federated search -A federated search is a multi-index search that returns results across multiple indexes in a single list. +Meilisearch allows you to search in multiple indexes at the same time with the `/multi-search` endpoint. A federated search is a multi-index search that returns results across multiple indexes in a single list. -In this guide you will see how to create separate indexes containing different types of data from a CRM application. You will then perform a query searching all these indexes at the same time to obtain a single list of results. +In this tutorial you will see how to create separate indexes containing different types of data from a CRM application. You will then perform a query searching all these indexes at the same time to obtain a single list of results. ## Requirements @@ -16,7 +16,9 @@ In this guide you will see how to create separate indexes containing different t ## Create three indexes -Download the following datasets: `crm-chats.json`, `crm-profiles.json`, and `crm-tickets.json` containing customer interaction data. Add them to Meilisearch, creating three separate indexes, `profiles`, `chats`, and `tickets`: +Download the following datasets: `crm-chats.json`, `crm-profiles.json`, and `crm-tickets.json` containing data from a fictional CRM application. + +Add the datasets to Meilisearch and create three separate indexes, `profiles`, `chats`, and `tickets`: ```sh curl -X POST 'http://localhost:7700/indexes/profiles' -H 'Content-Type: application/json' --data-binary @crm-profiles.json && @@ -24,7 +26,7 @@ curl -X POST 'http://localhost:7700/indexes/chats' -H 'Content-Type: applicati curl -X POST 'http://localhost:7700/indexes/tickets' -H 'Content-Type: application/json' --data-binary @crm-tickets.json ``` -Use the tasks endpoint to check the indexing status. Once Meilisearch successfully indexed all three datasets, you are ready to perform a federated search. +[Use the tasks endpoint](/learn/async/working_with_tasks) to check the indexing status. Once Meilisearch successfully indexed all three datasets, you are ready to perform a federated search. ## Perform a federated search @@ -80,9 +82,9 @@ Meilisearch should respond with a single list of search results: } ``` -## Promote results from an index +## Promote results from a specific index -Since this is a CRM application, it is likely your users have profiles where they specified their preferred contact information. If you want to search for Riccardo Rotondo's official preferred email, you can boost documents in the `profiles` index. +Since this is a CRM application, users have profiles with their preferred contact information. If you want to search for Riccardo Rotondo's preferred email, you can boost documents in the `profiles` index. Use the `weight` property of the `federation` parameter to boost results coming from a specific index: From ec8abafe9188cf3e2ba1225909ac7c8fd8df3468 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 30 Sep 2024 18:15:05 +0200 Subject: [PATCH 4/7] fix JSON formatting --- assets/datasets/crm-chats.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/assets/datasets/crm-chats.json b/assets/datasets/crm-chats.json index 7b448c9d5..569a62908 100644 --- a/assets/datasets/crm-chats.json +++ b/assets/datasets/crm-chats.json @@ -11,4 +11,4 @@ "message": "No, I changed my email, it's no longer rotondino@example.com, the one you see on my profile is the right one", "time": 1726344418 } -] \ No newline at end of file +] From 037c3e99824d375f05f86997605089e07a64a752 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 30 Sep 2024 18:15:49 +0200 Subject: [PATCH 5/7] fix JSON formatting --- assets/datasets/crm-tickets.json | 1 - 1 file changed, 1 deletion(-) diff --git a/assets/datasets/crm-tickets.json b/assets/datasets/crm-tickets.json index 83505844d..4a61886cb 100644 --- a/assets/datasets/crm-tickets.json +++ b/assets/datasets/crm-tickets.json @@ -14,4 +14,3 @@ "title": "Please remove my email from your mailing list" } ] - From 64b8f992be442bc26e395e5a1efe03b12b13b6cd Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 7 Oct 2024 19:06:21 +0200 Subject: [PATCH 6/7] address reviewer feedback --- learn/multi_search/multi_search_vs_federated_search.mdx | 6 +++--- learn/multi_search/performing_federated_search.mdx | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/learn/multi_search/multi_search_vs_federated_search.mdx b/learn/multi_search/multi_search_vs_federated_search.mdx index cfc9b8836..d8d275697 100644 --- a/learn/multi_search/multi_search_vs_federated_search.mdx +++ b/learn/multi_search/multi_search_vs_federated_search.mdx @@ -9,18 +9,18 @@ This article defines multi-search and federated search and then describes the di ## What is multi-search? -Multi-search, also called multi-index search, is a search operation that queries two or more indexes at the same time. Meilisearch then returns a separate list results for each index. Use the `/multi-search` route to perform multi-searches. +Multi-search, also called multi-index search, is a search operation that makes multiple queries at the same time. These queries may target different indexes. Meilisearch then returns a separate list results for each query. Use the `/multi-search` route to perform multi-searches. Multi-search favors discovery scenarios, where users might not have a clear idea of what they need and searches might have many valid results. ## What is federated search? -Federated search is a type of multi-index search. This operation also queries multiple indexes, but returns a single list with the most relevant results from all queried indexes. Use the `/multi-search` route and specify a non-null value for `federation` to perform a federated search. +Federated search is a type of multi-index search. This operation also makes multiple search requests at the same time, but returns a single list with the most relevant results from all queries. Use the `/multi-search` route and specify a non-null value for `federation` to perform a federated search. Federated search favors scenarios where users have a clear idea of what they need and expect a single best top result. ## Use cases -Because multi-search groups results by index, it is often useful when the origin and type of document contain information relevant to your users. For example, a person searching for `shygirl` in a music streaming application is likely to appreciate seeing separate results for matching artists, albums, and individual tracks. +Because multi-search groups results by query, it is often useful when the origin and type of document contain information relevant to your users. For example, a person searching for `shygirl` in a music streaming application is likely to appreciate seeing separate results for matching artists, albums, and individual tracks. Federated search is a better approach when the source of the information is not relevant to your users. For example, a person searching for a client's email in a CRM application is unlikely to care whether this email comes from chat logs, support tickets, or other data sources. diff --git a/learn/multi_search/performing_federated_search.mdx b/learn/multi_search/performing_federated_search.mdx index 0effaa623..1a90e68b4 100644 --- a/learn/multi_search/performing_federated_search.mdx +++ b/learn/multi_search/performing_federated_search.mdx @@ -5,7 +5,7 @@ description: In this tutorial you will see how to perform a query searching mult # Using multi-search to perform a federated search -Meilisearch allows you to search in multiple indexes at the same time with the `/multi-search` endpoint. A federated search is a multi-index search that returns results across multiple indexes in a single list. +Meilisearch allows you to make multiple search requests at the same time with the `/multi-search` endpoint. A federated search is a multi-search that returns results from multiple queries in a single list. In this tutorial you will see how to create separate indexes containing different types of data from a CRM application. You will then perform a query searching all these indexes at the same time to obtain a single list of results. From f69cf93031d6d0a2cbdf421feeb66c3e0d07499c Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 7 Oct 2024 19:09:35 +0200 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Louis Dureuil --- learn/multi_search/performing_federated_search.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/learn/multi_search/performing_federated_search.mdx b/learn/multi_search/performing_federated_search.mdx index 1a90e68b4..239a3f1c0 100644 --- a/learn/multi_search/performing_federated_search.mdx +++ b/learn/multi_search/performing_federated_search.mdx @@ -86,7 +86,7 @@ Meilisearch should respond with a single list of search results: Since this is a CRM application, users have profiles with their preferred contact information. If you want to search for Riccardo Rotondo's preferred email, you can boost documents in the `profiles` index. -Use the `weight` property of the `federation` parameter to boost results coming from a specific index: +Use the `weight` property of the `federation` parameter to boost results coming from a specific query: ```sh curl \ @@ -114,7 +114,7 @@ curl \ }' ``` -This query will result in `profile` results ranking higher than documents in other indexes: +This request will lead to results from the query targeting `profile` ranking higher than documents from other queries: ```json {