PolarSearch version selection
PolarSearch offers two major versions, 1.x and 3.x, built on different OpenSearch kernels. This guide compares the two versions across kernel features, client compatibility, and use cases to help you choose the right version for your business needs.
Selection overview
Choosing a PolarSearch version involves a trade-off between compatibility and performance. When adding a search node, you must decide between versions 1.x and 3.x based on your long-term business strategy and your tolerance for code refactoring. The following guide helps you make the most appropriate choice:
Decision criteria | Choose PolarSearch 1.x (Elasticsearch compatibility-first) | Choose PolarSearch 3.x (Performance-first) |
Core business needs | Your workloads are focused on traditional full-text search, and you have no short-term plans for vector search. | Your business includes AI search, RAG, or other vector search scenarios, or you plan to introduce these capabilities in the future. |
Client code refactoring cost | You require strict compatibility with existing code. Your application currently uses Elasticsearch Java high-level REST Client 7.13.4 or earlier, and you want a smooth, zero-code migration. | You are comfortable with code refactoring and willing to switch to an OpenSearch client for greater long-term benefits. |
Performance and feature expectations | Meeting the current performance baseline for traditional search is sufficient. | You need superior query and write performance, stronger security controls, and access to the latest features from the OpenSearch community. |
Version comparison
The following table compares the core specifications of PolarSearch 1.x and 3.x:
Feature | PolarSearch 1.x | PolarSearch 3.x |
Lucene version | 8.10.1 | 10.3.1 |
Elasticsearch client compatibility | Fully compatible with Elasticsearch Java high-level REST Client versions 7.0.0 to 7.13.4. | Not compatible |
Vector search (k-NN) | Basic support with low performance | Full support with high performance |
Query performance | Lucene 8.x baseline | Based on Lucene 10.x, it delivers superior indexing and query performance. |
Security capabilities | Basic authentication | Enhanced authentication and access control |
Use cases | Migration from Elasticsearch 7.x | New projects, AI workloads |
Client compatibility
The two versions of PolarSearch support different client libraries. Select a client that matches your PolarSearch version.
PolarSearch 1.x clients
Client | Recommended version | Description |
7.10.2 to 7.13.4 |
| |
Elasticsearch Java Low Level REST Client | Any version | Stable and flexible, but requires you to manually serialize HTTP requests and responses. |
1.3.20 | Natively supported. Recommended for new integration projects with PolarSearch 1.x. |
PolarSearch 3.x clients
Client | Recommended version | Description |
3.3.0 | Natively supported. Supports all features of version 3.x, including vector search (k-NN). | |
Elasticsearch Java Low Level REST Client | Any version | Stable and flexible, but requires you to manually serialize HTTP requests and responses. |
Use cases
Migrating from Elasticsearch
If your application currently uses the Elasticsearch Java high-level REST Client (versions 7.0.0 to 7.13.4), your choice of PolarSearch version depends on whether you are prepared to refactor your business code:
If you do not want to refactor your business code, choose PolarSearch 1.x. This version is API-compatible with Elasticsearch 7.x, enabling a smooth migration from Elasticsearch without requiring code changes. You can reuse your existing query DSL, index mapping, and client configurations.
If you are willing to refactor your business code, choose PolarSearch 3.x. This version is not compatible with Elasticsearch clients. The migration process requires you to replace the client library and perform significant code refactoring.
AI search and RAG
If your application requires vector search, semantic similarity matching, or Retrieval-Augmented Generation (RAG), choose PolarSearch 3.x. The built-in k-NN plugin supports storing high-dimensional embedding vectors and performing approximate nearest neighbor (ANN) queries. Typical use cases include:
RAG knowledge bases for large language model (LLM) applications.
Semantic search for documents, images, or multimodal data.
Recommendation systems based on embedding similarity.
Hybrid queries that combine full-text search and vector search.
New projects
If your project has no legacy dependencies on Elasticsearch, choose PolarSearch 3.x. This version is built on the latest OpenSearch kernel, delivering superior query performance, native vector search capabilities, and a longer support lifecycle. To take full advantage of all its features, use a native OpenSearch client from the beginning.
Traditional full-text search
Both PolarSearch 1.x and 3.x support full-text search capabilities, including inverted index, tokenization, and relevance scoring. If your workloads are primarily focused on traditional full-text search:
Choose 1.x if you need to maintain compatibility with your existing Elasticsearch Java high-level REST Client code.
Choose 3.x if you are looking for better indexing and query performance or high-performance vector search (k-NN).
Migration recommendations
The following sections outline migration paths for two common scenarios:
Elasticsearch to PolarSearch 1.x
This path is designed for users who want to minimize code changes when migrating from Elasticsearch, taking full advantage of the compatibility of PolarSearch 1.x with legacy clients.
Create a new cluster
In your PolarDB cluster, create a new PolarSearch 1.x search node.Verify client version compatibility
Ensure that the Elasticsearch Java high-level REST Client used in your application is within the version range of 7.0.0 to 7.13.4. If your version is 7.14.0 or later, you must downgrade it.Migrate data
Use snapshot/restore or Reindex to fully migrate data from your existing Elasticsearch cluster to the new PolarSearch 1.x search node.Test core APIs
Point your application's connection to the new PolarSearch 1.x search node and test all REST API calls for compatibility, such as index creation, document read/write operations, search, and aggregations.Verify business functionality and performance
Thoroughly test your application to ensure that all search-dependent features, such as product search and log queries, work correctly and that the results match your expectations.Gradually switch traffic
Use a load balancer or application-level configuration to gradually switch live traffic from the old Elasticsearch cluster to the new PolarSearch 1.x search node.Decommission the old instance
After confirming the new cluster runs stably for a period, safely decommission the old Elasticsearch instance to complete the migration.
PolarSearch 1.x to 3.x
This path is for users of version 1.x who want to use the new features in version 3.x, such as high-performance vector search. Note that this process involves replacing the client and refactoring code.
Create a new cluster
In your PolarDB cluster, create a new PolarSearch 3.x search node.Migrate data
Use Reindex to fully migrate data from the PolarSearch 1.x search node to the new PolarSearch 3.x search node.Switch the client and refactor code
Replace the client library in your application, such as the Elasticsearch Java high-level REST Client or an older OpenSearch Java Client, with a native client compatible with OpenSearch 3.x, like OpenSearch Java Client 3.3.0. This step requires significant code refactoring.Verify business functionality
After refactoring the code, thoroughly test your application to ensure all features work correctly with the new client and the 3.x kernel.Verify performance
Focus on the performance of search, indexing, and aggregations to ensure performance meets or exceeds that of version 1.x.Gradually switch traffic
Use a load balancer or application-level configuration to gradually switch live traffic from the 1.x search node to the new PolarSearch 3.x search node.Decommission the old search node
After confirming the new cluster runs stably for a period, safely decommission the old PolarSearch 1.x search node to complete the upgrade.
FAQ
Can I use an Elasticsearch client with PolarSearch 3.x?
No. PolarSearch 3.x is built on OpenSearch 3.x and is not compatible with Elasticsearch client libraries. Elasticsearch Java high-level REST Client versions 7.14.0 and later, and the Java API Client 8.x, include an Elastic license check that prevents them from connecting to PolarSearch. You must use a native OpenSearch client, such as OpenSearch Java Client 3.x or later, to connect to PolarSearch 3.x.
Why can't I connect to PolarSearch using Elasticsearch Java high-level REST Client 7.14.0 or later?
Starting from version 7.14.0, the Elasticsearch Java high-level REST Client includes an Elastic license check. This check cannot correctly identify the PolarSearch server, causing the client to throw an exception on startup.
For PolarSearch 1.x, you must downgrade the client to a version between 7.0.0 and 7.13.4.
For PolarSearch 3.x, you must switch to a native OpenSearch client.
Does PolarSearch 1.x support vector search?
PolarSearch 1.x offers basic support, but its low performance makes it unsuitable for production environments. Its older kernel is not optimized for vector search. If you require high-performance vector search, choose PolarSearch 3.x.