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
excludeInputDocuments
 Boolean true If true, input documents will never be returned in the results.
limit Integer 3 Maximum number of document chunks 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 normalize_embeddings=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"]
)

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': None
}

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.

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
}

Limit

Parameter: limit

Expected value: Any positive integer

Default value: 20

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: ["*"]

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

If no value is specified, searchableAttributes will be set to the wildcard and search all fields.

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"]

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.