Search

The search API supports full-text search with BM25F scoring, prefix matching, typo tolerance, highlighting, pagination, and many other options. All parameters follow the Typesense v30.1 API.

Basic Search

GET /collections/products/documents/search?q=running shoes&query_by=title,description
X-TYPESENSE-API-KEY: YOUR_API_KEY

Search Parameters

Parameter	Type	Description
`q`	string	Search query text. Use `*` to match all documents.
`query_by`	string	Comma-separated list of fields to search (required).
`query_by_weights`	string	Comma-separated weights for each `query_by` field (e.g., `3,1,1`).
`filter_by`	string	Filter expression. See Filtering.
`sort_by`	string	Sort specification. See Sorting.
`facet_by`	string	Comma-separated fields for facet counts. See Faceting.
`group_by`	string	Group results by field. See Grouping.
`group_limit`	int	Maximum results per group (default: 3).
`per_page`	int	Results per page (default: 10, max: 250).
`page`	int	Page number (default: 1).

Text Search Options

Parameter	Type	Default	Description
`text_match_type`	string	-	`all` requires all query tokens to match. `any` matches any token.
`prefix`	bool	`true`	Enable prefix matching on the last query token.
`infix`	string	`off`	Match inside words: `off`, `fallback` (only when a token has no match), or `always` - per `query_by` field. Works on any searchable field.
`max_extra_prefix` / `max_extra_suffix`	int	-	Limit how many extra characters an infix match may have before/after the query token.
`num_typos`	int	`2`	Maximum edit distance for typo correction (0, 1, or 2).
`typo_tokens_threshold`	int	-	Only attempt typo correction if fewer than this many results found.
`min_len_1typo`	int	`4`	Minimum token length before 1 typo is allowed.
`min_len_2typo`	int	`7`	Minimum token length before 2 typos are allowed.
`synonym_num_typos`	int	`0`	Allow typo-corrected tokens to resolve synonyms (max 2).
`drop_tokens_threshold`	int	`1`	Drop query tokens to widen results when fewer than this many hits are found.
`drop_tokens_mode`	string	-	Token drop order: `right_to_left`, `left_to_right`, or `both_sides:3`.
`split_join_tokens`	string	`fallback`	Try splitting/joining query tokens: `off`, `fallback`, `always`.
`prioritize_exact_match`	bool	`true`	Rank exact token matches above prefix/typo matches.
`exhaustive_search`	bool	`false`	Consider all candidate matches, disabling early cutoffs.
`search_cutoff_ms`	int	-	Best-effort scoring deadline in milliseconds.
`max_candidates`	int	`5`	Maximum prefix/typo expansions considered per query token.

Highlighting

Parameter	Type	Default	Description
`highlight_fields`	string	-	Comma-separated fields to highlight (defaults to `query_by` fields).
`highlight_start_tag`	string	`<mark>`	Opening tag for highlight matches.
`highlight_end_tag`	string	`</mark>`	Closing tag for highlight matches.
`highlight_affix_num_tokens`	int	`4`	Number of tokens to include around each highlight match.
`highlight_full_fields`	string	-	Fields for which the full highlighted `value` is returned. The windowed `snippet` is always emitted.
`snippet_threshold`	int	`30`	Fields shorter than this many tokens return their full text as the snippet; longer fields return a window around the match.

Advanced Options

Parameter	Type	Description
`vector_query`	string	Vector search query. See Vector Search.
`preset`	string	Preset ID to merge into the query. See Presets.
`stopwords`	string	Stopword set ID to apply. See Stopwords.
`synonym_sets`	string	Comma-separated synonym set IDs. See Synonyms.
`pinned_hits`	string	Document IDs to pin to the top of results (e.g., `id1:1,id2:2`).
`hidden_hits`	string	Document IDs to exclude from results (e.g., `id1,id2`).
`limit_hits`	int	-	Maximum number of hits to evaluate.
`facet_query`	string	-	Filter facet values by prefix (e.g., `category:Foot`).
`max_facet_values`	int	`10`	Maximum facet values to return per field.
`group_missing_values`	bool	`true`	Include documents with missing group_by field values.
`use_cache`	bool	`false`	Serve the result from the server-side cache when available.
`cache_ttl`	int	`60`	Cache lifetime in seconds for this query.
`enable_synonyms`	bool	`true`	Disable synonym expansion for this query when `false`.
`validate_field_names`	bool	`true`	When `false`, unknown fields in `query_by`/`filter_by` are ignored instead of returning an error.
`limit`	int	-	Alias for `per_page`.

Response Format

{
  "found": 2,
  "out_of": 1000,
  "page": 1,
  "search_time_ms": 1,
  "hits": [
    {
      "document": {
        "id": "1",
        "title": "Running Shoes",
        "price": 89.99
      },
      "highlights": [
        {
          "field": "title",
          "snippet": "<mark>Running</mark> <mark>Shoes</mark>",
          "matched_tokens": ["Running", "Shoes"]
        }
      ],
      "text_match": 578730123365711872
    }
  ],
  "facet_counts": [],
  "request_params": {"q": "running shoes", "query_by": "title"}
}

Multi-Search

Execute multiple search queries in a single request:

POST /multi_search
Content-Type: application/json
X-TYPESENSE-API-KEY: YOUR_API_KEY

{
  "searches": [
    {"collection": "products", "q": "shoes", "query_by": "title"},
    {"collection": "products", "q": "boots", "query_by": "title"}
  ]
}

The response contains an array of search results, one per query.

Union Mode

Pass "union": true to merge all searches into a single ranked result set instead of returning per-query results - useful for searching multiple collections as one:

{
  "union": true,
  "searches": [
    {"collection": "products", "q": "laptop", "query_by": "title"},
    {"collection": "accessories", "q": "laptop", "query_by": "title"}
  ]
}

Query-string parameters on POST /multi_search act as defaults for every search in the request; per-search values win.

Text Scoring

Torque uses BM25F scoring for text relevance. BM25F is a multi-field extension of BM25 that considers term frequency, inverse document frequency, document length, and per-field weights. The query_by_weights parameter controls how much each field contributes to the final score.

Prefix Search

When prefix is enabled (default), the last token in the query is treated as a prefix. This enables type-ahead suggestions as users type. Prefix matching uses an FST (Finite State Transducer) index for fast lookups.

Typo Tolerance

Torque uses SymSpell for typo correction. When a query token doesn’t match any indexed terms, Torque checks for corrections within the configured edit distance (num_typos, default 2). This handles common misspellings automatically. Short tokens are protected: 1 typo requires at least min_len_1typo (4) characters, 2 typos at least min_len_2typo (7).

Infix Search

Infix search matches query tokens inside indexed words - q=arch&infix=always matches "search" and "architecture". Set infix per query_by field to fallback (only used when a token has no regular match) or always. Unlike Typesense, Torque supports infix matching on any searchable field without a schema opt-in. max_extra_prefix and max_extra_suffix bound how many extra characters may surround the match.

Result Cache

Pass use_cache=true to cache the search result server-side for cache_ttl seconds (default 60). The cache is keyed on the exact query and the collection's index state - any document change invalidates naturally. Queries made with scoped API keys bypass the cache, and POST /operations/cache/clear empties it.

LLM-Powered Search

Torque can answer questions conversationally over your search results (conversation=true), translate natural-language questions into structured search parameters (nl_query=true), and embed query text server-side for semantic search. See AI & LLM Search.