PolarSearch提供1.x和3.x两个主要版本，基于不同的OpenSearch内核构建。本文从内核特性、客户端兼容性和适用场景三个维度对比两个版本的差异，帮助您根据业务需求选择合适的版本。
选型概述
PolarSearch的版本选择，核心是在兼容性与性能之间做出权衡。在添加搜索节点时，您需要根据业务的长期规划和对代码改造成本的接受度，在1.x和3.x版本间进行决策。PolarSearch提供以下决策指南，帮助您作出最合适的选择：
决策维度 | 选择PolarSearch 1.x（ElasticSearch兼容优先） | 选择PolarSearch 3.x（性能优先） |
核心业务需求 | 业务以传统全文检索为主，且短期内没有向量搜索规划。 | 业务包含AI 搜索、RAG等向量检索场景，或希望为未来引入这些能力做好准备。 |
客户端代码改造成本 | 严格要求兼容现有代码。业务应用当前使用Elasticsearch Java high-level REST Client 7.13.4及以下版本，希望零代码改动，实现平滑迁移。 | 接受代码改造。愿意将Elasticsearch客户端切换为OpenSearch客户端，以换取更优的长期收益。 |
性能与功能期望 | 满足当前传统搜索的性能基线即可。 | 追求更优的查询和写入性能，需要更强的安全管控能力，并希望获得OpenSearch社区的最新功能。 |
版本对比
下表对比了PolarSearch 1.x和3.x的核心规格：
特性 | PolarSearch 1.x | PolarSearch 3.x |
Lucene版本 | 8.10.1 | 10.3.1 |
Elasticsearch客户端兼容性 | 100%兼容7.0.0 ~ 7.13.4的Elasticsearch Java high-level REST Client | 不兼容 |
AWS OpenSearch内核兼容性 | 100%兼容OpenSearch 1.x内核。 | 100%兼容OpenSearch 2.x以及3.x内核。 |
AWS OpenSearch客户端兼容性 | 客户端版本兼容性与AWS OpenSearch保持完全一致。详细信息，请参见对应语言客户端的兼容性矩阵。 | |
向量检索（k-NN） | 基础支持，性能较低 | 完整支持，性能高 |
查询性能 | Lucene 8.x基准 | 基于Lucene 10.x，索引和查询性能更优 |
安全能力 | 基础认证 | 增强认证与访问控制 |
适用场景 | Elasticsearch 7.x版本迁移 | 全新项目、AI场景 |
客户端兼容性
PolarSearch的两个版本支持不同的客户端库，请根据您使用的PolarSearch版本选择对应的客户端。
PolarSearch 1.x客户端
客户端 | 推荐版本 | 说明 |
7.10.2 ~ 7.13.4 |
| |
Elasticsearch Java Low Level REST Client | 任意版本 | 稳定且灵活性高，但需自行处理 HTTP 请求与响应的序列化。 |
1.3.20 | 原生支持，推荐用于PolarSearch 1.x的新集成项目。 |
PolarSearch 3.x客户端
客户端 | 推荐版本 | 说明 |
3.3.0 | 原生支持。支持3.x的全部功能，包括向量检索（k-NN）。 | |
Elasticsearch Java Low Level REST Client | 任意版本 | 稳定且灵活性高，但需自行处理 HTTP 请求与响应的序列化。 |
适用场景
从Elasticsearch迁移
如果您的应用当前使用Elasticsearch的Java high-level REST Client客户端（版本7.0.0 ~ 7.13.4），PolarSearch的版本选择取决于您是否进行业务代码改造：
无需改造业务代码：建议选择PolarSearch 1.x。该版本在API层面兼容Elasticsearch 7.x，可从ElasticSearch平滑迁移，无需改造业务代码。您可以直接复用现有的查询DSL、索引映射和客户端配置。
需改造业务代码：PolarSearch 3.x版本不兼容Elasticsearch客户端，迁移过程中，您需要修改业务应用中的客户端库并进行主要的编码和重构工作。
AI搜索与RAG
如果您的应用需要向量检索、语义相似度匹配或检索增强生成（RAG），建议选择PolarSearch 3.x。内置的k-NN插件支持存储高维嵌入向量并执行近似最近邻（ANN）查询。典型应用场景包括：
大语言模型（LLM）应用的RAG知识库。
文档、图片或多模态数据的语义检索。
基于嵌入相似度的推荐系统。
全文检索与向量检索的混合查询。
全新项目
如果您的项目没有Elasticsearch历史依赖，建议选择PolarSearch 3.x。该版本搭载最新OpenSearch内核，具备更优的查询性能和原生向量检索能力，且支持周期更长。建议从一开始就使用OpenSearch原生客户端，以充分利用3.x的全部功能。
传统全文检索
PolarSearch 1.x和3.x均支持全文检索能力，包括倒排索引、分词和相关性评分。如果您的业务以传统全文检索为主：
需要兼容现有Elasticsearch Java high-level REST Client客户端代码时，选择1.x。
追求更优的索引和查询性能或高性能的向量检索（k-NN）时，选择3.x。
迁移建议
PolarSearch提供清晰的路径，帮助您将现有业务平滑迁移或升级至不同版本的PolarSearch。以下是两种典型场景的操作步骤：
从Elasticsearch迁移至PolarSearch 1.x
此路径适用于希望在迁移过程中最大限度减少代码改动的Elasticsearch实例而设计，可以充分利用PolarSearch 1.x对旧版客户端的兼容性。
创建新集群
在您的PolarDB集群中创建一个新的PolarSearch 1.x搜索节点。确认客户端版本兼容
检查并确保您应用中使用的Elasticsearch Java high-level REST Client客户端版本在7.0.0 ~ 7.13.4范围内。如果版本过高（≥7.14.0），请进行降级。迁移数据
使用快照/恢复 (Snapshot/Restore) 或Reindex的方式，将现有的Elasticsearch集群数据全量迁移至新的PolarSearch 1.x搜索节点。测试核心API
将应用的连接指向新的PolarSearch 1.x搜索节点，并测试所有的REST API调用是否兼容，例如索引创建、文档读写、搜索以及聚合等。验证业务功能和性能表现
全面测试您的应用程序，确保所有依赖搜索的功能（如商品搜索、日志查询等）均可正常工作，且返回结果与预期一致。逐步切换流量
通过负载均衡或应用层配置，逐步将线上流量从旧的Elasticsearch集群切换至新的PolarSearch 1.x搜索节点。下线旧实例
在确认新集群稳定运行一段时间后，安全地下线旧的Elasticsearch实例，完成迁移。
从PolarSearch 1.x升级至3.x
此路径适用于希望使用3.x版本新特性（如高性能向量检索）的1.x版本而设计。请注意，此过程涉及客户端的更换和代码重构。
创建新集群
在您的PolarDB集群中创建一个新的PolarSearch 3.x 搜索节点。迁移数据
使用Reindex的方式，将PolarSearch 1.x搜索节点的数据全量迁移至新的PolarSearch 3.x搜索节点。切换客户端并重构代码
将您应用中的客户端库从Elasticsearch Java high-level REST Client或旧版OpenSearch Java Client更换为与OpenSearch 3.x兼容的原生客户端（如OpenSearch Java Client 3.3.0）。此步骤通常涉及主要的编码和重构工作。验证业务功能
在完成代码重构后，全面测试您的应用程序，确保所有功能在新客户端和3.x内核上均可正常工作。验证性能表现
重点关注搜索、索引和聚合的性能，确保其符合或优于1.x版本的表现。逐步切换流量
通过负载均衡或应用层配置，逐步将线上流量从1.x搜索节点切换至新的PolarSearch 3.x搜索节点。下线旧搜索节点
在确认新集群稳定运行一段时间后，安全地下线旧的PolarSearch 1.x搜索节点，完成升级。
常见问题
PolarSearch 3.x能否使用Elasticsearch客户端？
不能。PolarSearch 3.x基于OpenSearch 3.x构建，不兼容Elasticsearch客户端库。Elasticsearch Java high-level REST Client 7.14.0及以上版本和Java API Client 8.x均包含Elastic许可证校验，无法连接PolarSearch。请使用OpenSearch原生客户端（OpenSearch Java Client 3.x及以上）连接PolarSearch 3.x。
为什么Elasticsearch Java high-level REST Client 7.14.0及以上版本无法连接PolarSearch？
从7.14.0版本开始，Elasticsearch Java high-level REST Client增加了版本安全检查，无法正确识别PolarSearch服务端，导致客户端在启动时抛出异常。
对于PolarSearch 1.x，请降级至7.0.0 ~ 7.13.4版本。
对于PolarSearch 3.x，请切换到OpenSearch原生客户端。
PolarSearch 1.x是否支持向量检索？
基础支持，但不推荐。PolarSearch 1.x 的内核版本较旧，虽然提供了基础的向量检索功能，但性能较低，不适合用于对性能有要求的生产环境。如果您需要高性能的向量检索，请务必选择PolarSearch 3.x。