Overview

The purpose of Akka Projections is described in Use Cases.

In Akka 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 Akka 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 Akka Projections implementation review the Getting Started Guide or the Microservices with Akka tutorial.

Dependencies

Akka 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 akka-projection-core:

sbt
libraryDependencies += "com.lightbend.akka" %% "akka-projection-core" % "1.2.4"
Maven
<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.lightbend.akka</groupId>
    <artifactId>akka-projection-core_${scala.binary.version}</artifactId>
    <version>1.2.4</version>
  </dependency>
</dependencies>
Gradle
def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.lightbend.akka:akka-projection-core_${versions.ScalaBinary}:1.2.4"
}
Project Info: Akka Projections Core
Artifact
com.lightbend.akka
akka-projection-core
1.2.4
JDK versions
AdoptOpenJDK 8
AdoptOpenJDK 11
Scala versions2.13.3, 2.12.15
JPMS module nameakka.projection.core
License
Readiness level
Since 1.0.0, 2020-09-10
Home pagehttps://akka.io
API documentation
Forums
Release notesGitHub releases
IssuesGitHub issues
Sourceshttps://github.com/akka/akka-projection

Akka version

Akka Projections requires Akka 2.6.18 or later. See Akka’s Binary Compatibility Rules for details.

It is recommended to use the latest patch version of Akka. It is important all Akka 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 AkkaVersion = "2.6.18"
libraryDependencies ++= Seq(
  "com.typesafe.akka" %% "akka-cluster-sharding-typed" % AkkaVersion,
  "com.typesafe.akka" %% "akka-persistence-query" % AkkaVersion,
  "com.typesafe.akka" %% "akka-discovery" % AkkaVersion
)
Gradle
def versions = [
  AkkaVersion: "2.6.18",
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.typesafe.akka:akka-cluster-sharding-typed_${versions.ScalaBinary}:${versions.AkkaVersion}"
  implementation "com.typesafe.akka:akka-persistence-query_${versions.ScalaBinary}:${versions.AkkaVersion}"
  implementation "com.typesafe.akka:akka-discovery_${versions.ScalaBinary}:${versions.AkkaVersion}"
}
Maven
<properties>
  <akka.version>2.6.18</akka.version>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-cluster-sharding-typed_${scala.binary.version}</artifactId>
    <version>${akka.version}</version>
  </dependency>
  <dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-persistence-query_${scala.binary.version}</artifactId>
    <version>${akka.version}</version>
  </dependency>
  <dependency>
    <groupId>com.typesafe.akka</groupId>
    <artifactId>akka-discovery_${scala.binary.version}</artifactId>
    <version>${akka.version}</version>
  </dependency>
</dependencies>

Transitive dependencies

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

Direct dependencies
OrganizationArtifactVersion
com.typesafe.akkaakka-actor-typed_2.132.6.18
com.typesafe.akkaakka-persistence-query_2.132.6.18
com.typesafe.akkaakka-protobuf-v3_2.132.6.18
com.typesafe.akkaakka-stream_2.132.6.18
org.scala-langscala-library2.13.3
Dependency tree
com.typesafe.akka    akka-actor-typed_2.13    2.6.18    Apache-2.0
    com.typesafe.akka    akka-actor_2.13    2.6.18    Apache-2.0
        com.typesafe    config    1.4.0    Apache-2.0
        org.scala-lang.modules    scala-java8-compat_2.13    1.0.0    Apache-2.0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        org.scala-lang    scala-library    2.13.3    Apache-2.0
    com.typesafe.akka    akka-slf4j_2.13    2.6.18    Apache-2.0
        com.typesafe.akka    akka-actor_2.13    2.6.18    Apache-2.0
            com.typesafe    config    1.4.0    Apache-2.0
            org.scala-lang.modules    scala-java8-compat_2.13    1.0.0    Apache-2.0
                org.scala-lang    scala-library    2.13.3    Apache-2.0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        org.scala-lang    scala-library    2.13.3    Apache-2.0
        org.slf4j    slf4j-api    1.7.32
    org.scala-lang    scala-library    2.13.3    Apache-2.0
    org.slf4j    slf4j-api    1.7.32
