typesense-docs

官方文件中的 Typesense

概述

本技能收錄 Typesense 官方文件裡容易搞錯的部分：哪些行為會消耗 RAM、隱藏失敗於 HTTP 200 背後的匯入結果、過濾器優先級、會放寬搜尋結果的預設值、範圍搜尋金鑰洩漏、混合搜尋權重，以及 v30 版本轉向 synonym sets 和 curation sets 的改變。一般的搜尋與資料庫建議則不在此列。每個主張都附有來源文件的 URL。

涵蓋版本

Typesense Server 30.2，程式碼範例使用 JavaScript 客戶端。伺服器旗標適用於自架伺服器，Typesense Cloud 則會管理這些旗標。在審閱為舊版伺服器撰寫的程式碼前，請先閱讀下方的「舊版模式」。

如何使用

1. 閱讀下方的快速入門。它涵蓋大多數任務中重要的規則。
2. 從結尾的表格中，開啟一個與任務領域相符的參考檔案。每個檔案都是獨立的。
3. 每個主張結尾都附有來源 URL。當某個細節會影響最終結果時，請重新開啟該 URL 進行確認。

快速入門

結構與記憶體

• 結構中的每個欄位都會載入 RAM 進行索引。僅用於顯示的欄位應排除在結構之外（仍會儲存並回傳），或設定 index: false。優先使用預先定義的結構，而非 .* 自動偵測。 https://typesense.org/docs/30.2/api/collections.html 和 https://typesense.org/docs/guide/running-in-production.html
• 無日期類型：以 int64 儲存 Unix 時間戳記。geopoint 的格式為 [lat, lng]，不是 GeoJSON 的順序。 https://typesense.org/docs/30.2/api/collections.html 和 https://typesense.org/docs/30.2/api/geosearch.html
• 使用 facet_by 和 group_by 需要設定 facet: true。字串排序需要設定 sort: true。 https://typesense.org/docs/30.2/api/search.html
• Alter 操作會封鎖對該集合的所有寫入。結構變更的預設做法是：建立一個新增版本號的集合、重新索引，然後將應用程式始終使用的別名指向新集合。 https://typesense.org/docs/30.2/api/collections.html
• 特殊字元會被移除，且比對僅限前綴：SKU、Email 和 URL 需要設定 token_separators。 https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html

寫入資料

• 預設：使用 action: 'upsert' 進行匯入（JSONL）。upsert 會取代整個文件，emplace 或 update 則接受部分更新。 https://typesense.org/docs/30.2/api/documents.html
• 匯入永遠回傳 HTTP 200。必須掃描每一行結果，檢查 success: false，並搭配 return_id=true。 https://typesense.org/docs/30.2/api/documents.html 和 https://typesense.org/docs/guide/faqs.html
• 設定自訂的字串 id。為匯入操作設定至少 5 分鐘的客戶端逾時（同步指南建議大型批次可高達 60 分鐘），且絕不要在寫入操作仍在運行時進行重試。 https://typesense.org/docs/30.2/api/documents.html 和 https://typesense.org/docs/guide/syncing-data-into-typesense.html
• 503 Not Ready or Lagging 表示寫入回壓：應批次寫入、增加 CPU、進行附帶抖動（jitter）的重試。 https://typesense.org/docs/guide/syncing-data-into-typesense.html

搜尋

• filter_by 需要冒號：price:>=100。使用 : 比對單詞，:= 比對整個值。&& 和 || 具有相同優先級，因此需加上括號。反引號可用於跳脫包含逗號或括號的值。 https://typesense.org/docs/guide/tips-for-filtering.html
• 在 object[] 中對相同物件的條件：ingredients.{name:=cheese && concentration:<50}。 https://typesense.org/docs/guide/tips-for-filtering.html
• drop_tokens_threshold 和 typo_tokens_threshold 預設為 1，因此點擊數少的查詢會默默地被丟棄詞彙或加入錯字。使用 drop_tokens_threshold: 0 可要求所有詞彙都必須匹配。使用 num_typos: 0 且 typo_tokens_threshold: 0 可關閉錯字容忍。 https://typesense.org/docs/guide/ranking-and-relevance.html
• max_candidates 預設為 4。短查詢可能會遺漏記錄，除非提高此值，或設定一個熱門度 default_sorting_field。 https://typesense.org/docs/30.2/api/search.html
• 混合相關性與熱門度：_text_match(buckets: 10):desc,popularity:desc。在不進行過濾的情況下提升特定值：_eval(in_stock:true):desc。 https://typesense.org/docs/guide/ranking-and-relevance.html
• 每頁最多 250 筆結果。group_by 會回傳 grouped_hits 和一個近似值 found。 https://typesense.org/docs/30.2/api/search.html
• 使用 union: true 的多重搜尋會忽略個別搜尋的分頁設定，且需要一致的排序欄位類型。 https://typesense.org/docs/30.2/api/federated-multi-search.html

向量與 AI 搜尋

• 向量查詢需透過 multi_search 進行，並務必在向量欄位上使用 exclude_fields。使用 k 或 distance_threshold 來限制結果範圍。 https://typesense.org/docs/30.2/api/vector-search.html
• 混合搜尋：query_by: 'title,embedding'。融合方式為 0.7 關鍵字權重與 0.3 向量權重，而 vector_query 中的 alpha 是向量權重。query_by_weights 需要為嵌入欄位設定一個佔位符 0。 https://typesense.org/docs/30.2/api/vector-search.html
• RAG：設定 conversation=true 並使用 exclude_fields: 'embedding'，否則原始浮點數會填充到 LLM 上下文中。 https://typesense.org/docs/30.2/api/conversational-search-rag.html

金鑰與多租戶

