Skip to content

Recommend

Input a list of existing document IDs or dict of IDs and weights, and the response will be a list of "recommendations", which are documents similar to the input. These similar documents are retrieved by searching using interpolated vectors from the input. No inference is done during this process.


POST /indexes/{index_name}/recommend

Path parameters

Name Type Description
index_name String name of the requested index

Body

The body parameters below would be used for HTTP requests (if you were using cURL, for example). Python client users should use the pythonic snakecase equivalents (for example, searchable_attributes rather than searchableAttributes).

Search Parameter Type Default value Description
documents Array of strings or Dict null Document IDs to get recommendations for. This is either a list of IDs or a dictionary of ID to weight pairs.
tensorFields
Array of Strings [] Tensor fields within the documents to use to generate recommendations
Boolean true If true, input documents will never be returned in the results.
limit Integer 10 Maximum number of documents to be returned
offset Integer 0 Number of documents to skip (used for pagination)
filter String null Filter string in the Marqo DSL Language. In the Python client this parameter is called filter_string: mq.recommend(["doc1", "doc2"], filter_string="country:(United States)")
searchableAttributes Array of strings null Attributes to be queried during the search. Only supported in structured indexes
Boolean true Return highlights for the document match.
interpolationMethod String null The interpolation method to use for combining document embeddings. Defaults to slerp if normalizeEmbeddings=True for the index, and lerp otherwise.
attributesToRetrieve Array of strings null Attributes to return in the response
efSearch Integer 2000 The size of the dynamic list for the nearest neighbors (used during the search) - higher gives better recall at the cost of latency. Also efSearch must be greater than limit and limit is capped at 400
approximate Boolean True Toggles between exact KNN and approximate KNN (with HNSW)
reRanker String null Method to use for reranking results
scoreModifiers Dict null A dictionary to modify the score based on field values. Check here for examples.

Response

Name Type Description
hits Array of objects Results of the query
limit Integer Number of documents chunks specified in the query
offset Integer Number of skipped results specified in the query
processingTimeMs Number Processing time of the query
query String Query originating the response

Example

cURL -XPOST 'http://localhost:8882/indexes/my-first-index/recommend' -H 'Content-type:application/json' -d '
{
    "documents": ["doc1", "doc5"],
    "limit": 10,
    "offset": 0,
    "showHighlights": true,
    "attributesToRetrieve": ["Title", "Description"]
}'
mq.index("my-first-index").recommend(
    documents=["doc1", "doc5"],
    limit=10,
    offset=0,
    show_highlights=True,
    attributes_to_retrieve=["Title", "Description"]
)

For Marqo Cloud, you will need to access the endpoint of your index and replace your_endpoint with this. To do this, visit Find Your Endpoint. You will also need your API Key. To obtain this key visit Find Your API Key.

cURL -XPOST 'your_endpoint/indexes/my-first-index/recommend' \
-H 'x-api-key: XXXXXXXXXXXXXXX' \
-H 'Content-type:application/json' -d '
{
    "documents": ["doc1", "doc5"],
    "limit": 10,
    "offset": 0,
    "showHighlights": true,
    "attributesToRetrieve": ["Title", "Description"]
}'
mq.index("my-first-index").recommend(
    documents=["doc1", "doc5"],
    limit=10,
    offset=0,
    show_highlights=True,
    attributes_to_retrieve=["Title", "Description"]
)

Response: 200 Ok

{
    "hits": [
        {
            "Description": "A small breed of dog.",
            "Title": "Chihuahuas",
            "_highlights": [{"Description": "A small breed of dog."}],
            "_id": "doc4",
            "_score": 0.8582207950725244
        },
        {
            "Description": "A certain breed of dog.",
            "Title": "Huskies",
            "_highlights": [{"Description": "A certain breed of dog."}],
            "_id": "doc3",
            "_score": 0.8579511935990104
        },
        {
            "Description": "Our favorite feline friends.",
            "Title": "Cats",
            "_highlights": [{"Title": "Cats"}],
            "_id": "doc2",
            "_score": 0.8182416336023639
        }
    ],
    "limit": 10,
    "offset": 0,
    "processingTimeMs": 48,
    "query": null
}

Documents

Parameter: documents

Expected value: List of document IDs, a dictionary of weighted document IDs.

