# elasticsearch-sql: querying Elasticsearch with SQL, and what the deprecation notice means for you > NLPchina/elasticsearch-sql is a Java plugin that accepts SQL at an HTTP endpoint and translates it to Elasticsearch queries. It works, it is versioned against recent Elasticsearch releases, and its own README tells you to use something else. **NLPchina/elasticsearch-sql** — Use SQL to query Elasticsearch - Repository: https://github.com/NLPchina/elasticsearch-sql - Stars: 7,009 · Forks: 1,528 - Language: Java - License: Apache-2.0 - Published: 2026-09-22 · Updated: 2026-09-22 · Language: en - Canonical page: https://hysenlabs.com/projects/nlpchina-elasticsearch-sql ## The problem elasticsearch-sql solves, and the audience it was built for Elasticsearch's native query language is a JSON DSL. Writing it by hand is fine for one query and tedious for a hundred, especially for people who already think in SELECT, WHERE and GROUP BY. elasticsearch-sql exists to close that gap inside the cluster itself: it is a Java plugin that accepts SQL text and turns it into Elasticsearch queries, so an analyst or an application can send a statement rather than construct a nested JSON body. The README frames the pitch in one line: query Elasticsearch using familiar SQL syntax, and the README also notes that ES functions can be used in SQL. The audience is therefore teams that already run Elasticsearch and want SQL as an additional access path, not teams choosing a database. It is not a storage engine and it does not add transactions or a schema. It is a translation layer that happens to be installed where the data lives. The repository is Java, licensed Apache-2.0, with no homepage listed and the wiki hosted on GitHub. The README's own deprecation notice is the first thing a reader meets, and it is worth taking literally: the project states it is no longer in active development and recommends the official x-pack-sql and OpenDistro for Elasticsearch SQL instead. ## How the plugin turns a statement into an Elasticsearch query The mechanism is an HTTP endpoint registered by the plugin. Since 7.5.0.0 the README states that the path /_sql changed to /_nlpcn/sql, and /_sql/_explain changed to /_nlpcn/sql/explain. That rename matters for anyone copying older tutorials: a request to /_sql on a modern build will not reach the plugin. The explain endpoint is the part worth understanding. It returns the Elasticsearch query the plugin derived from your SQL rather than executing it, which is the practical way to check whether a join, an aggregation or a function call was translated the way you expected. The README shows an explain example section but the captured text does not include the payload, so the exact response shape is not documented here; the wiki is where the project points readers for detail. Because translation happens server side, the plugin inherits the cluster's own authentication and transport. There is no separate SQL service to run, and no second network hop. The cost is that the plugin must be rebuilt for each Elasticsearch line, which is why the README carries a long version table mapping an Elasticsearch version to a plugin version and a branch name such as elastic9.3.4 or elastic7.17.28. That table is the real compatibility contract. ## Installing elasticsearch-sql and running a first query The README's setup section says to install as a plugin, and the version table tells you which build pairs with your Elasticsearch version. Pick the row that matches your cluster exactly; the table lists entries such as 9.3.4, 8.19.15, 7.17.28 and 6.8.23, each with its own branch. The recent releases follow the same pattern, with v9.3.4 described as elasticsearch 9.3.4 support. The README does not give a concrete install command in the captured text, so the only instruction available is to install as a plugin, using the version row that matches your cluster. Once the plugin is loaded, the SQL endpoint is the path the README documents: /_nlpcn/sql, with /_nlpcn/sql/explain for the explain form. A query sent to /_sql will not reach a build from 7.5.0.0 onward. Before running anything expensive, use the explain path. It returns the translated query instead of results, which is how you check whether a join, an aggregation or a function call was translated the way you expected. The README does not document the response format in the captured text, so treat the output as something to inspect rather than parse. The wiki is the project's stated reference for further examples. ## Where elasticsearch-sql stops being the right tool The deprecation notice is the largest limitation and it is stated by the project itself. The README says the project is no longer in active development, is deprecated, and directs readers to x-pack-sql and OpenDistro for Elasticsearch SQL. Anyone starting fresh should read that as the project's own recommendation, not as a third-party opinion. The version table carries a second, quieter constraint. From 2.0.0 through 5.6.5, every row is marked delete commands not supported. If your workflow depends on DELETE through SQL on those lines, the plugin will not provide it. Later rows in the table drop that remark, but the captured README does not explain what changed, so the behaviour on 5.6.6 and later is not documented in the text available here. There is also a translation boundary to accept. SQL is being mapped onto a document store with its own execution model, and the explain endpoint exists precisely because that mapping is not always obvious. Queries that assume relational semantics, particularly joins across large indices, are where a translation layer is most likely to behave differently from what a SQL-trained reader expects. The README does not describe join execution or its limits, so that is a question to answer on your own cluster before depending on it. ## x-pack-sql and OpenDistro SQL: what actually differs The alternatives the README names are not drop-in replacements with a different logo. x-pack-sql ships as part of Elastic's own distribution, which means it moves with the Elasticsearch release rather than lagging behind it through a separate build matrix. OpenDistro for Elasticsearch SQL comes from the AWS side and, as the README notes, is licensed under Apache 2. The practical difference for a team is who owns compatibility: with elasticsearch-sql you own the version pairing yourself, and the version table is long because that pairing has to be maintained per Elasticsearch release. A second difference is surface area. elasticsearch-sql is a plugin with an HTTP endpoint and a web frontend shown in the README screenshot. The official options are positioned as the supported route, which matters when you need someone to answer a bug report. The plugin's own README sending you elsewhere is the clearest signal about where maintenance effort sits. The related searches around this topic also pull in ESQL and OpenSearch SQL, which are separate query languages and engines, not SQL translators for Elasticsearch. If what you want is a SQL dialect that the vendor supports, the README already tells you which two projects to look at. ## Maintenance, upgrade cost and the Apache-2.0 licence Maintenance status is visible from the facts rather than the prose. The repository is not archived, and the last push was on 2026-06-30. The most recent release listed is v9.3.4 on 2026-05-04, described as elasticsearch 9.3.4 support, with v9.3.3 and v9.3.2 released the same day. So builds are still being cut against current Elasticsearch lines even though the README declares the project deprecated. Those two signals point in different directions, and a reader should weigh the README's own statement more heavily than the release cadence when planning. The upgrade cost is the version table. Each Elasticsearch upgrade means finding the matching plugin row and branch, and the table shows that this has been done for many releases across the 1.x through 9.x lines. That is real work per upgrade, and it is work the plugin's users take on rather than Elastic. On licensing, the project is Apache-2.0, and the README notes that OpenDistro for Elasticsearch SQL is also Apache 2. That is a fact about the licences, not advice. If your organisation has rules about which Elastic components you may run, check them against the actual artefacts you install; nothing here should be read as a legal opinion. ## Conclusion Adopt it only if you are pinned to an Elasticsearch line the plugin still builds against and you need SQL reachable over HTTP without a separate service. Do not adopt it for new work: the README declares the project deprecated and points at x-pack-sql and OpenDistro for Elasticsearch SQL. Verify first that your exact Elasticsearch version appears in the version table, that the client you plan to use can target /_nlpcn/sql rather than /_sql, and whether your queries rely on DELETE, which the table marks as unsupported from 2.0.0 through 5.6.5. ## FAQ ### Is Elasticsearch a SQL database? No. Elasticsearch is a document store whose native query language is a JSON DSL, and elasticsearch-sql is a plugin that translates SQL statements into those queries rather than a database that speaks SQL natively. ### What query language does Elasticsearch use? Elasticsearch uses its own JSON query DSL. elasticsearch-sql exists because that DSL is not SQL, and the plugin accepts SQL text and converts it into Elasticsearch queries. ### Is Elasticsearch SQL or NoSQL? Elasticsearch is NoSQL. SQL reaches it only through a translation layer, and elasticsearch-sql is one such layer, installed as a plugin inside the cluster. ### What is the difference between elasticsearch-sql and the Elasticsearch DSL? The DSL is the native JSON format Elasticsearch executes. elasticsearch-sql lets you write SQL instead and translates it, and its explain endpoint returns the resulting query so you can see the translation. ## Sources - [Issues](https://github.com/NLPchina/elasticsearch-sql/issues) - [License: Apache-2.0](https://github.com/NLPchina/elasticsearch-sql/blob/master/LICENSE) - [NLPchina/elasticsearch-sql on GitHub](https://github.com/NLPchina/elasticsearch-sql) - [README](https://github.com/NLPchina/elasticsearch-sql/blob/master/README.md) - [Releases](https://github.com/NLPchina/elasticsearch-sql/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/nlpchina-elasticsearch-sql