• 絕不在應用程式中使用 bootstrap 金鑰。絕不暴露管理金鑰，也不暴露範圍搜尋金鑰的父金鑰。 https://typesense.org/docs/guide/data-access-control.html
• 範圍搜尋金鑰：父金鑰僅需 documents:search 權限，在後端為每個使用者產生，並嵌入 filter_by 且必須設定 filter_curated_hits: true，否則固定（pinned）和精選（curated）的結果會在不同租戶間洩漏。 https://typesense.org/docs/30.2/api/api-keys.html 和 https://typesense.org/docs/30.2/api/curation.html
• 金鑰上的 collections 限制並不會限制全域端點（如 keys、synonym_sets、stopwords）。參考（reference）欄位會透過關聯暴露被參考的集合。 https://typesense.org/docs/30.2/api/api-keys.html

操作

• 生產環境：3 或 5 節點的高可用性（HA）架構，客戶端配置所有節點（在負載平衡器後方加上 nearestNode），RAM 占用低於 85%。 https://typesense.org/docs/guide/high-availability.html 和 https://typesense.org/docs/guide/running-in-production.html
• 使用 /operations/snapshot 進行備份，切勿直接複製運作中的資料目錄。先升級追隨者（follower），最後再升級領導者（leader）。 https://typesense.org/docs/guide/backups.html 和 https://typesense.org/docs/guide/updating-typesense.html

舊版模式

舊版	目前版本	來源
/collections/{c}/synonyms, synonyms:* 金鑰動作	/synonym_sets，搭配 synonym_sets:* 和 synonym_sets/items:*，透過集合 synonym_sets 連結	https://typesense.org/docs/30.2/api/synonyms.html
/collections/{c}/overrides, overrides:*	/curation_sets，搭配 curation_sets:* 和 curation_sets/items:*	https://typesense.org/docs/30.2/api/curation.html
override_tags	curation_tags	https://typesense.org/docs/30.2/api/curation.html
分析規則使用 params.source 和 params.destination	頂層 collection、event_type、扁平化 params	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
一個帶有加權 source.events 的計數器規則	每個事件類型一個規則，使用 params.weight	https://typesense.org/docs/30.2/api/analytics-query-suggestions.html
搭配 group_by 的精確 found	近似值，使用 group_max_candidates 提高準確度	https://typesense.org/docs/30.2/api/search.html
在應用程式中呼叫 LLM 來建構過濾器	nl_search_models + nl_query=true	https://typesense.org/docs/guide/natural-language-search.html
扁平化的巢狀物件	enable_nested_fields	https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html
使用 document_type 處理混合列表的單一集合	使用 union: true 的 multi_search	https://typesense.org/docs/guide/faqs.html
舊的 highlights 陣列	highlight 物件，設定 enable_highlight_v1=false	https://typesense.org/docs/30.2/api/search.html

金鑰無法更新：必須透過建立新金鑰來取代舊金鑰。自架伺服器在升級前應先建立快照，以便同義詞和覆寫規則能順利遷移。 https://typesense.org/docs/30.2/api/synonyms.html

參考檔案

檔案	用途
references/schema-and-collections.md	欄位參數與預設值、類型、RAM 成本、自動結構、巢狀物件、alter、別名、複製、集合佈局
references/tokenization-locale-stemming.md	token_separators、symbols_to_index、中綴、SKU、Email 和 URL 的處理方式、地區設定與變音符號、詞幹字典
references/documents-and-import.md	ID、匯入動作、讀取匯入結果、逾時、dirty_values、依查詢更新、刪除與匯出
references/syncing-and-reindexing.md	從資料庫同步的策略、高量寫入、503 與資源錯誤、透過別名重新索引
references/search-parameters.md	q、query_by、錯字容忍度、詞彙丟棄、前綴、max_candidates、高亮、分頁、快取、預設集
references/filtering-and-geo.md	filter_by 語法、優先級、跳脫、陣列、巢狀物件、空值、地理過濾與排序
references/ranking-and-sorting.md	預設排名、sort_by、text_match_type、區間（buckets）、_eval、衰減（decay）、遺漏值、固定結果
references/faceting-grouping-multi-search.md	Facet 與策略、group_by、聯邦與聯合多重搜尋、布林標籤搜尋
references/synonyms-curation-stopwords.md	同義詞集合、精選集合、標籤、動態規則、搭配範圍搜尋金鑰的精選機制、停用詞
references/vector-and-hybrid-search.md	向量欄位、自動嵌入模型、vector_query、混合搜尋融合與 alpha、HNSW、記憶體
references/conversational-nl-image-voice.md	RAG 對話模型、自然語言搜尋、圖片與語音查詢、推薦
references/api-keys-and-access-control.md	金鑰類型、動作、範圍陷阱、範圍搜尋金鑰、多租戶模式、金鑰輪替
references/clients-and-errors.md	客戶端函式庫、節點與負載平衡器配置、JS 調校、快取、錯誤碼、慢速搜尋
references/server-configuration.md	伺服器旗標與預設值、CORS、TLS、日誌、資源限制、分析功能旗標、安裝說明
references/cluster-ha-backups-upgrades.md	HA 叢集、節點檔案、復原、操作 API、監控、備份、升級、容量規劃、CI
references/analytics-and-query-suggestions.md	分析規則與事件、熱門與無結果查詢、計數器、日誌規則、查詢建議
references/joins-and-personalization.md	參考欄位、關聯包含、過濾與排序、左關聯與反關聯、非同步參考、個人化
references/ui-and-algolia-migration.md	InstantSearch 適配器、與 Algolia 的差異、概念對應、遷移步驟

原始來源與擷取細節列於 SOURCES.md。