Chapter 01 · Search Engine Foundations, Elasticsearch vs OpenSearch, Deployment Models, and Lab Setup
Elasticsearch and OpenSearch Lineage, Licensing/Ecosystem Differences, APIs, and Compatibility Expectations
Treat Elasticsearch and OpenSearch as independent products by testing lineage, licensing, clients, APIs and portability rather than assuming compatibility.
Learning outcomes
AtlasMart can satisfy the first catalog fixture on both engines, which makes a dangerous shortcut tempting: “they are basically the same.” This lesson replaces that assumption with a compatibility contract that separates ancestry from current product behavior, licensing, clients, plugins, release cadence, managed offerings and migration risk.
Explain the common ancestry without implying current drop-in compatibility.
Distinguish Elastic distribution/source licensing and subscription features from OpenSearch Apache-2.0 project licensing.
Treat REST shape, clients, plugins, security, lifecycle, vector features and managed services as independently versioned compatibility surfaces.
Build a repeatable API compatibility probe instead of trusting a product-name substitution.
Turn portability requirements into explicit tests and artifacts that support future migration or rollback.
This chapter pins Elasticsearch 9.5.3 (released 3
September 2026) and OpenSearch 3.8.0 (released 4
August 2026) for reproducible examples. OpenSearch 3.9.0 is
scheduled for 29 September 2026 and is therefore not treated
as current. Re-check both projects before reusing these
commands later. Elasticsearch and OpenSearch are independent
products: shared Lucene ancestry does not make their APIs,
plugins, security, lifecycle, vector features, clients, or
managed offerings interchangeable.
The environment used to generate this lesson does not provide
Docker, Elasticsearch, OpenSearch, Kibana, or OpenSearch
Dashboards. The commands and API shapes were reviewed against
the current official documentation but were not executed here.
Expected output is described by invariant and field shape
rather than presented as captured benchmark evidence. Every
destructive action is scoped to
atlasmart-* course containers, volumes, indices,
and local loopback ports.
1. Shared ancestry is historical context, not a compatibility guarantee
OpenSearch 1.0 was derived from the Apache-2.0-licensed Elasticsearch 7.10.2 and Kibana 7.10.2 code line. Since then Elasticsearch and OpenSearch have evolved independently through multiple major releases. The useful mental model in 2026 is therefore “two Lucene-based search platforms with overlapping concepts and diverging product contracts,” not “one is an alternate build of the other.”
A familiar endpoint such as /_search can exist on
both while request options, defaults, field types, response
metadata, security privileges, plugin availability or
managed-service restrictions differ. Compatibility must be
stated at the granularity that matters to the application.
| Surface | What to verify | Why a superficial smoke test misses it |
|---|---|---|
| Mappings / analysis | field types, analyzer components, defaults, limits | A simple text+keyword mapping may work while specialized fields or plugins diverge. |
| Query / aggregation DSL | syntax, semantics, scoring, pagination, approximate behavior | HTTP 200 does not prove equal result ordering or edge-case semantics. |
| Clients | official client/server matrix, product checks, retries, serialization | OpenSearch documentation explicitly recommends OpenSearch clients for OpenSearch 2.x+ rather than assuming Elasticsearch clients are fully compatible. |
| Security | users/roles, certificates, API keys, tenants, realms/backends, IAM | The security products and managed-service integration models are not interchangeable. |
| Operations | lifecycle, snapshots, upgrades, remote clusters, plugins | Names may differ and compatibility is version/topology dependent. |
| AI/vector search | field types, model integration, ANN options, hybrid pipelines | This is a fast-moving divergence surface and must be rechecked per release. |
2. Licensing and subscription are deployment inputs
Elastic’s downloadable default Elasticsearch distribution is governed by the Elastic License and contains free functionality plus features whose availability depends on subscription. Elastic also documents separate source-code licensing choices; those source terms are not the same question as the license governing the default binary distribution. OpenSearch describes the project and its components as Apache License 2.0. A technical course should state those boundaries without pretending to provide legal advice.
Licensing affects architecture when it changes which feature you can deploy, redistribute, host, operate or support under your chosen model. It also affects procurement and exit strategy. The safe engineering practice is to record exact distribution, feature, subscription/tier and terms checked at decision time, then re-check before release because licensing and feature packaging can change independently of API syntax.
Both ecosystems have free/local learning paths and paid managed/support offerings. Evaluate the exact feature set, operational model, support requirement, licensing terms and cloud constraints you intend to use rather than assigning a one-word commercial label.
3. Observe identity before comparing behavior
Every test run should capture what server actually answered. Root/version output is diagnostic metadata, not an authorization or health guarantee, but it prevents comparisons against an assumed product/version.
GET /GET /_cluster/healthGET /_nodes?filter_path=cluster_name,nodes.*.name,nodes.*.version,nodes.*.roles,nodes.*.jvm.versionGET /_cat/indices?v=true
For automation, prefer structured APIs such as
/_cluster/health and nodes information rather than
scraping CAT output; both projects document CAT-style endpoints
primarily as human-oriented inspection surfaces. Store the raw
JSON with the test run so a later difference can be tied to a
version or topology change.
4. Build a compatibility probe, not a compatibility belief
A practical probe is a small, version-controlled suite that
applies the exact subset your application depends on. For
AtlasMart Chapter 01 that subset is intentionally small:
create/delete index, explicit mapping, single-document indexing,
bulk indexing, match, term filter,
count, cluster health and nodes information.
platform: elasticsearchserver_version: 9.5.3client: curlfixture: atlasmart-products-v1checks: - root_identity - create_mapping - index_three_docs - lexical_match_plus_term_filter - mapping_round_trip - cluster_health - delete_fixtureresult: record actual pass/fail and response deltasplatform: opensearchserver_version: 3.8.0client: curlfixture: atlasmart-products-v1checks: same logical checks; do not require byte-identical responsesLater chapters expand this manifest with analyzers, templates, data streams, lifecycle, security, snapshots, SQL/ES|QL/PPL, vector search and performance. The manifest becomes a migration asset because it expresses what “compatible enough for AtlasMart” actually means.
Point the latest Elasticsearch 9 client at OpenSearch 3.8 because both speak HTTP/JSON. A basic request might work, but version checks, generated API types, unsupported endpoints, retry behavior or response parsing can fail later. Repair by using each product’s maintained client for that server line, keeping application access behind a small adapter where portability matters, and testing the exact operations you depend on.
5. Production judgment: portability has a cost, but lock-in has a cost too
Maximum common-denominator design can prevent you from using valuable product-specific features. Maximum product specialization can make migration expensive. The decision is not ideological: rank features by business value and exit cost. Keep authoritative source data outside the search index where appropriate, automate index creation from mappings/templates, preserve ingestion transformations, keep judged query sets, and isolate product-specific client calls so you can measure the cost of change.
For incident response, also record the exact managed service if applicable. “OpenSearch 3.8” running upstream in Docker and “Amazon OpenSearch Service” are not identical operational contracts; likewise Elasticsearch self-managed, Elastic Cloud Hosted and Elastic Cloud Serverless expose different controls. The next lesson makes those responsibility boundaries explicit.
Check your understanding
- What historical fact connects OpenSearch and Elasticsearch, and why is it insufficient as a compatibility claim today?
- Why must licensing be recorded separately from API behavior?
- Why is an HTTP 200 response an incomplete compatibility test?
- What is the safest default client strategy for modern OpenSearch?
- Which artifacts reduce future migration risk?
Review the answers
1. OpenSearch began from the Apache-2.0 Elasticsearch/Kibana 7.10.2 line, but both products have since evolved independently across major releases and ecosystems.
2. A feature can be technically present yet subject to different distribution, subscription, redistribution or service terms; licensing is a separate system constraint.
3. It proves only that one request was accepted. It does not prove equivalent mappings, scoring, errors, retries, plugins, security, lifecycle, vector behavior or edge cases.
4. Use a maintained OpenSearch client with OpenSearch and verify its documented compatibility matrix rather than assuming a current Elasticsearch client is fully compatible.
5. Authoritative source data, reproducible mappings/templates, ingestion definitions, client adapters, compatibility tests, judged relevance queries, benchmark methodology and rollback/runbook documentation.
Summary and next step
Elasticsearch and OpenSearch should be compared as independent platforms with overlapping search concepts. Version, distribution, license, client, plugin, service and feature status are part of every reproducible claim. Next, map those product differences onto who operates the infrastructure and which controls you actually receive.
Authoritative references
- OpenSearch 1.0 GA announcement — Official history describing derivation from Elasticsearch/Kibana 7.10.2.
- OpenSearch language clients — Current client guidance and compatibility cautions.
- Elastic licensing FAQ — Official distribution/source licensing overview.
- Elastic License 2.0 FAQ — Official ELv2 terms summary for the distribution.
- OpenSearch About — Official project and Apache-2.0 licensing statement.
- OpenSearch release schedule — Current release cadence and scheduled versions.