Checking OpenSearch Compatibility Before Leaving Elasticsearch

Then compare:

• Result count
• Result ordering
• Scores where meaningful
• Missing results
• Unexpected results
• Response latency

For search-heavy applications, relevance testing is as important as API compatibility.

Check Aggregations

Applications often use Elasticsearch for analytics as well as search.

For example:

{
  "size": 0,
  "aggs": {
    "categories": {
      "terms": {
        "field": "category"
      }
    }
  }
}

Review every aggregation used by the application.

Test:

• Terms aggregations
• Date aggregations
• Metric aggregations
• Nested aggregations
• Pipeline aggregations
• Filters
• Bucket sizes
• Sorting

Compare both result structure and values.

An aggregation that returns successfully but produces different buckets can create subtle application bugs.

Check Pagination Strategy

Search pagination deserves special attention.

Traditional pagination might use:

from
size

For example:

{
  "from": 0,
  "size": 20
}

Large offsets can become expensive.

Applications may instead use mechanisms such as search-after or point-in-time based approaches.

Before migration, document the pagination strategy currently used and confirm that the target platform supports the required behavior for your version.

Check Bulk Operations

Large applications frequently use bulk indexing.

A simplified bulk request looks like:

{ "index": { "_index": "products", "_id": "101" } }
{ "name": "Laptop", "price": 999.99 }
{ "index": { "_index": "products", "_id": "102" } }
{ "name": "Keyboard", "price": 79.99 }

Test:

• Batch size
• Error handling
• Retry behavior
• Partial failures
• Index refresh behavior
• Throughput
• Timeouts

Do not treat a bulk request as successful only because the HTTP response is successful.

Bulk responses can contain individual item failures.

Review Index Lifecycle Management

If Elasticsearch currently manages index rotation or retention automatically, verify how the equivalent lifecycle process will work after migration.

For example:

products-2026-10
products-2026-11
products-2026-12

Review:

• Index creation
• Aliases
• Rollover
• Retention
• Deletion
• Templates
• Replicas
• Shard settings

The migration should preserve the operational lifecycle, not only the search queries.

Check Ingest Pipelines

Applications may transform documents before indexing.

For example:

Application
    |
    v
Ingest Pipeline
    |
    v
Index

Review every processor used by the current pipeline.

Common examples include:

• Field transformations
• Date processing
• Renaming fields
• Removing fields
• Enrichment
• Parsing

Recreate and test these pipelines on the target platform rather than assuming every processor behaves identically.

Review Security and Authentication

Security configuration is another major migration area.

Check:

• Username/password authentication
• TLS certificates
• Service accounts
• API keys
• Roles
• Permissions
• Index-level access
• Tenant or multi-tenant access
• Audit logging

Do not copy security configuration blindly from Elasticsearch.

The target OpenSearch environment may use a different security model or configuration structure.

The application should be tested using the same least-privilege access model that will be used in production.

Check Plugins and Extensions

Custom plugins can create high migration risk.

Create a complete inventory:

Plugin
Purpose
Used by application?
Required?
OpenSearch equivalent?
Replacement required?

If a critical feature depends on a plugin that has no compatible replacement, the migration may require application redesign.

This is one of the cases where a simple endpoint replacement is not enough.

Test Snapshot and Restore

Disaster recovery should be part of the compatibility assessment.

Test:

1. Create a representative index.
2. Snapshot the required data.
3. Restore it into the target environment.
4. Verify mappings.
5. Verify document counts.
6. Run representative queries.
7. Validate application behavior.

Do not assume that a successful backup from one platform can automatically become a production restore strategy for another platform.

Treat backup migration as a separate compatibility area.

Build a Compatibility Test Suite

A repeatable migration test suite is more useful than manually testing a few queries.

For example:

Compatibility Tests
    |
    +-- Index creation
    +-- Document indexing
    +-- Document updates
    +-- Document deletion
    +-- Full-text search
    +-- Filters
    +-- Sorting
    +-- Aggregations
    +-- Pagination
    +-- Bulk operations
    +-- Authentication
    +-- Error handling

