Skip to content

Commit 9a66e2c

Browse files
guimachiavellidureuill
guimachiavelli
and
dureuill
authored
Federated tutorial and explanation (#3002)
--------- Co-authored-by: Louis Dureuil <[email protected]>
1 parent 2e1af9c commit 9a66e2c

File tree

6 files changed

+227
-0
lines changed

6 files changed

+227
-0
lines changed

‎assets/datasets/crm-chats.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
[
2+
{
3+
"id": 0,
4+
"client_name": "Natasha Nguyen",
5+
"message": "My email is [email protected]",
6+
"time": 1727349362
7+
},
8+
{
9+
"id": 1,
10+
"client_name": "Riccardo Rotondo",
11+
"message": "No, I changed my email, it's no longer [email protected], the one you see on my profile is the right one",
12+
"time": 1726344418
13+
}
14+
]

‎assets/datasets/crm-profiles.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
[
2+
{
3+
"id": 0,
4+
"name": "Natasha Nguyen",
5+
"email": "[email protected]"
6+
},
7+
{
8+
"id": 1,
9+
"name": "Riccardo Rotondo",
10+
"email": "[email protected]"
11+
}
12+
]

‎assets/datasets/crm-tickets.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
[
2+
{
3+
"id": 0,
4+
"time": 1727349362,
5+
"client_name": "Natasha Nguyen",
6+
"type": "complaint",
7+
"title": "I'm not receiving any emails"
8+
},
9+
{
10+
"id": 1,
11+
"time": 1701448312,
12+
"client_name": "Riccardo Rotondo",
13+
"type": "support",
14+
"title": "Please remove my email from your mailing list"
15+
}
16+
]

‎config/sidebar-learn.json‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -253,6 +253,22 @@
253253
}
254254
]
255255
},
256+
{
257+
"title": "Multi-search",
258+
"slug": "multi_search",
259+
"routes": [
260+
{
261+
"source": "learn/multi_search/performing_federated_search.mdx",
262+
"label": "Using multi-search to perform a federated search",
263+
"slug": "performing_federated_search"
264+
},
265+
{
266+
"source": "learn/multi_search/multi_search_vs_federated_search.mdx",
267+
"label": "Differences between multi-search and federated search",
268+
"slug": "multi_search_vs_federated_search"
269+
}
270+
]
271+
},
256272
{
257273
"title": "Update and migration",
258274
"slug": "update_and_migration",

‎learn/multi_search/multi_search_vs_federated_search.mdx‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: Differences between multi-search and federated search — Meilisearch API reference
3+
description: This article defines multi-search and federated search and then describes the different uses of each.
4+
---
5+
6+
# Differences between multi-search and federated search
7+
8+
This article defines multi-search and federated search and then describes the different uses of each.
9+
10+
## What is multi-search?
11+
12+
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.
13+
14+
Multi-search favors discovery scenarios, where users might not have a clear idea of what they need and searches might have many valid results.
15+
16+
## What is federated search?
17+
18+
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.
19+
20+
Federated search favors scenarios where users have a clear idea of what they need and expect a single best top result.
21+
22+
## Use cases
23+
24+
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.
25+
26+
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.

‎learn/multi_search/performing_federated_search.mdx‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
title: Using multi-search to perform a federated search — Meilisearch API reference
3+
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.
4+
---
5+
6+
# Using multi-search to perform a federated search
7+
8+
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.
9+
10+
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.
11+
12+
## Requirements
13+
14+
- A running Meilisearch project
15+
- A command-line console
16+
17+
## Create three indexes
18+
19+
Download the following datasets: <a href="/assets/datasets/crm-chats.json">`crm-chats.json`</a>, <a href="/assets/datasets/crm-profiles.json">`crm-profiles.json`</a>, and <a href="/assets/datasets/crm-tickets.json">`crm-tickets.json`</a> containing data from a fictional CRM application.
20+
21+
Add the datasets to Meilisearch and create three separate indexes, `profiles`, `chats`, and `tickets`:
22+
23+
```sh
24+
curl -X POST 'http://localhost:7700/indexes/profiles' -H 'Content-Type: application/json' --data-binary @crm-profiles.json &&
25+
curl -X POST 'http://localhost:7700/indexes/chats' -H 'Content-Type: application/json' --data-binary @crm-chats.json &&
26+
curl -X POST 'http://localhost:7700/indexes/tickets' -H 'Content-Type: application/json' --data-binary @crm-tickets.json
27+
```
28+
29+
[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.
30+
31+
## Perform a federated search
32+
33+
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.
34+
35+
Use the `/multi-search` endpoint with the `federation` parameter to query the three indexes simultaneously:
36+
37+
```sh
38+
curl \
39+
-X POST 'http://localhost:7700/multi-search' \
40+
-H 'Content-Type: application/json' \
41+
--data-binary '{
42+
"federation": {},
43+
"queries": [
44+
{
45+
"indexUid": "chats",
46+
"q": "natasha"
47+
},
48+
{
49+
"indexUid": "profiles",
50+
"q": "natasha"
51+
},
52+
{
53+
"indexUid": "tickets",
54+
"q": "natasha"
55+
}
56+
]
57+
}'
58+
```
59+
60+
Meilisearch should respond with a single list of search results:
61+
62+
```json
63+
{
64+
"hits": [
65+
{
66+
"id": 0,
67+
"client_name": "Natasha Nguyen",
68+
"message": "My email is [email protected]",
69+
"time": 1727349362,
70+
"_federation": {
71+
"indexUid": "chats",
72+
"queriesPosition": 0
73+
}
74+
},
75+
…
76+
],
77+
"processingTimeMs": 0,
78+
"limit": 20,
79+
"offset": 0,
80+
"estimatedTotalHits": 3,
81+
"semanticHitCount": 0
82+
}
83+
```
84+
85+
## Promote results from a specific index
86+
87+
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.
88+
89+
Use the `weight` property of the `federation` parameter to boost results coming from a specific query:
90+
91+
```sh
92+
curl \
93+
-X POST 'http://localhost:7700/multi-search' \
94+
-H 'Content-Type: application/json' \
95+
--data-binary '{
96+
"federation": {},
97+
"queries": [
98+
{
99+
"indexUid": "chats",
100+
"q": "rotondo"
101+
},
102+
{
103+
"indexUid": "profiles",
104+
"q": "rotondo",
105+
"federationOptions": {
106+
"weight": 1.2
107+
}
108+
},
109+
{
110+
"indexUid": "tickets",
111+
"q": "rotondo"
112+
}
113+
]
114+
}'
115+
```
116+
117+
This request will lead to results from the query targeting `profile` ranking higher than documents from other queries:
118+
119+
```json
120+
{
121+
"hits": [
122+
{
123+
"id": 1,
124+
"name": "Riccardo Rotondo",
125+
"email": "[email protected]",
126+
"_federation": {
127+
"indexUid": "profiles",
128+
"queriesPosition": 1
129+
}
130+
},
131+
…
132+
],
133+
"processingTimeMs": 0,
134+
"limit": 20,
135+
"offset": 0,
136+
"estimatedTotalHits": 3,
137+
"semanticHitCount": 0
138+
}
139+
```
140+
141+
## Conclusion
142+
143+
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.

0 commit comments

Comments
 (0)