Search

POST /indexes/{index_name}/search

Search for documents matching a specific query in the given index.

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
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.

Response

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

Example

cURLPython

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,
    "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,
    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,
  "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.

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"