elastic4s: A Typed Scala Client for Elasticsearch

The Scala Integration Gap elastic4s Targets

Elastic4s addresses a specific boundary problem: Elasticsearch publishes an official Java client, but Java syntax does not naturally fit a Scala codebase. Calling that client from Scala is possible, yet the README says it produces more verbose code and does not directly support classes from the Scala core library or idioms such as typeclass support. Elastic4s wraps Elasticsearch operations in a Scala DSL whose requests are intended to expose syntactic and semantic mistakes at compile time.

The target audience is not every Elasticsearch user. It is application developers who work primarily in Scala, want to construct Elasticsearch requests without hand-building Java collection structures, and need serialization tied to Scala domain classes. The project supports Scala 2.13 and Scala 3 in its current release line. Earlier compatibility has narrowed over time: Scala 2.10 support ended with the 5.0.x line, Scala 2.11 with 7.2.0, and Scala 2.12 with 9.0.0.

That compatibility policy matters because a client upgrade can involve decisions about both Elasticsearch and Scala. The current release table includes Elastic4s 9.5.x for Scala 2.13 and Scala 3, while no Scala 2.12 entry is listed for that line. A team cannot treat the client as a version-agnostic bridge and defer all compatibility checks until runtime.

Immutable Requests and Scala-Native Data Flow

Elastic4s builds requests as immutable objects. The README says they can be reused safely or copied to produce derived requests, which is useful when common search criteria or index operations are assembled as application values rather than recreated as mutable builders. The DSL is builder-like, but its operations remain broadly recognizable to readers familiar with the Java API or the Elasticsearch REST API.

Several data representations come directly from Scala rather than Java. The client uses Scala collections, returns `Option` where the corresponding Java methods return null, and accepts Scala `Duration` values instead of strings or primitive duration values. These choices reduce conversion code at application boundaries, although they also mean code written for an existing Java-oriented integration may need adjustment.

Domain conversion is handled through typeclasses for indexing, updating, and searching. The repository contains separate modules for Jackson, Circe, Json4s, PlayJSON, and Spray Json. This allows an application class to participate in Elasticsearch operations without manually setting fields or assembling JSON for every call. The choice of JSON module is not cosmetic: each module belongs to the serialization path, and the README lists all five as supported implementations.

Elastic4s also exposes standard Scala futures and a Reactive Streams implementation. The repository layout broadens that integration with client modules for Akka HTTP, Http4s, Pekko, sniffed clients, STTP variants, and ZIO HTTP. It also includes effect modules for Monix, Scalaz, and ZIO, plus Akka and Pekko stream integrations. Teams can choose among effect styles, but dependency selection increases with the number of optional paths offered.

Installation Requires an Explicit Version Matrix

The README directs users to Maven Central for library releases rather than providing a copy-and-paste dependency declaration. This avoids inventing a package name, but it also means installation cannot be reproduced from the README without first selecting artifacts for the intended Elasticsearch and Scala versions. Projects using the current line should search Maven Central for `nl.gn0s1s` and then verify the relevant artifact and version before adding it to a build.

That search instruction matters because the group ID changed. The README states that releases from 7.17.25 and 8.12.0 use `nl.gn0s1s` instead of `com.sksamuel.elastic4s`. The current version table links `nl.gn0s1s` artifacts for 9.5.x, including `elastic4s-core_2.13` and `elastic4s-core_3`. A build copied from an older article may therefore resolve an obsolete coordinate even when its class and method names appear familiar.

The repository also provides sample directories for Gradle, Maven, and sbt HTTP-client integrations. Those directories are the appropriate next source when selecting the remaining transport dependencies because the README does not include complete installation commands. Until those project files are inspected, there is no confirmed single dependency set that covers every application.

A first evaluation should therefore begin with version selection, not client code. Confirm the Elasticsearch release line, Scala binary version, JSON library, transport, and effect system. Then inspect the matching sample under `samples/` and verify that its dependency graph resolves from the selected repository.

Starting Elasticsearch for a Local Evaluation

