API/behavior changes

New POST /indexes/:indexUid/similar route

POST /indexes/:indexUid/similar
{
  // mandatory: the external id of the target document 
  // that we're looking similar docs for.
  // Must be an integer or a string respecting the correct format: 
  // <https://www.meilisearch.com/docs/learn/core_concepts/primary_key#formatting-the-document-id>
  "id": "23",
  
  // optional, defaults to 0: how many results to skip
  "offset": 0,
  // optional, defaults to 20: how many results to display
  "limit": 2,
  
  // optional, defaults to null: an additional filter for the returned documents
  // The target document doesn't have to match the filter
  "filter": "release_date > 1521763199",
  
  // optional, defaults to the default embedder: name of the embedder to use
  // for computing recommendations.
  //
  // Note that recommendation will not actually perform any embedding operation,
  // the embedder name is only used to know in which vector DB we should look.
  "embedder": "default",
  
  // optional, defaults to null: same as the search query parameter of the same name
  "attributesToRetrieve": [],
  
  // optional, defaults to false: allow displaying the ranking score 
  // (resp. detailed ranking score)
  //
  // The ranking score (details) is computed as if there had been a single
  // "VectorSort" rule, with the target vector the vector of the target document
  // that is closest from each returned hit.
  "showRankingScore": false,
  "showRankingScoreDetails": false
  // optional, defaults to `null` (no threshold): if present,
  // limits the ranking score of results to be above the specified threshold
  // For details see:
  // <https://meilisearch.notion.site/Filter-by-score-usage-224a183ce7b24ca99b6a9a8da755668a>
  "rankingScoreThreshold": 0.0
}

New GET /indexes/:indexUid/similar route

GET /indexes/:indexUid/similar?id=23&offset=0&limit=20&filter="release_date>1521763199"&embedder=default&attributesToRetrieve=id,title,desc&showRankingScore=false&showRankingScoreDetails=false

Implementation status: ✅ Landed PR

Response format

Both endpoints result in a response with the following shape:

{
  // array of documents of up to `limit` length, 
  // identical to "hits" in the `search` endpoint.
  // In particular, contains `_rankingScore` and `_rankingScoreDetails`
  // if the corresponding options were enabled.
  // <https://www.meilisearch.com/docs/reference/api/search#response>
  "hits": [
    {
      "title": "Captain Marvel",
      "release_year": 
      "id": "299537",
      "_vectors": {
        "manual": [
          0.6,
          0.8,
          -0.2
        ]
      }
    },
    {
      "title": "How to Train Your Dragon: The Hidden World",
      "release_year": 2019,
      "id": "166428",
      "_vectors": {
        "manual": [
          0.7,
          0.7,
          -0.4
        ]
      }
    },
    {
      "title": "Shazam!",
      "release_year": 2019,
      "id": "287947",
      "_vectors": {
        "manual": [
          0.8,
          0.4,
          -0.5
        ]
      }
    }
  ],
  "id": "23", // `id` from the query, repeated as a string
  "processingTimeMs": 0, // Processing time of the query
  "limit": 20, // `limit` from the query
  "offset": 0, // `offset` from the query
  "estimatedTotalHits": 3 // estimated total number of matches
}

Telemetry

List all the new or updated telemetry

This feature adds two new telemetry events:

The properties of these events are the same as those for the search events, but those that are not currently relevant (e.g., sort.*) will always be missing. These events are aggregated similarly to the search events.

Error handling

New? Status code Error code Caused by Error message
NEW 400 invalid_similar_id id in request does not respect the format for document identifiers the provided id is invalid. A document identifier can be of type integer or string, only composed of alphanumeric characters (a-z A-Z 0-9), hyphens (-) and underscores (_).
NEW 400 not_found_similar_id the document associated with the provided id was not found in the index Document {id} not found.
NEW 400 invalid_similar_attributes_to_retrieve The attributesToRetrieve parameter is invalid. It should be an array of strings, a string, or set to null.
NEW 400 invalid_similar_filter This error occurs if: 
- The filter parameter is invalid
    - It should be a string, array of strings, or array of array of strings for the POST endpoint
    - It should be a string for the GET endpoint
- The attribute used for filtering is not defined in the filterableAttributes list
- The filter expression has a missing or invalid operator. Read more about our supported operators

| | NEW | 400 | invalid_similar_limit | | The limit parameter is invalid. It should be an integer. | | NEW | 400 | invalid_similar_offset | | The offset parameter is invalid. It should be an integer. | | NEW | 400 | invalid_similar_show_ranking_score | | The ranking_score parameter is invalid. It should be a boolean. | | NEW | 400 | invalid_similar_show_ranking_score_details | | The ranking_score_details parameter is invalid. It should be a boolean. | | Reused | 400 | invalid_embedder | | The embedder parameter is invalid. It should be a string corresponding to the name of a configured embedder. | | Reused | 400 | vector_embedding_error | | Error while generating embeddings: {explanation} |