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

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Body

    ParameterTypeDefault valueDescription
    idString or numbernullIdentifier of the target document (mandatory)
    embedderString"default"Embedder to use when computing recommendations
    attributesToRetrieveArray of strings["*"]Attributes to display in the returned documents
    offsetInteger0Number of documents to skip
    limitInteger20Maximum number of documents returned
    filterStringnullFilter queries by an attribute's value
    showRankingScoreBooleanfalseDisplay the global ranking score of a document
    showRankingScoreDetailsBooleanfalseDisplay detailed ranking score information
    rankingScoreThresholdNumbernullExclude results with low ranking scores
    retrieveVectorsBooleanfalseReturn 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
      }'

    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

    NameTypeDescription
    index_uid *Stringuid of the requested index

    Query parameters

    ParameterTypeDefault valueDescription
    idString or numbernullIdentifier of the target document (mandatory)
    embedderString"default"Embedder to use when computing recommendations
    attributesToRetrieveArray of strings["*"]Attributes to display in the returned documents
    offsetInteger0Number of documents to skip
    limitInteger20Maximum number of documents returned
    filterStringnullFilter queries by an attribute's value
    showRankingScoreBooleanfalseDisplay the global ranking score of a document
    showRankingScoreDetailsBooleanfalseDisplay detailed ranking score information
    rankingScoreThresholdNumbernullExclude results with low ranking scores
    retrieveVectorsBooleanfalseReturn document vector data

    Example

    curl \
      -X GET 'http://localhost:7700/indexes/INDEX_NAME/similar?id=TARGET_DOCUMENT_ID'

    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
    }