# Tìm kiếm toàn văn FTS5

Synapse sử dụng FTS5 (Full-Text Search 5) cho tìm kiếm bộ nhớ nhanh, linh hoạt.
Trang này giải thích cách nó hoạt động và cách sử dụng hiệu quả.

## FTS5 là gì?

FTS5 là một phần mở rộng SQLite (cũng có sẵn trong PostgreSQL qua các phần mở
rộng) cung cấp khả năng tìm kiếm toàn văn. Nó:

- Đánh chỉ mục nội dung văn bản để tìm kiếm từ khóa nhanh
- Hỗ trợ toán tử boolean (AND, OR, NOT)
- Hỗ trợ khớp cụm từ với dấu ngoặc kép
- Hỗ trợ khớp tiền tố với `*`
- Xếp hạng kết quả theo mức độ liên quan

Synapse sử dụng FTS5 để đánh chỉ mục toàn bộ nội dung bộ nhớ, cho phép tìm
kiếm dưới mili giây trên hàng nghìn bộ nhớ.

## Cách Synapse sử dụng FTS5

Khi bạn `POST /memory`:

1. Nội dung bộ nhớ được lưu trong bảng `memories`
2. Nội dung cũng được chèn vào bảng ảo FTS5
3. FTS5 tự động tokenize và đánh chỉ mục nội dung

Khi bạn `GET /memory/search?q=...`:

1. Synapse phân tích truy vấn bằng cú pháp FTS5
2. Thực thi `MATCH` đối với chỉ mục FTS5
3. Lọc theo `mind_id` (cách ly tenant)
4. Trả về kết quả được xếp hạng

## Cú pháp truy vấn

### Tìm kiếm từ khóa đơn giản

```
?q=docker
```

Trả về bộ nhớ chứa "docker".

### Nhiều từ khóa (AND ngầm định)

```
?q=docker+swarm
?q=docker%20swarm
```

Trả về bộ nhớ chứa CẢ "docker" VÀ "swarm".

### Khớp cụm từ

```
?q="docker+swarm"
?q=%22docker%20swarm%22
```

Trả về bộ nhớ chứa cụm từ chính xác "docker swarm".

### Khớp tiền tố

```
?q=docker*
```

Trả về bộ nhớ chứa các từ bắt đầu bằng "docker" (ví dụ "dockers", "dockerfile",
"dockerize").

### Boolean OR

```
?q=docker+OR+kubernetes
```

Trả về bộ nhớ chứa "docker" HOẶC "kubernetes".

### Boolean NOT

```
?q=docker+-swarm
?q=docker+NOT+swarm
```

Trả về bộ nhớ chứa "docker" nhưng KHÔNG chứa "swarm".

### Nhóm

```
?q=(docker+OR+kubernetes)+-test
```

Trả về bộ nhớ chứa "docker" hoặc "kubernetes", nhưng không chứa "test".

## Ví dụ thực tế

### Tìm bộ nhớ về một dự án

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=synapse+deployment"
```

### Tìm cụm từ chính xác

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=%22docker+swarm%22"
```

### Loại trừ bộ nhớ kiểm thử

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=production+-test"
```

### Tìm theo công nghệ

```bash
curl -H "Authorization: Bearer YOUR_MIND_KEY" \
     "https://synapse.schaefer.zone/memory/search?q=(postgres+OR+sqlite)+-mysql"
```

## Xếp hạng

FTS5 xếp hạng kết quả theo mức độ liên quan bằng thuật toán BM25. Các yếu tố:

- Tần suất thuật ngữ (thuật ngữ xuất hiện bao nhiêu lần)
- Tần suất tài liệu nghịch đảo (thuật ngữ hiếm xếp cao hơn)
- Độ dài tài liệu (tài liệu ngắn hơn với thuật ngữ xếp cao hơn)
- Trọng số cột (tiêu đề > nội dung)

Kết quả được trả về theo thứ tự xếp hạng (liên quan nhất trước).

## Hiệu suất

| Thao tác | Độ trễ |
|-----------|---------|
| Tìm 100 bộ nhớ | < 5ms |
| Tìm 1.000 bộ nhớ | < 10ms |
| Tìm 10.000 bộ nhớ | < 25ms |
| Tìm 100.000 bộ nhớ | < 100ms |

FTS5 được tối ưu cao cho khối lượng công việc nặng về đọc.

## Giới hạn

### Stemming

FTS5 không làm stemming theo mặc định. "running" và "run" là các thuật ngữ
khác nhau.

**Giải pháp:** Sử dụng khớp tiền tố: `?q=run*`

### Dung sai lỗi chính tả

FTS5 không hỗ trợ khớp mờ. Lỗi chính tả sẽ trả về không kết quả.

**Giải pháp:** Sử dụng tìm kiếm ngữ nghĩa (`/memory/semantic-search`) cho khớp
khái niệm.

### Từ dừng

Các từ phổ biến (the, a, an, is) được đánh chỉ mục nhưng có thể không hữu ích
cho tìm kiếm. FTS5 xử lý điều này tự động.

## FTS5 so với Tìm kiếm ngữ nghĩa

| Khía cạnh | FTS5 | Tìm kiếm ngữ nghĩa |
|--------|------|-----------------|
| Tốc độ | Dưới mili giây | 50-100ms |
| Khớp | Từ khóa chính xác | Khái niệm |
| Dung sai lỗi chính tả | Không | Một số |
| Stemming | Không | Ngầm định |
| Yêu cầu embeddings | Không | Có |
| Tốt nhất cho | Thuật ngữ cụ thể | Khái niệm |

Sử dụng FTS5 khi bạn biết từ khóa. Sử dụng tìm kiếm ngữ nghĩa khi bạn muốn
"bộ nhớ về X" khi X được mô tả khác đi.

## Thực hành tốt nhất

> [!TIP]
> - **Sử dụng thuật ngữ cụ thể** — "docker swarm" tốt hơn "container orchestration"
> - **Trích dẫn cụm từ** — `"docker swarm"` đảm bảo khớp cụm từ
> - **Sử dụng tiền tố cho biến thể** — `deploy*` bắt được "deploy", "deployment", "deploying"
> - **Loại trừ nhiễu** — `-test` lọc bỏ bộ nhớ kiểm thử
> - **Kết hợp với tag** — `?q=docker&tag=production` thu hẹp kết quả

## Bước tiếp theo

- [Tìm kiếm ngữ nghĩa](/docs/concepts/semantic-search)
- [Memory API](/docs/api/memory)
- [Thực hành tốt nhất về bộ nhớ](/docs/guides/memory-best-practices)