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
`excludeInputDocuments`	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
`showHighlights`	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

Marqo Open SourceMarqo Cloud

cURLPython

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.

cURLPython

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.

Recommend

Path parameters

Body

Response

Example

Response: 200 Ok

Documents

Tensor fields

Limit

Offset

Filter

Example

Searchable attributes

Example

Interpolation method

SLERP

LERP

NLERP

Reranker

Example

Score modifiers

Response: `200 Ok`