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

常见问题

Q: Typesense 和 Meilisearch 怎么选？ A: 两者非常相似，都提供 Algolia-like 的开发体验。Typesense 的优势：原生集群/HA 支持、更稳定的 GA 状态、C++ 性能稍优。Meilisearch 的优势：MIT 许可更宽松、API 更友好、内置 UI 更美观。对大多数项目两者都是好选择。

Q: 集群模式怎么工作？ A: Typesense 使用 Raft 共识算法实现 3 节点集群。写入到 leader，自动同步到 followers。任一节点都可以处理读请求。单节点故障自动切换。

Q: 适合电商搜索吗？ A: 非常适合。电商常见需求（分面搜索、价格筛选、排序、typo 容忍、个性化）都是 Typesense 的核心功能。Algolia 的大多数电商案例都可以用 Typesense 复制。

来源与致谢

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