Typeahead

Get intelligent query suggestions based on partial user input to help users find relevant content faster and reduce zero-result searches.

Get Suggestions

Get typeahead suggestions for partial user input.

POST /indexes/{index_name}/suggestions

Path parameters

Name	Type	Description
`index_name`	String	name of the requested index

Body

Parameter	Type	Default	Description
`q`	String	`null`	Partial user search input to get suggestions for. Empty strings return top results ordered by popularity
`limit`	Integer	`10`	Maximum number of suggestions to return
`fuzzyEditDistance`	Integer	`2`	Maximum edit distance for fuzzy matching
`minFuzzyMatchLength`	Integer	`3`	Minimum character length before fuzzy matching is applied
`popularityWeight`	Float	`null`	Weight for popularity scoring (0.0-1.0)
`bm25Weight`	Float	`null`	Weight for BM25 relevance scoring (0.0-1.0)

Response

{
  "suggestions": [
    {
      "suggestion": "iphone 15 case",
      "score": 0.95,
      "metadata": {
        "hitCount": 150
      }
    },
    {
      "suggestion": "iphone charger",
      "score": 0.89,
      "metadata": {
        "hitCount": 89
      }
    }
  ]
}

Example

Marqo Open SourceMarqo Cloud

curl -XPOST 'http://localhost:8882/indexes/my-index/suggestions' \
  -H 'Content-type:application/json' -d '
{
  "q": "iph",
  "limit": 5,
  "fuzzyEditDistance": 1,
  "popularityWeight": 0.3,
  "bm25Weight": 0.7
}'

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-index/suggestions' \
-H 'x-api-key: XXXXXXXXXXXXX' \
-H 'Content-type:application/json' -d '
{
  "q": "iph",
  "limit": 5,
  "fuzzyEditDistance": 1,
  "popularityWeight": 0.3,
  "bm25Weight": 0.7
}'

Index Queries

Add queries to the typeahead suggestion corpus. These queries will be used to generate suggestions when users type partial input. This endpoint can also be used to update existing queries by re-indexing them with the same query text but updated metadata or popularity scores.

Query strings are normalized during indexing, so "Nike" and "nike" result in the same query term.

POST /indexes/{index_name}/suggestions/queries

Path parameters

Name	Type	Description
`index_name`	String	name of the requested index

Body

Parameter	Type	Description
`queries`	Array	Array of query objects to index for typeahead suggestions

Each query object can contain:

Field	Type	Description
`query`	String	The query text to index
`popularity`	Float	Popularity score used in ranking (defaults to 0.0)
`metadata`	Dict	Optional metadata with string keys and numeric values (e.g., `{"hitCount": 150}`)

Response

{
  "indexed": 3,
  "errors": [],
  "processing_time_ms": 12.5
}

Example

Marqo Open SourceMarqo Cloud

curl -XPOST 'http://localhost:8882/indexes/my-index/suggestions/queries' \
  -H 'Content-type:application/json' -d '
{
  "queries": [
    {
      "query": "iphone 15 case",
      "popularity": 150.0,
      "metadata": {
        "hitCount": 150
      }
    },
    {
      "query": "samsung galaxy charger",
      "popularity": 89.0,
      "metadata": {
        "hitCount": 89
      }
    },
    {
      "query": "wireless headphones",
      "popularity": 245.0,
      "metadata": {
        "hitCount": 245
      }
    }
  ]
}'

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-index/suggestions/queries' \
-H 'x-api-key: XXXXXXXXXXXXX' \
-H 'Content-type:application/json' -d '
{
  "queries": [
    {
      "query": "iphone 15 case",
      "popularity": 150.0,
      "metadata": {
        "hitCount": 150
      }
    },
    {
      "query": "samsung galaxy charger",
      "popularity": 89.0,
      "metadata": {
        "hitCount": 89
      }
    },
    {
      "query": "wireless headphones",
      "popularity": 245.0,
      "metadata": {
        "hitCount": 245
      }
    }
  ]
}'

Get Queries

Retrieve indexed queries that are available for typeahead suggestions.

GET /indexes/{index_name}/suggestions/queries

Path parameters

Name	Type	Description
`index_name`	String	name of the requested index

Body

