# OpenSearch: what the repository actually ships, and how to run it

> OpenSearch is an Apache-2.0 distributed search and observability engine written in Java. This is what the repository and the documentation describe, where the boundaries are, and how to get a first query back.

**opensearch-project/OpenSearch** — Open source distributed and RESTful search engine. OpenSearch is an open-source, enterprise-grade search and observability suite that brings order to unstructured data at scale.

- Repository: https://github.com/opensearch-project/OpenSearch
- Website: https://opensearch.org/docs/latest/opensearch/index/
- Stars: 13,775 · Forks: 2,972
- Language: Java
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/opensearch-project-opensearch

## The problem OpenSearch is built to solve

OpenSearch is a distributed search engine that speaks REST. The README describes it as an "open-source, enterprise-grade search and observability suite that brings order to unstructured data at scale". That sentence covers two distinct buyers. The first is an engineering team that has text or log data it needs to query by relevance, filter and aggregate, and does not want to operate a proprietary search cluster. The second is an observability team that wants log ingestion, dashboards and alerting in the same system as its search workload rather than two separate stacks.

The repository layout confirms the scope. There is a server/ directory holding the engine, modules/ and plugins/ for the optional components, client/ for language clients, and distribution/ for the assembled builds. There are also rest-api-spec/ for the HTTP API surface and formal-models/ for specifications. That is a search engine plus an ecosystem, not a single library.

The audience is therefore teams with operational capacity. You are running a JVM process, or a cluster of them, and you own the storage, the shard layout and the upgrades.

## How the engine is put together in the repository

The primary language is Java and the build is Gradle: build.gradle, settings.gradle and the gradlew wrapper sit at the top level, with buildSrc/ holding the build logic. If you want to compile from source rather than install a release, that is the entry point, and the DEVELOPER_GUIDE.md file is where the repository points contributors.

The API is HTTP and JSON. rest-api-spec/ is the machine-readable description of the REST surface, which is why the API is the stable contract rather than the Java classes. Client libraries live under client/, and the documentation site is where the project directs users for usage.

Optional behaviour is packaged as modules and plugins rather than baked into the core. That matters for two reasons. It means the distribution you install decides which capabilities exist, and it means a plugin can lag the core version. The README does not document plugin compatibility rules, so treat the release notes and the distribution manifest as the authority for what ships together.

The project is governed by the OpenSearch Foundation and is a registered trademark of LF Projects, LLC. The README states that the project includes certain Apache-licensed Elasticsearch code from Elasticsearch B.V., and that Elasticsearch B.V. is not the source of the other source code. That sentence is the honest description of the lineage, and it is worth reading before you assume API parity in either direction.

## Installing OpenSearch and reaching the API

The README does not contain install instructions. It points to the downloads page and the documentation site, so that is where you should get a build rather than following a command copied from an article. The documentation covers install paths for the supported platforms, including Windows.

Once an instance is running, the API is the way to confirm it works. The REST surface is described in rest-api-spec/ in the repository, and the documentation covers the API in detail. The repository also ships client libraries under client/ for calling it from application code, and the documentation covers using OpenSearch from Python and from Spring Boot.

The README gives no example request, no port number and no environment variable, so there is nothing here to copy. Read the API reference in the documentation for the exact request shapes for cluster info, indexing a document and searching, and read the client documentation for the language you use. Pin that client to the server version you are running, because the API version is what the client speaks.

## Where OpenSearch is the wrong tool

OpenSearch is not a database in the transactional sense. The search questions people ask about it include whether it is a database, and the honest answer from the repository is that it is a search and observability engine: the API is REST and JSON, and there is no SQL transaction model in the core description. If you need multi-row atomic commits with foreign keys and rollback, this is the wrong layer.

Plugin coupling is the second boundary. Because optional capabilities ship as modules and plugins, the feature set is a property of your distribution, not of the project as a whole. A capability you read about may not be present in the build you installed, and upgrading the core can leave a plugin behind. The README does not document rollback, so plan upgrades with the release notes in front of you rather than assuming you can reverse one cleanly.

The third boundary is lineage. The README's own trademark section states that OpenSearch includes certain Apache-licensed Elasticsearch code and that Elasticsearch B.V. is not the source of the other source code. Any workload that depends on Elasticsearch-specific behaviour, or on a feature that exists on only one side, needs a compatibility check rather than an assumption. The two projects share history; they do not share a release train.

