Similar documents experimental
The /similar route uses AI-powered search to return a number of documents similar to a target document.
Meilisearch exposes two routes for retrieving similar documents: POST and GET. In the majority of cases, POST will offer better performance and ease of use.
Activating `/similar`
This is an experimental feature. To use it, you must first enable and configure AI-powered search.
Get similar documents with POST
POST/indexes/{index_uid}/similar
Retrieve documents similar to a specific search result.
Path parameters
| Name | Type | Description |
|---|---|---|
index_uid * | String | uid of the requested index |
Body
| Parameter | Type | Default value | Description |
|---|---|---|---|
id | String or number | null | Identifier of the target document (mandatory) |
embedder | String | "default" | Embedder to use when computing recommendations. Mandatory |
attributesToRetrieve | Array of strings | ["*"] | Attributes to display in the returned documents |
offset | Integer | 0 | Number of documents to skip |
limit | Integer | 20 | Maximum number of documents returned |
filter | String | null | Filter queries by an attribute's value |
showRankingScore | Boolean | false | Display the global ranking score of a document |
showRankingScoreDetails | Boolean | false | Display detailed ranking score information |
rankingScoreThreshold | Number | null | Exclude results with low ranking scores |
retrieveVectors | Boolean | false | Return document vector data |
Example
curl \
-X POST 'http://localhost:7700/indexes/INDEX_NAME/similar' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer DEFAULT_SEARCH_API_KEY' \
--data-binary '{
"id": TARGET_DOCUMENT_ID,
"embedder": "EMBEDDER_NAME"
}'Response: 200 OK
{
"hits": [
{
"id": "299537",
"title": "Captain Marvel"
},
{
"id": "166428",
"title": "How to Train Your Dragon: The Hidden World"
}
{
"id": "287947",
"title": "Shazam!"
}
],
"id": "23",
"processingTimeMs": 0,
"limit": 20,
"offset": 0,
"estimatedTotalHits": 3
}
Get similar documents with GET
GET/indexes/{index_uid}/similar
Retrieve documents similar to a specific search result.
Path parameters
| Name | Type | Description |
|---|---|---|
index_uid * | String | uid of the requested index |
Query parameters
| Parameter | Type | Default value | Description |
|---|---|---|---|
id | String or number | null | Identifier of the target document (mandatory) |
embedder | String | "default" | Embedder to use when computing recommendations. Mandatory |
attributesToRetrieve | Array of strings | ["*"] | Attributes to display in the returned documents |
offset | Integer | 0 | Number of documents to skip |
limit | Integer | 20 | Maximum number of documents returned |
filter | String | null | Filter queries by an attribute's value |
showRankingScore | Boolean | false | Display the global ranking score of a document |
showRankingScoreDetails | Boolean | false | Display detailed ranking score information |
rankingScoreThreshold | Number | null | Exclude results with low ranking scores |
retrieveVectors | Boolean | false | Return document vector data |
Example
curl \
-X GET 'http://localhost:7700/indexes/INDEX_NAME/similar?id=TARGET_DOCUMENT_ID&embedder=EMBEDDER_NAME'Response: 200 OK
{
"hits": [
{
"id": "299537",
"title": "Captain Marvel"
},
{
"id": "166428",
"title": "How to Train Your Dragon: The Hidden World"
}
{
"id": "287947",
"title": "Shazam!"
}
],
"id": "23",
"processingTimeMs": 0,
"limit": 20,
"offset": 0,
"estimatedTotalHits": 3
}