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

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

=== "Marqo Cloud" 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 Source"

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
      }
    }
  ]
}'

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

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

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

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

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

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

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

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

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

Get Suggestions​

Path parameters​

Body​

Response​

Example​

Index Queries​

Path parameters​

Body​

Response​

Example​

Get Queries​

Path parameters​

Body​

Response​

Example​

Get Statistics​

Path parameters​

Response​

Example​

Delete Specific Queries​

Path parameters​

Body​

Response​

Example​

Delete All Queries​

Path parameters​

Response​

Example​

How Typeahead Works​

1. Retrieval Stage​

2. Ranking Stage​

Key Features​

Best Practices​

Get Suggestions

Path parameters

Body

Response

Example

Index Queries

Path parameters

Body

Response

Example

Get Queries

Path parameters

Body

Response

Example

Get Statistics

Path parameters

Response

Example

Delete Specific Queries

Path parameters

Body

Response

Example

Delete All Queries

Path parameters

Response

Example

How Typeahead Works

1. Retrieval Stage

2. Ranking Stage

Key Features

Best Practices