Finally, operating a cluster is real work. Shards, replicas, mappings and upgrade sequencing are yours to manage. A single-node install is easy; a production cluster is an infrastructure commitment.

## OpenSearch versus Elasticsearch: the actual difference

The comparison people search for most is OpenSearch versus Elasticsearch, and the repository answers part of it directly. OpenSearch is licensed under Apache-2.0 and is governed by the OpenSearch Foundation, with the trademark held by LF Projects, LLC. That governance and licence structure is the substantive difference for teams that need a permissively licensed search engine they can build a product on.

The second difference is the plugin model. OpenSearch packages optional capabilities as modules and plugins that ship with the distribution, which is why the project describes itself as a suite rather than only an engine. If your requirements include security, alerting or index management as first-class parts of the install, that packaging is the reason to look here.

The third difference is direction of travel. The README states that the project includes certain Apache-licensed Elasticsearch code from Elasticsearch B.V. So the starting point is shared, but the APIs and features have diverged since. A migration in either direction is a compatibility project, not a version bump. Verify the specific API calls and query types your application uses against the target version's documentation before you plan the move.

## Maintenance, releases and what upgrades cost

The repository is not archived. The most recent push recorded is 2026-08-05, and the same date carries release 3.8.0. Before that, 2.19.6 landed on 2026-07-06 and 3.7.0 on 2026-06-09. The cadence is visible in those dates, and the 2.x line is still receiving releases alongside 3.x, which is useful if you are pinned to the older major version.

CHANGELOG.md and release-notes/ are in the repository, and RELEASING.md documents how releases are produced. That is the material to read before an upgrade, because the README itself says nothing about rollback or about version compatibility between core and plugins. The upgrade cost is therefore not something you can estimate from the README alone; it depends on which modules and plugins your distribution includes.

On licensing, the project is Apache-2.0, with the full text in LICENSE.txt and attribution details in NOTICE.txt. The trademark section is explicit that OpenSearch is a registered trademark of LF Projects, LLC, and that the project includes Apache-licensed Elasticsearch code from Elasticsearch B.V. If you plan to redistribute a build or use the name in a product, read LICENSE.txt and NOTICE.txt yourself. This is a description of what the files say, not legal advice.

## Conclusion

Adopt OpenSearch when you need a REST-addressable search or log store that you can run yourself under Apache-2.0, and when the plugin model (security, alerting, index management) is part of the reason you are choosing it. Do not adopt it as a primary transactional database or as a drop-in for a workload that depends on Elasticsearch-only features, because the README explicitly states that the project includes certain Apache-licensed Elasticsearch code and that Elasticsearch B.V. is not the source of the other source code. Before committing, verify your target version against the release notes for 3.8.0, confirm which plugins your distribution bundles, and check that your client library speaks the same API version you plan to run.

## FAQ

### Is OpenSearch the same as Elasticsearch?

No. The README states that OpenSearch includes certain Apache-licensed Elasticsearch code from Elasticsearch B.V., and that Elasticsearch B.V. is not the source of the other source code. They share history but are separate projects with separate governance, and OpenSearch is a registered trademark of LF Projects, LLC.

### What is OpenSearch used for?

The README describes it as an open-source, enterprise-grade search and observability suite that brings order to unstructured data at scale. In practice that covers search over text data and observability over logs, both reached through a REST API.

### Is OpenSearch an AWS product?

The repository does not describe OpenSearch as an AWS product. The README states the project is governed through the OpenSearch Foundation and that OpenSearch is a registered trademark of LF Projects, LLC, with the code licensed under Apache-2.0.

### How do I install OpenSearch?

The README does not include install steps. It points to the project downloads page and the documentation site, which is where the supported install paths, including Windows, are documented.

### How do I use the OpenSearch API?

The API is HTTP and JSON, described in rest-api-spec/ in the repository. The documentation is where the request shapes are documented, and the repository ships client libraries under client/ for calling it from application code.

### How do I use OpenSearch from Python?

The repository has a client/ directory for language clients, and the documentation covers using OpenSearch from Python. Pin the client to the server version you are running, since the API version is what the client speaks.

## Sources

- [Official documentation](https://opensearch.org/docs/latest/opensearch/index/)
- [Official README](https://github.com/opensearch-project/OpenSearch#readme)
- [Project repository](https://github.com/opensearch-project/OpenSearch)
- [Release notes](https://github.com/opensearch-project/OpenSearch/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/opensearch-project-opensearch