Similar documents

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.

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	`null`	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 'MEILISEARCH_URL/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"
  }'

client.index('INDEX_NAME').searchSimilarDocuments({ id: 'TARGET_DOCUMENT_ID', embedder: 'default' })

client.index("INDEX_NAME").get_similar_documents({"id": "TARGET_DOCUMENT_ID", "embedder": "default"})

$similarQuery = new SimilarDocumentsQuery('TARGET_DOCUMENT_ID', 'default');
$client->index('INDEX_NAME')->searchSimilarDocuments($similarQuery);

SimilarDocumentRequest query = new SimilarDocumentRequest() .setId("143") .setEmbedder("manual"); client.index("movies").searchSimilarDocuments(query)

client.index('INDEX_NAME').search_similar_documents('TARGET_DOCUMENT_ID', embedder: 'default')

resp := new(meilisearch.SimilarDocumentResult)
client.Index("INDEX_NAME").SearchSimilarDocuments(&meilisearch.SimilarDocumentQuery{
  Id: "TARGET_DOCUMENT_ID",
  Embedder: "default",
}, resp)

let results = index
  .similar_search("TARGET_DOCUMENT_ID", "EMBEDDER_NAME")
  .execute()
  .await
  .unwrap();

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 'MEILISEARCH_URL/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
}

API reference

Errors

Get similar documents with `POST`

Path parameters

Body

Example

Response: `200 OK`

Get similar documents with `GET`

Path parameters

Query parameters

Example

Response: `200 OK`

​Get similar documents with POST

​Path parameters

​Body

​Example

​Response: 200 OK

​Get similar documents with GET

​Path parameters

​Query parameters

​Example

​Response: 200 OK

Get similar documents with `POST`

Path parameters

Body

Example

Response: `200 OK`

Get similar documents with `GET`

Path parameters

Query parameters

Example

Response: `200 OK`