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.