# 搜尋 API

以 `GET /api/search` 查詢已載入的資料庫，並了解已 deprecated 的單一策略 route。

## Search

```http
GET /api/search?db=notes&q=什麼是RAG&limit=5
```

### Query parameter

| Parameter | 必要 | 預設 | 行為 |
|---|---|---|---|
| `db` | 是 | — | 選擇目前已載入的資料庫 |
| `q` | 是 | — | 所選 strategy 使用的完整 query text |
| `limit` | 否 | `10` | 每個 strategy 的 result-row limit；有效值為 1–100 |
| `target` | 否 | 兩者 | 使用 `keyword` 或 `semantic` 選擇單一 branch；不分大小寫 |

`limit` 缺少、非數字、非正數或大於 100 時，會 fallback 為 10。

### Combined response

未指定 `target` 時，KuraDB 會並行執行兩個 branch：

```json
{
  "keyword": [
    {
      "source": "/Users/example/.config/kuradb/notes/inbox/rag.md",
      "matches": [
        {
          "chunk": 1,
          "content": "RAG 結合檢索與生成。"
        }
      ]
    }
  ],
  "semantic": [
    {
      "source": "/Users/example/.config/kuradb/notes/inbox/rag.md",
      "matches": [
        {
          "chunk": 1,
          "content": "RAG 結合檢索與生成。"
        }
      ]
    }
  ]
}
```

未選擇的 branch 會直接省略，而不是回傳 `null`。已選 branch 若無 match，則回傳空 array。分組方式與每個 match 暴露的欄位見 [錯誤與契約](/zh/api-reference-errors#api-response-契約)。

### Keyword target

```http
GET /api/search?db=notes&q=向量快取&target=keyword
```

Query 會經過 gse tokenization、lowercase normalization 與 deduplication，再比對 SQLite active row。Ranking 依 matched-token count，再依 row ID。Query 未產生任何 token 時回傳空 array，而不是 error。完整 keyword 流程見 [搜尋與檢索](/zh/search-and-retrieval)。

### Semantic target

```http
GET /api/search?db=notes&q=向量快取&target=semantic
```

KuraDB 從 cache 或 OpenAI 取得 512 維 query embedding，搜尋記憶體 vector bucket，移除 cosine score 低於 0.3 的 hit，再從 SQLite hydrate active row。兩階段排序見 [語意搜尋](/zh/search-and-retrieval-semantic)。

## Compatibility route

下列 route 使用固定 target 呼叫相同 search handler：

```http
GET /api/keyword?db=notes&q=向量快取&limit=5
GET /api/semantic?db=notes&q=向量快取&limit=5
```

固定 target 會覆寫任何 `target` query parameter。為避免破壞 Agenvoy，它們目前仍可使用，但已標示將於 v1 移除。新 consumer 應使用 `/api/search`。