Get similar documents with POST

Retrieve documents similar to a reference document identified by its id.

Useful for “more like this” or recommendations.

POST /indexes/{index_uid}/similar

cURL

cURL

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' })

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

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

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();

200

{
  "hits": [
    {
      "id": 2770,
      "title": "American Pie 2",
      "poster": "https://image.tmdb.org/t/p/w1280/q4LNgUnRfltxzp3gf1MAGiK5LhV.jpg",
      "overview": "The whole gang are back and as close as ever. They decide to get even closer by spending the summer together at a beach house. They decide to hold the biggest…",
      "release_date": 997405200
    },
    {
      "id": 190859,
      "title": "American Sniper",
      "poster": "https://image.tmdb.org/t/p/w1280/svPHnYE7N5NAGO49dBmRhq0vDQ3.jpg",
      "overview": "U.S. Navy SEAL Chris Kyle takes his sole mission—protect his comrades—to heart and becomes one of the most lethal snipers in American history. His pinpoint accuracy not only saves countless lives but also makes him a prime…",
      "release_date": 1418256000
    }
  ],
  "id": "143",
  "offset": 0,
  "limit": 2,
  "estimatedTotalHits": 976,
  "processingTimeMs": 35
}

{
  "message": "The Authorization header is missing. It must use the bearer authorization method.",
  "code": "missing_authorization_header",
  "type": "auth",
  "link": "https://docs.meilisearch.com/errors#missing_authorization_header"
}

{
  "message": "Index `movies` not found.",
  "code": "index_not_found",
  "type": "invalid_request",
  "link": "https://docs.meilisearch.com/errors#index_not_found"
}

Authorizations

Authorization · string · header · required

An API key is a token that you provide when making API calls. Read more about how to secure your project.

Include the API key to the Authorization header, for instance:

-H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1'

If you use a SDK, ensure you instantiate the client with the API key, for instance with JS SDK:

const client = new MeiliSearch({
  host: 'MEILISEARCH_URL',
  apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1'
});

Path Parameters

index_uid · string · required

Unique identifier of the index.

Body

application/json

Request body for similar document search

id · string · required

Document ID to find similar documents for

embedder · string · required

Name of the embedder to use for semantic similarity

offset · integer · default: 0

Number of documents to skip

Required range: x >= 0

limit · integer · default: 20

Maximum number of documents returned

Required range: x >= 0

filter · any

Filter queries by an attribute's value

attributesToRetrieve · string[] | null

Attributes to display in the returned documents

retrieveVectors · boolean

Return document vector data

showRankingScore · boolean

Display the global ranking score of a document

showRankingScoreDetails · boolean

Adds a detailed global ranking score field

showPerformanceDetails · boolean

Adds a detailed performance details field

rankingScoreThreshold · number<double>

Excludes results with low ranking scores

Response

200

application/json

The documents are returned.

Option 1

Option 2

Response containing similar documents

hitsPerPage · integer · required

Number of results per page.

Required range: x >= 0

page · integer · required

Current page index (1-based).

Required range: x >= 0

totalPages · integer · required

Exhaustive total number of result pages.

Required range: x >= 0

totalHits · integer · required

Exhaustive total number of matching documents.

Required range: x >= 0

hits · object[] · required

Results of the query

Show child attributes

id · string · required

Document ID that was used as reference

processingTimeMs · integer · required

Processing time of the query in milliseconds

Required range: x >= 0

performanceDetails · any

Performance details of the query