typesense-docs

Typesense 官方文档精要

概述

本技能提炼了 Typesense 文档中容易出错的部分：什么操作会消耗 RAM、导入结果会通过 HTTP 200 隐藏失败、筛选器优先级、会宽松匹配结果的默认设置、作用域搜索密钥泄漏、混合搜索权重，以及 v30 中向同义词集和筛选集的迁移。不包含通用的搜索和数据库建议。每项声明都附有来源的文档 URL。

涉及版本

Typesense Server 30.2，代码示例使用 JavaScript 客户端。服务器标志适用于自托管服务器。Typesense Cloud 会管理这些标志。在审查为旧版服务器编写的代码之前，请先阅读下面的“旧模式”。

导航方法

1. 阅读下面的快速入门。它涵盖了大多数任务中重要的规则。
2. 从末尾的表格中打开与任务领域匹配的参考文件。每个文件都是独立的。
3. 每项声明后都附有来源 URL。当某个细节决定结果时，请重新打开它。

快速入门

模式与内存

• 模式中的每个字段都会在 RAM 中建立索引。仅供显示的字段应排除在模式之外（仍会存储并返回），或设置 index: false。建议优先使用预定义模式，而不是 .* 自动检测。 https://typesense.org/docs/30.2/api/collections.html 和 https://typesense.org/docs/guide/running-in-production.html
• 没有日期类型：将 Unix 时间戳存储为 int64。geopoint 使用 [lat, lng] 顺序，绝不能使用 GeoJSON 的顺序。 https://typesense.org/docs/30.2/api/collections.html 和 https://typesense.org/docs/30.2/api/geosearch.html
• facet: true 是使用 facet_by 和 group_by 的必要条件。字符串排序需要 sort: true。 https://typesense.org/docs/30.2/api/search.html
• 修改操作会阻塞对该集合的所有写入操作。模式更改的默认做法是：创建一个带版本号的新集合，重新索引，然后更新应用始终使用的别名指向它。 https://typesense.org/docs/30.2/api/collections.html
• 特殊字符会被丢弃，且匹配只支持前缀方式：SKU、电子邮件和 URL 需要使用 token_separators。 https://typesense.org/docs/guide/tips-for-searching-common-types-of-data.html

写入数据

• 默认导入（JSONL）使用 action: 'upsert'。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、加入随机延迟后重试。 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

密钥与多租户

• 绝不要在应用中使用引导密钥。绝不要暴露管理密钥，也不要暴露作用域搜索密钥的父密钥。 https://typesense.org/docs/guide/data-access-control.html
• 作用域搜索密钥：父密钥仅具有 documents:search 权限，在后端为每个用户生成，并嵌入 filter_by 以及 filter_curated_hits: true，否则置顶和精选的结果会在不同租户间泄漏。 https://typesense.org/docs/30.2/api/api-keys.html 和 https://typesense.org/docs/30.2/api/curation.html
• 密钥上的 collections 设置并不能限制全局端点（keys、synonym_sets、stopwords 等）。引用字段会通过连接操作暴露被引用的集合。 https://typesense.org/docs/30.2/api/api-keys.html

运维

• 生产环境：3 或 5 节点高可用集群，客户端配置包含所有节点（如果使用负载均衡器，则加上 nearestNode），RAM 使用率低于 85%。 https://typesense.org/docs/guide/high-availability.html 和 https://typesense.org/docs/guide/running-in-production.html
• 使用 /operations/snapshot 进行备份，绝不能复制运行中的数据目录。先升级跟随者，最后升级领导者。 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 成本、自动模式、嵌套对象、修改、别名、克隆、集合布局
references/tokenization-locale-stemming.md	token_separators、symbols_to_index、中缀、SKU、电子邮件和 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、桶、_eval、衰减、缺失值、置顶
references/faceting-grouping-multi-search.md	分类与策略、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	高可用集群、节点文件、恢复、运维 API、监控、备份、升级、容量规划、CI
references/analytics-and-query-suggestions.md	分析规则和事件、热门查询和无结果查询、计数器、日志规则、建议
references/joins-and-personalization.md	引用字段、连接包含、筛选器和排序、左连接和反连接、异步引用、个性化
references/ui-and-algolia-migration.md	InstantSearch 适配器、与 Algolia 的差异、概念映射、迁移步骤

来源和获取细节列在 SOURCES.md 中。