Search
POST /indexes/{index_name}/search
Path parameters
Name | Type | Description |
---|---|---|
index_name * |
String | name of the requested index |
Body
Search Parameter | Type | Default value | Description |
---|---|---|---|
q |
String | "" |
Query string |
limit |
Integer | 20 |
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 |
searchableAttributes |
Array of strings | ["*"] |
Attributes to display in the returned documents |
highlight |
Boolean | true |
Return highlights for the document match |
searchMethod |
String | "TENSOR" |
The search method, can be LEXICAL or TENSOR |
attributesToRetrieve |
String | ["*"] |
Attributes to return in the search response |
reRanker |
String | null |
Method to use for reranking results |
Query parameters
Search Parameter | Type | Default value | Description |
---|---|---|---|
device |
String | cpu |
The device used to search. This allows you to use cuda GPUs to speed up indexing, if available. Options include cpu and cuda , cuda1 , cuda2 etc. The cuda option tells Marqo to use all available cuda devices. |
Search Result Pagination
Use parameters limit
and offset
to paginate your results, meaning to query a certain number of results at a time instead of all at once.
The limit
parameter sets the size of a page. If you set limit
to 10
, Marqo's response will contain a maximum of 10 search results. The offset
parameter skips a number of search results. If you set offset
to 20
, Marqo's response will skip the first 20 search results.
Let's say you want each page to have 10 results, and you want to receive the 2nd page. Try setting limit
and offset
like so:
# Specify page properties
page_size = 10
page_num = 2
# Set limit and offset accordingly
limit = page_size
offset = (page_num - 1) * page_size
Pagination Limitations
Tensor Search Inconsistencies
Using pagination with search_method="TENSOR"
may result in some results being skipped or duplicated (often near the edge of pages) within the first few pages if the page size is much smaller than the total search result count. Please keep this in mind when looking for particular results or when result order is essential.
Single-field Pagination Only
Currently, pagination is only supported for searches in 1 field (when searchable_attributes
is set to a single field). Setting offset
for multi-field searches will result in an error.
Additionally, search results can only be 10,000 results deep. This means limit + offset
must be less than or equal to 10000
.
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/search' -H 'Content-type:application/json' -d '
{
"q": "what is the best outfit to wear on the moon?",
"searchableAttributes": ["Description"],
"limit": 10,
"offset": 0,
"showHighlights": true,
"filter": "*:*",
"searchMethod": "TENSOR",
"attributesToRetrieve": ["Title", "Description"]
}'
mq.index("my-first-index").search(
q="What is the best outfit to wear on the moon?",
searchable_attributes=["Description"],
limit=10,
offset=0,
show_highlights=True,
filter_string="*:*",
search_method=marqo.SearchMethods.LEXICAL,
attributes_to_retrieve=["Title", "Description"]
)
Response: 200 Ok
{
"hits": [
{
"Title": "Extravehicular Mobility Unit (EMU)",
"Description": "The EMU is a spacesuit that provides environmental protection, mobility, life support, and communications for astronauts",
"_highlights": {
"Description": "The EMU is a spacesuit that provides environmental protection, mobility, life support, and communications for astronauts"
},
"_id": "article_591",
"_score": 1.2387788
},
{
"Title": "The Travels of Marco Polo",
"Description": "A 13th-century travelogue describing Polo's travels",
"_highlights": {"Title": "The Travels of Marco Polo"},
"_id": "e00d1a8d-894c-41a1-8e3b-d8b2a8fce12a",
"_score": 1.2047464
}
],
"limit": 10,
"offset": 0,
"processingTimeMs": 49,
"query": "What is the best outfit to wear on the moon?"
}
Query (q)
Parameter: q
Expected value: Any string
Default value: null
Limit
Parameter: limit
Expected value: Any positive integer
Default value: 20
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
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. Attributes used as filter criteria must be added to the filterableAttributes
list.
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.
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"