# Typesense — Fast Typo-Tolerant Search Engine

> Typesense is an open-source, typo-tolerant search engine optimized for instant sub-50ms searches. Developer-friendly alternative to Algolia and ElasticSearch.

## Install

Save in your project root:

## Quick Use

```bash
docker run -d --name typesense 
  -p 8108:8108 
  -v typesense-data:/data 
  typesense/typesense:latest 
  --data-dir /data 
  --api-key=your-api-key 
  --enable-cors
```

Then start creating collections and searching via API.

## Intro

**Typesense** is an open-source, lightning-fast search engine built with C++ for instant sub-50ms searches. It provides typo tolerance out of the box, faceted filtering, geo search, vector/semantic search, and a beautiful JavaScript InstantSearch adapter — all through a simple REST API.

With 25.6K+ GitHub stars and GPL-3.0 license, Typesense has become a popular alternative to Algolia and ElasticSearch, particularly for developers who want Algolia-like features without the cost or ElasticSearch-like power without the complexity.

## 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

```yaml
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)

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

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

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

```bash
# 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

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

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

```json
{
  "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

```bash
# 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)

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

## Typesense vs Alternatives

| Feature | Typesense | Meilisearch | Algolia | ElasticSearch |
|---------|-----------|-------------|---------|---------------|
| Open Source | Yes (GPL-3.0) | Yes (MIT) | No | Yes |
| Language | C++ | Rust | N/A | Java |
| Typo tolerance | Built-in | Built-in | Built-in | Plugin |
| Vector search | Yes | Yes | Yes | Yes |
| Cluster/HA | Built-in raft | Single node | Managed | Complex |
| Memory (1M docs) | ~1GB | ~1GB | N/A | ~4GB+ |
| Setup | Single binary | Single binary | SaaS | Cluster |
| Pricing | Free (self-host) | Free | $500+/mo | Free (self-host) |

## 常见问题

**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](https://github.com/typesense/typesense) — 25.6K+ ⭐ | GPL-3.0
- 官网: [typesense.org](https://typesense.org)

---
Source: https://tokrepo.com/en/workflows/92da8a8c-352f-11f1-9bc6-00163e2b0d79
Author: AI Open Source