These are the document IDs that you want to get recommendations for. Their embeddings will be interpolated and used to search for similar documents in the index.

If document IDs are weighted, each weight acts as a (possibly negative) multiplier for that document's embeddings, relative to the other documents.

When providing weights, there must be at least one document with a non-zero weight. Document weights may have to meet other criteria, depending on the interpolation method used. See the Interpolation method section for more details.

Default value: null

Examples

# document list
documents = ["doc1", "doc2"]

# a dictionary of weighted documents
documents = {
    # a weighting of 1 gives this query a neutral effect:
    "doc1": 1.0,
    # we give this a weighting of 2 because we really want results similar to this:
    "doc2": 2.0,
    # we give this a negative weighting to make it less likely to appear: 
    "doc3": -1
}

Tensor fields

Parameter: tensorFields

Expected value: An array of strings

Default value: null

Configures which tensor fields will be used to generate recommendations.

If no value is specified, all tensor fields will be used.

Limit

Parameter: limit

Expected value: Any positive integer

Default value: 10

Max: 1000

Sets the maximum number of documents returned by a single query.

Offset

Parameter: offset

Expected value: Any integer greater than or equal to 0

Default value: 0

Max: 10000

Sets the number of documents to skip. For example, if offset = 20, The first result returned will be the 21st result. Only set this parameter for single-field searches (multi-field support to follow).

Filter

Parameter: filter

Expected value: A filter string written in Marqo's query DSL.

Default value: null

Uses filter expressions to refine search results.

Read our guide on filtering, faceted search and filter expressions.

Example

You can write a filter expression in string syntax using logical connectives (see filtering in Marqo):

"(type:confectionary AND food:(ice cream)) OR animal:hippo"

Searchable attributes

Parameter: searchableAttributes

Expected value: An array strings

Default value: null

Configures which attributes will be searched for query matches. This field is only supported in structured indexes.

If no value is specified, all fields will be searched.

Example

You can write the searchableAttributes as a list of strings, for example if you only wanted to search the "Description" field of your documents:

["Description"]

Interpolation method

Parameter: interpolationMethod

Expected value: One of "slerp", "lerp" or nlerp

Default value: null

Sets the method used to interpolate the document embeddings.

If no value is specified, the interpolation method will be set to slerp if normalizeEmbeddings=True for the index, and lerp otherwise.

SLERP

SLERP (Spherical Linear Interpolation) is a method of interpolating between two vectors on a hypersphere. It is suitable for interpolating between embeddings that are normalized. SLERP cannot interpolate between embeddings where the sum of the weights is equal to zero. Consequently, it is best to avoid consecutive pairs of weights that add up to zero in your input document weights, as such pairs can result in a 400 error.

LERP

LERP (Linear Interpolation) is a method of interpolating between two vectors in a linear fashion. LERP cannot interpolate between embeddings where the sum of all weights is equal to zero. A zero weight sum will result in a 400 error.

NLERP

NLERP (Normalized Linear Interpolation) is similar to LERP, but the interpolated vector is normalized. It can be used as an alternative to SLERP where normalizeEmbeddings=True for the index. As with LERP, a zero weight sum will result in a 400 error.

Reranker

Parameter: reRanker

Expected value: One of "owl/ViT-B/32", "owl/ViT-B/16", "owl/ViT-L/14"

Default value: null

Selects the method for reranking results. See the Models reference reranking section for more details.

If no value is specified, reRanker will be set to null and no reranking will occur.

Example

You can write reRanker as a string, for example:

"owl/ViT-B/32"

Score modifiers

Parameter: score_modifiers

Expected value: An object with two optional keys: multiply_score_by and add_to_score. The value of each of these keys is an array of objects that each contain the name of a numeric field in the document as the field_name key and the weighting that should be applied to the numeric value, as the weight key, if it is found in the doc.

Default value: null

Score modifiers allows you to modify the initial score of the document by multiplying, and adding to, the initial search with values found within the document itself. This allows you to modify the search results based on metadata not included in the vectors

The default weight value is 1 in the multiply_score_by object and 0 in the add_to_score object. The multiply_score_by modifiers will be applied to the document's score before the add_to_score modifiers. If a field specified in the score modification objects isn't found in the document, then the score modification will be skipped for that document's field.