The repository includes a `docker-compose.yml` for Elasticsearch 9.5.5, but the README does not present it as a complete installation tutorial for the library. The Compose service runs a single-node Elasticsearch instance with security enabled and maps the container's HTTP and transport ports to host ports `39227` and `39337`. The unusual host ports are intentional according to the file comment, which says they reduce interference with existing local Elasticsearch installations.

The Compose file is configuration, not an executable command that the repository documentation asks readers to run. Its exact relevant settings are:

image: docker.elastic.co/elasticsearch/elasticsearch:9.5.5
discovery.type: single-node
xpack.security.enabled: "true"

Before using this environment as a model for an application, the reader must also inspect `elastic4s-tests/src/test/resources/elasticsearch.yml` and determine the credentials required by the mounted configuration. The Compose file does not show those credentials. It also does not identify this environment as a production deployment template.

The first real use can remain limited to connectivity and one typed operation after dependencies and credentials are known. The README does not contain a complete, current client initialization example, and it does not state the default connection object or exact authentication arguments. Inventing those details would make an evaluation fail for the wrong reason. The concrete starting point is therefore the Compose endpoint at `localhost:39227`, matched against the full sample configuration and initialization code in the corresponding repository sample.

Where the Official Elasticsearch Java Client Differs

The official Elasticsearch Java client is the most direct alternative because it can be used from Scala, as Elastic4s itself acknowledges. Its approach is to preserve the Java client API and runtime model. Elastic4s instead translates request construction, collections, null handling, duration values, and serialization into Scala conventions. The choice is less about access to Elasticsearch features than about how application code represents those features.

For a Scala team with domain-case classes and an established JSON module, that difference can remove conversion and Java-collection friction. Typeclasses can connect those domain classes to indexing, updating, and searching, while the DSL offers editor assistance based on each request type. For a mixed Java and Scala organization, the official client may produce less abstraction between teams and can keep a single Elasticsearch integration model across both languages.

Elastic4s also introduces a compatibility surface. Its modules are organized by transport, JSON library, effect system, streams, and testing. Users must select compatible pieces and account for Scala and Elasticsearch release lines. The official client avoids that particular DSL and module matrix because it is the vendor-provided Java API. Whether these conveniences justify the dependency is an architectural decision, not something established by the README's type-safety claims.

The repository's dedicated `elastic4s-testkit` is another practical distinction. It is described as suitable for tests, so Scala projects that need Elasticsearch-specific fixtures or client behavior may gain more than request syntax alone. The README does not document detailed testkit APIs, so that benefit should be verified against the chosen release.

Release Line, Licensing, and Upgrade Work

Elastic4s is a community project. The README says that pull requests are accepted and releases are published by the maintainer. The repository was not archived, and the last push was on 2026-10-15. Recent release records include v9.5.0 on 2026-09-08, v8.19.2 on 2026-09-08, and v7.17.26 on 2026-09-06. These dates indicate recent branch and release work, although the README does not define a long-term support period or a compatibility promise for every Elasticsearch release.

Upgrades require attention to more than one version axis. The default branch is `series/9.x`, while multiple major Elasticsearch-related release lines appear in the release history. Users must select artifacts that match their Scala version and Elasticsearch target. The moved group ID adds another point to verify when updating build files or copying coordinates from older documentation.

The project is licensed under Apache-2.0. That identifier indicates the stated licensing model and permits reuse under its terms, but this review does not interpret those terms or provide legal advice. Projects with a formal policy review should inspect the repository's `LICENSE` file and account for dependencies used through HTTP clients, JSON libraries, effect libraries, and transport modules.

The upgrade cost is concentrated in build configuration, binary compatibility, serialization behavior, and the selected integration modules. The README does not document a migration command or automated upgrade procedure. A safer first step is to inspect `build.sbt`, `version.sbt`, and the sample projects for the exact target branch, then resolve the corresponding artifacts before changing application code.

Editorial conclusion

Scala teams using Scala 2.13 or Scala 3 that want request construction and domain mapping to remain within Scala conventions should evaluate elastic4s. Projects already standardized on the official Java API, or unable to align their Elasticsearch and Scala versions with the release matrix, should check those constraints first. The most important first verification is a small client build against the exact artifact, Scala version, Elasticsearch version, JSON library, and transport implementation intended for production.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. Philippus/elastic4s on GitHub
4. README
5. Releases