com.typesafe.akka    akka-persistence-query_2.13    2.6.18    Apache-2.0
    com.typesafe.akka    akka-persistence_2.13    2.6.18    Apache-2.0
        com.typesafe.akka    akka-actor_2.13    2.6.18    Apache-2.0
            com.typesafe    config    1.4.0    Apache-2.0
            org.scala-lang.modules    scala-java8-compat_2.13    1.0.0    Apache-2.0
                org.scala-lang    scala-library    2.13.3    Apache-2.0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        com.typesafe.akka    akka-stream_2.13    2.6.18    Apache-2.0
            com.typesafe.akka    akka-actor_2.13    2.6.18    Apache-2.0
                com.typesafe    config    1.4.0    Apache-2.0
                org.scala-lang.modules    scala-java8-compat_2.13    1.0.0    Apache-2.0
                    org.scala-lang    scala-library    2.13.3    Apache-2.0
                org.scala-lang    scala-library    2.13.3    Apache-2.0
            com.typesafe.akka    akka-protobuf-v3_2.13    2.6.18    Apache-2.0
            com.typesafe    ssl-config-core_2.13    0.4.2    Apache-2.0
                com.typesafe    config    1.4.0    Apache-2.0
                org.scala-lang.modules    scala-parser-combinators_2.13    1.1.2    Apache-2.0
                    org.scala-lang    scala-library    2.13.3    Apache-2.0
                org.scala-lang    scala-library    2.13.3    Apache-2.0
            org.reactivestreams    reactive-streams    1.0.3    CC0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        org.scala-lang    scala-library    2.13.3    Apache-2.0
    com.typesafe.akka    akka-protobuf-v3_2.13    2.6.18    Apache-2.0
    com.typesafe.akka    akka-stream_2.13    2.6.18    Apache-2.0
        com.typesafe.akka    akka-actor_2.13    2.6.18    Apache-2.0
            com.typesafe    config    1.4.0    Apache-2.0
            org.scala-lang.modules    scala-java8-compat_2.13    1.0.0    Apache-2.0
                org.scala-lang    scala-library    2.13.3    Apache-2.0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        com.typesafe.akka    akka-protobuf-v3_2.13    2.6.18    Apache-2.0
        com.typesafe    ssl-config-core_2.13    0.4.2    Apache-2.0
            com.typesafe    config    1.4.0    Apache-2.0
            org.scala-lang.modules    scala-parser-combinators_2.13    1.1.2    Apache-2.0
                org.scala-lang    scala-library    2.13.3    Apache-2.0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        org.reactivestreams    reactive-streams    1.0.3    CC0
        org.scala-lang    scala-library    2.13.3    Apache-2.0
    org.scala-lang    scala-library    2.13.3    Apache-2.0
com.typesafe.akka    akka-protobuf-v3_2.13    2.6.18    Apache-2.0
com.typesafe.akka    akka-stream_2.13    2.6.18    Apache-2.0
    com.typesafe.akka    akka-actor_2.13    2.6.18    Apache-2.0
        com.typesafe    config    1.4.0    Apache-2.0
        org.scala-lang.modules    scala-java8-compat_2.13    1.0.0    Apache-2.0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        org.scala-lang    scala-library    2.13.3    Apache-2.0
    com.typesafe.akka    akka-protobuf-v3_2.13    2.6.18    Apache-2.0
    com.typesafe    ssl-config-core_2.13    0.4.2    Apache-2.0
        com.typesafe    config    1.4.0    Apache-2.0
        org.scala-lang.modules    scala-parser-combinators_2.13    1.1.2    Apache-2.0
            org.scala-lang    scala-library    2.13.3    Apache-2.0
        org.scala-lang    scala-library    2.13.3    Apache-2.0
    org.reactivestreams    reactive-streams    1.0.3    CC0
    org.scala-lang    scala-library    2.13.3    Apache-2.0
org.scala-lang    scala-library    2.13.3    Apache-2.0

See the individual modules for their transitive dependencies.

Akka Classic

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

Contributing

Please feel free to contribute to Akka and Akka 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 Akka to strive in a welcoming and open atmosphere and expect all contributors to respect our code of conduct.

Found an error in this documentation? The source code for this page can be found here. Please feel free to edit and contribute a pull request.