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

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.

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.

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.

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.