Overview

The purpose of Apache Pekko Projections is described in Use Cases.

In Apache Pekko Projections you process a stream of events or records from a source to a projected model or external system. Each event is associated with an offset representing the position in the stream. This offset is used for resuming the stream from that position when the projection is restarted.

As the source you can select from:

For the offset storage you can select from:

Those building blocks are assembled into a Projection. You can have many instances of it automatically distributed and run in an Apache Pekko Cluster.

Warning

This module is currently marked as May Change in the sense that the API might be changed based on feedback from initial usage. However, the module is ready for usage in production and we will not break serialization format of messages or stored data.

To see a complete example of an Apache Pekko Projections implementation review the Getting Started Guide.

Dependencies

Apache Pekko Projections consists of several modules for specific technologies. The dependency section for each module describes which dependency you should define in your project.

All of them share a dependency to pekko-projection-core:

sbt
libraryDependencies += "org.apache.pekko" %% "pekko-projection-core" % "1.0.0"
Maven
<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-projection-core_${scala.binary.version}</artifactId>
    <version>1.0.0</version>
  </dependency>
</dependencies>
Gradle
def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "org.apache.pekko:pekko-projection-core_${versions.ScalaBinary}:1.0.0"
}
Project Info: Apache Pekko Projections Core
Artifact
org.apache.pekko
pekko-projection-core
1.0.0
JDK versions
OpenJDK 8
OpenJDK 11
OpenJDK 17
Scala versions3.3.3, 2.13.13, 2.12.19
JPMS module namepekko.projection.core
License
API documentation
Forums
Release notesGitHub releases
IssuesGitHub issues
Sourceshttps://github.com/apache/pekko-projection

Pekko version

Apache Pekko Projections requires Pekko 1.0.2 or later. See Pekko’s Binary Compatibility Rules for details.

It is recommended to use the latest patch version of Pekko. It is important all Pekko dependencies are in the same version, so it is recommended to depend on them explicitly to avoid problems with transient dependencies causing an unlucky mix of versions. For example:

sbt
val PekkoVersion = "1.0.2"
libraryDependencies ++= Seq(
  "org.apache.pekko" %% "pekko-cluster-sharding-typed" % PekkoVersion,
  "org.apache.pekko" %% "pekko-persistence-query" % PekkoVersion,
  "org.apache.pekko" %% "pekko-discovery" % PekkoVersion
)
Gradle
def versions = [
  PekkoVersion: "1.0.2",
  ScalaBinary: "2.13"
]
dependencies {
  implementation "org.apache.pekko:pekko-cluster-sharding-typed_${versions.ScalaBinary}:${versions.PekkoVersion}"
  implementation "org.apache.pekko:pekko-persistence-query_${versions.ScalaBinary}:${versions.PekkoVersion}"
  implementation "org.apache.pekko:pekko-discovery_${versions.ScalaBinary}:${versions.PekkoVersion}"
}
Maven
<properties>
  <pekko.version>1.0.2</pekko.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-cluster-sharding-typed_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-persistence-query_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-discovery_${scala.binary.version}</artifactId>
    <version>${pekko.version}</version>
  </dependency>
</dependencies>

Transitive dependencies

The table below shows pekko-projection-core’s direct dependencies and the second tab shows all libraries it depends on transitively.

See the individual modules for their transitive dependencies.

Pekko Classic

Apache Pekko Projections can be used with the new Actor API or the classic Actor API. The documentation samples show the new Actor API, and the Pekko Classic page highlights how to use it with the classic Actor API.

Contributing

Please feel free to contribute to Apache Pekko and Apache Pekko Projections by reporting issues you identify, or by suggesting changes to the code. Please refer to our contributing instructions to learn how it can be done.

We want Pekko to strive in a welcoming and open atmosphere and expect all contributors to respect our code of conduct.

1.0.0