Each test should record expected behavior and actual behavior.

This makes it easier to identify differences before production traffic is moved.

Compare Performance With Realistic Workloads

Do not use synthetic benchmarks alone.

Use representative workloads such as:

• Average search queries
• High-cardinality filters
• Large result sets
• Aggregations
• Bulk indexing
• Concurrent users
• Peak traffic

Measure:

• Average latency
• p95 latency
• p99 latency
• Throughput
• CPU usage
• Memory usage
• Disk usage
• Error rate

The goal is not to prove that one platform is universally faster.

The goal is to determine whether the target platform meets the application's actual requirements.

Common Migration Mistakes

Changing Only the Endpoint

Replacing:

https://old-search-server

with:

https://new-search-server

does not validate compatibility.

The client, queries, mappings, security, and operational processes also need testing.

Testing Only Successful Queries

A migration test should include invalid requests, missing fields, authorization failures, empty results, and partial bulk failures.

Ignoring Search Relevance

A technically successful migration can still damage the user experience if search results are ranked differently.

Copying All Index Settings

Not every setting should be copied without review.

Evaluate each setting against the target platform and workload.

Ignoring Plugins

A custom plugin can represent a major migration dependency.

Inventory plugins before choosing a migration timeline.

Migrating Without a Rollback Strategy

Keep the existing Elasticsearch environment available until the new system has passed production validation.

Best Practices

Inventory Before Migrating

Document every Elasticsearch feature used by the application.

Test the Application, Not Just the Server

Compatibility should be measured from the application's perspective.

Compare Search Results

Use a representative query corpus and compare ranking and result quality.

Separate Data Migration From Traffic Migration

First prove that the data and queries work. Then move application traffic.

Keep the Migration Reversible

Use a staged rollout, feature flag, dual-read strategy, or controlled traffic switch when appropriate.

Monitor After Cutover

Track:

• Search latency
• Error rate
• Empty-result rate
• Result quality
• Indexing failures
• Resource utilization

Advantages of Checking Compatibility First

A compatibility assessment provides:

• Lower migration risk
• Clearer project scope
• Earlier discovery of unsupported features
• Better test coverage
• More predictable production behavior
• Easier rollback planning

It also prevents teams from discovering important incompatibilities after production traffic has already moved.

Disadvantages and Considerations

Compatibility testing requires additional engineering effort.

You may need to:

• Build comparison tests
• Recreate indexes
• Test analyzers
• Review client libraries
• Validate security
• Benchmark workloads
• Test operational processes

For a small application using only basic search, this work may be relatively small.

For a large search platform with custom analyzers, plugins, aggregations, and complex indexing pipelines, the assessment can become a significant migration project.

A Practical Migration Decision

Before leaving Elasticsearch, classify each dependency:

Green
    Compatible with minor or no changes

Yellow
    Requires testing or application changes

Red
    Unsupported, unclear, or requires redesign

A migration is much easier to plan when these classifications are based on actual application behavior.

Do not make the decision based only on feature lists.

Summary

Moving from Elasticsearch to OpenSearch requires more than changing the search endpoint.

Start by inventorying the Elasticsearch features your application actually uses. Check the source and target versions, client libraries, REST APIs, mappings, analyzers, queries, aggregations, pagination, bulk operations, lifecycle management, security configuration, plugins, and backup processes.

The most important compatibility tests should compare real application behavior. Search requests should be tested for both successful execution and result quality. Aggregations should be compared for correctness, and bulk operations should be checked for partial failures.

Keep the existing Elasticsearch environment available while the OpenSearch environment is validated. A staged migration with monitoring and a rollback plan provides a safer path than switching all production traffic at once.

The right question is not whether OpenSearch looks similar to Elasticsearch. The right question is whether your application's current search behavior, operational requirements, and security model can be reproduced reliably on the target platform.