Typesense — Fast Typo-Tolerant Search Engine

What Typesense Does

• Instant Search: Sub-50ms latency on large collections via in-memory indexing
• Typo Tolerance: Automatic typo correction with configurable fuzziness
• Faceted Filtering: Filter by categories, prices, dates, and custom fields
• Geo Search: Location-based search with distance sorting
• Vector Search: AI embedding search for semantic similarity
• Synonyms: Define synonym mappings for better results
• Curation: Pin specific results to the top for sponsored/featured items
• Multi-Search: Execute multiple searches in a single API call
• Highlighting: Highlight matched terms in results
• Cluster: High availability clustering with automatic failover

Architecture

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Search UI   │────▶│  Typesense   │────▶│  In-Memory   │
│  (InstantJS) │     │  Cluster     │     │  Index + SSD │
└──────────────┘     │  (C++)       │     │  Persistence │
                     └──────────────┘     └──────────────┘

Typesense keeps the entire search index in RAM for maximum speed, with persistent storage on SSD.

Self-Hosting

Docker Compose

services:
  typesense:
    image: typesense/typesense:latest
    ports:
      - "8108:8108"
    volumes:
      - typesense-data:/data
    command:
      - --data-dir=/data
      - --api-key=your-api-key
      - --enable-cors
    restart: unless-stopped

volumes:
  typesense-data:

Cluster (HA Setup)

services:
  typesense-1:
    image: typesense/typesense:latest
    command: --data-dir=/data --api-key=xyz --nodes=/etc/typesense/nodes
    volumes:
      - node1-data:/data
      - ./nodes:/etc/typesense/nodes

  typesense-2:
    image: typesense/typesense:latest
    command: --data-dir=/data --api-key=xyz --nodes=/etc/typesense/nodes

  typesense-3:
    image: typesense/typesense:latest
    command: --data-dir=/data --api-key=xyz --nodes=/etc/typesense/nodes

Basic Usage

Create Collection

curl -X POST 'http://localhost:8108/collections' 
  -H "X-TYPESENSE-API-KEY: your-api-key" 
  -H "Content-Type: application/json" 
  -d '{
    "name": "products",
    "fields": [
      {"name": "title", "type": "string"},
      {"name": "description", "type": "string"},
      {"name": "price", "type": "float"},
      {"name": "category", "type": "string", "facet": true},
      {"name": "brand", "type": "string", "facet": true}
    ],
    "default_sorting_field": "price"
  }'

Index Documents

curl -X POST 'http://localhost:8108/collections/products/documents' 
  -H "X-TYPESENSE-API-KEY: your-api-key" 
  -H "Content-Type: application/json" 
  -d '{
    "id": "1",
    "title": "Wireless Headphones",
    "description": "Noise-cancelling bluetooth headphones",
    "price": 199.99,
    "category": "Electronics",
    "brand": "Sony"
  }'

Search

# Basic search
curl "http://localhost:8108/collections/products/documents/search?q=headphones&query_by=title,description" 
  -H "X-TYPESENSE-API-KEY: your-api-key"

# Advanced search
curl "http://localhost:8108/collections/products/documents/search?q=bluetooth&query_by=title,description&filter_by=price:<500 && category:Electronics&sort_by=price:asc&facet_by=brand" 
  -H "X-TYPESENSE-API-KEY: your-api-key"

SDK Examples

JavaScript

import Typesense from 'typesense';

const client = new Typesense.Client({
  nodes: [{ host: 'localhost', port: 8108, protocol: 'http' }],
  apiKey: 'your-api-key',
});

// Search
const results = await client.collections('products').documents().search({
  q: 'wireless headphones',
  query_by: 'title,description',
  filter_by: 'price:<300',
  facet_by: 'brand,category',
  per_page: 20,
});

Python

import typesense

client = typesense.Client({
    'nodes': [{'host': 'localhost', 'port': '8108', 'protocol': 'http'}],
    'api_key': 'your-api-key',
    'connection_timeout_seconds': 2
})

# Search
results = client.collections['products'].documents.search({
    'q': 'wireless headphones',
    'query_by': 'title,description',
    'filter_by': 'price:<300',
    'per_page': 20
})

Key Features

Vector Search (AI Semantic Search)

{
  "name": "products",
  "fields": [
    {"name": "title", "type": "string"},
    {"name": "embedding", "type": "float[]", "num_dim": 768}
  ]
}

// Search by vector
POST /collections/products/documents/search
{
  "q": "*",
  "vector_query": "embedding:([0.1, 0.2, ...], k:10)"
}

Geo Search

# Find products within 5km of location
curl "http://localhost:8108/collections/stores/documents/search?q=*&filter_by=location:(40.7128, -74.0060, 5 km)"

Curation (Promoted Results)

{
  "id": "headphones-promo",
  "rule": {
    "query": "headphones",
    "match": "exact"
  },
  "includes": [
    {"id": "premium-headphones-1", "position": 1},
    {"id": "premium-headphones-2", "position": 2}
  ]
}

Typesense vs Alternatives

FAQ

Q: Typesense or Meilisearch — which should I choose? A: The two are very similar, both offering an Algolia-like developer experience. Typesense's strengths: native clustering/HA support, a more stable GA status, and slightly better C++ performance. Meilisearch's strengths: a more permissive MIT license, a friendlier API, and a nicer built-in UI. Either is a solid choice for most projects.

Q: How does cluster mode work? A: Typesense uses the Raft consensus algorithm for a 3-node cluster. Writes go to the leader and are automatically synced to followers. Any node can serve reads. Single-node failures trigger automatic failover.

Q: Is it suitable for e-commerce search? A: Very much so. Common e-commerce requirements — faceted search, price filtering, sorting, typo tolerance, personalization — are all core Typesense features. Most Algolia e-commerce use cases can be replicated with Typesense.

Sources & Credits

• GitHub: typesense/typesense — 25.6K+ ⭐ | GPL-3.0
• Website: typesense.org