Parameter	Type	Description
`queries`	Array	Array of query strings to retrieve

Response

{
  "queries": [
    {
      "query": "iphone 15 case",
      "query_words": ["iphone", "15", "case"],
      "popularity": 150.0,
      "metadata": {
        "hitCount": 150
      },
      "last_updated_at": 1642502400
    },
    {
      "query": "samsung galaxy charger",
      "query_words": ["samsung", "galaxy", "charger"],
      "popularity": 89.0,
      "metadata": {
        "hitCount": 89
      },
      "last_updated_at": 1642415200
    }
  ]
}

Example

Marqo Open SourceMarqo Cloud

curl -XGET 'http://localhost:8882/indexes/my-index/suggestions/queries' \
  -H 'Content-type:application/json' -d '
{
  "queries": ["iphone 15 case", "samsung galaxy charger"]
}'

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 -XGET 'your_endpoint/indexes/my-index/suggestions/queries' \
-H 'x-api-key: XXXXXXXXXXXXX' \
-H 'Content-type:application/json' -d '
{
  "queries": ["iphone 15 case", "samsung galaxy charger"]
}'

Get Statistics

Get statistics about the typeahead feature usage and performance for an index.

GET /indexes/{index_name}/suggestions/stats

Path parameters

Name	Type	Description
`index_name`	String	name of the requested index

Response

{
  "indexed_queries": 1250
}

Example

Marqo Open SourceMarqo Cloud

curl -XGET 'http://localhost:8882/indexes/my-index/suggestions/stats'

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 -XGET 'your_endpoint/indexes/my-index/suggestions/stats' \
-H 'x-api-key: XXXXXXXXXXXXX'

Delete Specific Queries

Delete specific queries from the typeahead suggestion corpus.

DELETE /indexes/{index_name}/suggestions/queries

Path parameters

Name	Type	Description
`index_name`	String	name of the requested index

Body

Parameter	Type	Description
`queries`	Array	Array of query strings to delete

Response

"Queries deleted successfully"

Example

Marqo Open SourceMarqo Cloud

curl -XDELETE 'http://localhost:8882/indexes/my-index/suggestions/queries' \
  -H 'Content-type:application/json' -d '
{
  "queries": ["old query", "outdated search term"]
}'

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 -XDELETE 'your_endpoint/indexes/my-index/suggestions/queries' \
-H 'x-api-key: XXXXXXXXXXXXX' \
-H 'Content-type:application/json' -d '
{
  "queries": ["old query", "outdated search term"]
}'

Delete All Queries

Delete all queries from the typeahead suggestion corpus for an index.

DELETE /indexes/{index_name}/suggestions/queries/delete-all

Path parameters

Name	Type	Description
`index_name`	String	name of the requested index

Response

"All queries deleted successfully"

Example

Marqo Open SourceMarqo Cloud

curl -XDELETE 'http://localhost:8882/indexes/my-index/suggestions/queries/delete-all'

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 -XDELETE 'your_endpoint/indexes/my-index/suggestions/queries/delete-all' \
-H 'x-api-key: XXXXXXXXXXXXX'

How Typeahead Works

Marqo's typeahead feature uses a two-stage process to provide intelligent query suggestions:

1. Retrieval Stage

Prefix Matching: Matches indexed queries where at least one word starts with the user's input
Text Normalization: Removes accents and converts to lowercase for better matching
Fuzzy Matching: Allows for typos and minor variations using configurable edit distance

2. Ranking Stage

BM25 Scoring: Relevance score based on how well the input matches the query text
Popularity Weighting: Boosts suggestions based on query popularity/usage frequency
Combined Scoring: Balances BM25 relevance and popularity using configurable weights

Key Features

Configurable Fuzzy Matching: Adjust tolerance for typos and variations
Metadata Support: Store query hit counts for popularity-based ranking
Real-time Suggestions: Low-latency responses for interactive search experiences
Popularity-based Ranking: Surface frequently searched queries first
Text Normalization: Handles accents, case variations automatically

Best Practices

Index popular search queries from your search logs
Update popularity scores regularly based on actual usage
Use appropriate fuzzy matching settings for your use case
Balance BM25 and popularity weights based on your requirements
Consider query length when setting minFuzzyMatchLength