A recent project has prompted me to adopt Node.js, a popular by-design lean and mean server, as the server-side tech stack. With the requirement for a rather UI feature-rich web application, I include React (a.k.a. ReactJS) as part of the tech stack. A backend database is needed, so I pick PostgreSQL. Thus, this is a deviation from the Scala / Akka Actor / Akka Stream tech stack I’ve been using in recent years.
PostgreSQL has always been one of my favorite database choices whenever a robust RDBMS with decent scalability is required for a given R&D project. With Node.js being the chosen app/API server and React the UI library for the project at hands, I decided to use Sequelize, a popular ORM tool in the Node ecosystem, as the ORM tool.
First and foremost, I must acknowledge the effective documentation on Sequelize’s official website, allowing developers new to it to quickly pick up the essential know-how’s from:
Assuming the Node.js module is already in place, to install PostgreSQL driver and Sequelize, simply do the following under the Node project root subdirectory:
Note that within the above data model scripts, each of the table entities is represented by a function with two arguments — Sequelize refers to the Sequelize library, whereas sequelize is an instance of it. The instance is what’s required to connect to a given database. It has a method define() responsible for specifying the table definition including the table attributes and the by-default pluralized table name.
Also note that it looks as though the typical primary key column id is missing in most of the above table definitions. That’s because Sequelize would automatically create an auto-increment integer column id if none is specified. For a table intended to be set up with specific primary key values, define it with explicitly (similar to how table roles is set up in our sample models).
The Sequelize instance is created and initialized within ${node-project-root}/app/models/index.js as shown below.
As can be seen from the index.js data model script, after a Sequelize instance is instantiated, it loads the database configuration information from db.config.js as well as the table definitions from the individual model scripts.
Also included in the index.js script are examples of both the one-to-many and many-to-many association types. For instance, the relationship between table users and orders is one-to-many with userId as the foreign key:
Contrary to the camelCase naming style for variables in programming languages such as JavaScript, Java, Scala, conventional RDBMSes tend to use snake_case naming style for table and column names. To accommodate the different naming conventions, Sequelize automatically converts database schemas’ snake_case style to JavaScript objects’ camelCase. To keep the database schema in snake_case style one can customize the Sequelize instance by specifying underscored: true within the define {} segment as shown below.
As mentioned in an earlier section, Sequelize pluralizea database table names by default. To suppress the auto-pluralization, specifying also freezeTableName: true within define {} followed by defining the table with singular names within the individual model scripts.
Personally, I prefer keeping database table names singular. However, I have a table I’d like to name it user which is disallowed within PostgreSQL’s default schema namespace. That’s because PostgreSQL makes user a reserved keyword.
A work-around would be to define a custom schema that serves as a namespace in which all user-defined entities are contained. An inconvenient consequence is that when performing queries using tools like psql, one would need to alter the schema search path from the default public schema to the new one.
ALTER ROLE leo SET search_path TO myschema;
After weighing the pros and cons, I decided to go with Sequelize‘s default pluralized table naming. Other than this minor inconvenience, I find Sequelize an easy-to-pick-up ORM for wiring programmatic CRUD operations with PostgreSQL from within Node’s controller modules.
The following sample snippet highlights what a simple find-by-primary-keyselect and update might look like in a Node controller:
const db = require("../models");
const User = db.user;
...
exports.find = (req, res) => {
const id = req.params.id;
User.findByPk(id)
.then(data => {
if (data) {
res.send(data);
} else {
res.status(404).send({
message: `ERROR finding user with id=${id}!`
});
}
})
.catch(err => {
res.status(500).send({
message: `ERROR retrieving user data!`
});
});
};
exports.update = (req, res) => {
const id = req.params.id;
User.update(req.body, {
where: { id: id }
})
.then(num => {
if (num == 1) {
res.send({
message: "User was updated successfully!"
});
} else {
res.send({
message: `ERROR updating user with id=${id}!`
});
}
})
.catch(err => {
res.status(500).send({
message: `ERROR updating user data!`
});
});
};
In the next blog post, we’ll shift our focus towards the popular UI library React and how state changes propagate across the UI components and the React Redux central store.
With the increasing demand for big data transformations on distributed platforms, one approach is to put in place a streaming ETL system with built-in packpressure using Alpakka Kafka API that allows composable pipelines to be constructed on-demand. This blog post extends the previous post which shows a skeletal version of the system.
Let’s first review the diagram shown in the previous post of what we’re aiming to build — a streaming ETL system empowered by reactive streams and Apache Kafka’s publish-subscribe machinery for durable stream data to be produced or consumed by various data processing/storage systems:
In this blog post, we’re going to:
enhance the data warehouse consumer to programmatically track the commit offset positions,
plug into an existing consumer a data processing pipeline as a stream processing operator, and,
add to the streaming ETL system a mix of heterogeneous producers and consumers
Action item #1 would address the requirement of at-least-once delivery in stream consumption. #2 illustrates how to add to the streaming ETL system a custom data pipeline as a composable stream flow, and #3 showcases how data in various storage systems can participate in the real-time stream to operate (serially or in parallel) as composable sources, flows and sinks. All relevant source code is available in this GitHub repo.
Real-time streaming ETL/pipelining of property listing data
For usage demonstration, the application runs ETL/pipelining of data with a minified real estate property listing data model. It should be noted that expanding or even changing it altogether to a different data model should not affect how the core streaming ETL system operates.
Below are a couple of links related to library dependencies and configurations for the core application:
Configurations for Akka, Kafka, PostgreSQL & Cassandra in application.conf[separate tab]
It’s also worth noting that the application can be scaled up with just configurative changes. For example, if the Kafka brokers and Cassandra database span across multiple hosts, relevant configurations like Kafka’s bootstrap.servers could be "10.1.0.1:9092,10.1.0.2:9092,10.1.0.3:9092" and contact-points for Cassandra might look like ["10.2.0.1:9042","10.2.0.2:9042"].
Next, let’s get ourselves familiarized with the property listing data definitions in the PostgreSQL and Cassandra, as well as the property listing classes that model the schemas.
Alpakka comes with a simple API for CSV file parsing with method lineScanner() that takes parameters including the delimiter character and returns a Flow[ByteString, List[ByteString], NotUsed].
Below is the relevant code in CsvPlain.scala that highlights how the CSV file gets parsed and materialized into a stream of Map[String,String] via CsvParsing and CsvToMap, followed by transforming into a stream of PropertyListing objects.
Note that the drop(offset)/take(limit) code line, which can be useful for testing, is for taking a segmented range of the stream source and can be removed if preferred.
A subsequent map wraps each of the PropertyListing objects in a ProducerRecord[K,V] with the associated topic and key/value of type String/JSON before being streamed into Kafka via Alpakka Kafka’s Producer.plainSink().
A Kafka producer using Alpakka Slick
The PostgresPlain producer, which is pretty much identical to the one described in the previous blog post, creates a Kafka producer using Alpakka Slick which allows SQL queries into a PostgreSQL database to be coded in Slick’s functional programming style.
The partial code below shows how method Slick.source() takes a streaming query and returns a stream source of PropertyListing objects.
The high-level code logic in PostgresPlain is similar to that of the CsvPlain producer.
A Kafka consumer using Alpakka Cassandra
We created a Kafka consumer in the previous blog post using Alpakka Kafka’s Consumer.plainSource[K,V] for consuming data from a given Kafka topic into a Cassandra database.
The following partial code from the slightly refactored version of the consumer, CassandraPlain shows how data associated with a given Kafka topic can be consumed via Alpakka Kafka’s Consumer.plainSource().
def runPropertyListing(consumerGroup: String,
topic: String)(implicit
cassandraSession: CassandraSession,
jsonFormat: JsonFormat[PropertyListing],
system: ActorSystem,
ec: ExecutionContext): Future[Done] = {
val consumerConfig = system.settings.config.getConfig("akkafka.consumer.with-brokers")
val consumerSettings =
ConsumerSettings(consumerConfig, new StringDeserializer, new StringDeserializer)
.withGroupId(consumerGroup)
.withProperty(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest")
val table = "propertydata.property_listing"
val partitions = 10 // number of partitions
val statementBinder: (ConsumerRecord[String, String], PreparedStatement) => BoundStatement = {
case (msg, preparedStatement) =>
val p = msg.value().parseJson.convertTo[PropertyListing]
preparedStatement.bind(
(p.propertyId % partitions).toString, Int.box(p.propertyId), p.dataSource.getOrElse("unknown"),
Double.box(p.bathrooms.getOrElse(0)), Int.box(p.bedrooms.getOrElse(0)), Double.box(p.listPrice.getOrElse(0)), Int.box(p.livingArea.getOrElse(0)),
p.propertyType.getOrElse(""), p.yearBuilt.getOrElse(""), p.lastUpdated.getOrElse(""), p.streetAddress.getOrElse(""), p.city.getOrElse(""), p.state.getOrElse(""), p.zip.getOrElse(""), p.country.getOrElse("")
)
}
val cassandraFlow: Flow[ConsumerRecord[String, String], ConsumerRecord[String, String], NotUsed] =
CassandraFlow.create(
CassandraWriteSettings.defaults,
s"""INSERT INTO $table (partition_key, property_id, data_source, bathrooms, bedrooms, list_price, living_area, property_type, year_built, last_updated, street_address, city, state, zip, country)
|VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""".stripMargin,
statementBinder
)
val control: DrainingControl[Done] =
Consumer
.plainSource(consumerSettings, Subscriptions.topics(topic))
.via(cassandraFlow)
.toMat(Sink.ignore)(DrainingControl.apply)
.run()
Thread.sleep(2000)
control.drainAndShutdown()
}
Alpakka’s CassandraFlow.create() is the stream processing operator responsible for funneling data into the Cassandra database. Note that it takes a CQLPreparedStatement along with a “statement binder” that binds the incoming class variables to the corresponding Cassandra table columns before executing the CQL.
Enhancing the Kafka consumer for ‘at-least-once’ consumption
To enable at-least-once consumption by Cassandra, instead of Consumer.plainSource[K,V], we construct the stream graph via Alpakka Kafka Consumer.committableSource[K,V] which offers programmatic tracking of the commit offset positions. By keeping the commit offsets as an integral part of the streaming data, failed streams could be re-run from the offset positions.
def runPropertyListing(consumerGroup: String,
topic: String)(implicit
cassandraSession: CassandraSession,
jsonFormat: JsonFormat[PropertyListing],
system: ActorSystem,
ec: ExecutionContext): Future[Done] = {
val consumerConfig = system.settings.config.getConfig("akkafka.consumer.with-brokers")
val consumerSettings =
ConsumerSettings(consumerConfig, new StringDeserializer, new StringDeserializer)
.withGroupId(consumerGroup)
.withProperty(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest")
val committerConfig = system.settings.config.getConfig("akka.kafka.committer")
val committerSettings = CommitterSettings(committerConfig)
val table = "propertydata.property_listing"
val partitions = 10 // number of partitions
val statementBinder: (CommittableMessage[String, String], PreparedStatement) => BoundStatement = {
case (msg, preparedStatement) =>
val p = msg.record.value().parseJson.convertTo[PropertyListing]
preparedStatement.bind(
(p.propertyId % partitions).toString, Int.box(p.propertyId), p.dataSource.getOrElse("unknown"),
Double.box(p.bathrooms.getOrElse(0)), Int.box(p.bedrooms.getOrElse(0)), Double.box(p.listPrice.getOrElse(0)), Int.box(p.livingArea.getOrElse(0)),
p.propertyType.getOrElse(""), p.yearBuilt.getOrElse(""), p.lastUpdated.getOrElse(""), p.streetAddress.getOrElse(""), p.city.getOrElse(""), p.state.getOrElse(""), p.zip.getOrElse(""), p.country.getOrElse("")
)
}
val cassandraFlow: Flow[CommittableMessage[String, String], CommittableMessage[String, String], NotUsed] =
CassandraFlow.create(
CassandraWriteSettings.defaults,
s"""INSERT INTO $table (partition_key, property_id, data_source, bathrooms, bedrooms, list_price, living_area, property_type, year_built, last_updated, street_address, city, state, zip, country)
|VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""".stripMargin,
statementBinder
)
val control =
Consumer
.committableSource(consumerSettings, Subscriptions.topics(topic))
.via(cassandraFlow)
.map(_.committableOffset)
.toMat(Committer.sink(committerSettings))(DrainingControl.apply)
.run()
Thread.sleep(2000)
control.drainAndShutdown()
}
A couple of notes:
In order to be able to programmatically keep track of the commit offset positions, each of the stream elements emitted from Consumer.committableSource[K,V] is wrapped in a CommittableMessage[K,V] object, consisting of the CommittableOffset value in addition to the Kafka ConsumerRecord[K,V].
Committing the offset should be done after the stream data is processed for at-least-once consumption, whereas committing prior to processing the stream data would only achieve at-most-once delivery.
Adding a property-rating pipeline to the Alpakka Kafka consumer
Next, we add a data processing pipeline to the consumer to perform a number of ratings of the individual property listings in the stream before delivering the rated property listing data to the Cassandra database, as illustrated in the following diagram.
Since the CassandraFlow.create() stream operator will be executed after the rating pipeline, the corresponding “statement binder” necessary for class-variable/table-column binding will now need to encapsulate also PropertyRating along with CommittableMessage[K,V], as shown in the partial code of CassandraCommittableWithRatings.scala below.
def runPropertyListing(consumerGroup: String,
topic: String)(implicit
cassandraSession: CassandraSession,
jsonFormat: JsonFormat[PropertyListing],
system: ActorSystem,
ec: ExecutionContext): Future[Done] = {
val consumerConfig = system.settings.config.getConfig("akkafka.consumer.with-brokers")
val consumerSettings =
ConsumerSettings(consumerConfig, new StringDeserializer, new StringDeserializer)
.withGroupId(consumerGroup)
.withProperty(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest")
val committerConfig = system.settings.config.getConfig("akka.kafka.committer")
val committerSettings = CommitterSettings(committerConfig)
val table = "propertydata.rated_property_listing"
val partitions = 10 // number of partitions
val statementBinder: ((PropertyRating, CommittableMessage[String, String]), PreparedStatement) => BoundStatement = {
case ((rating, msg), preparedStatement) =>
val p = msg.record.value().parseJson.convertTo[PropertyListing]
preparedStatement.bind(
(p.propertyId % partitions).toString, Int.box(p.propertyId), p.dataSource.getOrElse("unknown"),
Double.box(p.bathrooms.getOrElse(0)), Int.box(p.bedrooms.getOrElse(0)), Double.box(p.listPrice.getOrElse(0)), Int.box(p.livingArea.getOrElse(0)),
p.propertyType.getOrElse(""), p.yearBuilt.getOrElse(""), p.lastUpdated.getOrElse(""), p.streetAddress.getOrElse(""), p.city.getOrElse(""), p.state.getOrElse(""), p.zip.getOrElse(""), p.country.getOrElse(""),
rating.affordability.getOrElse(0), rating.comfort.getOrElse(0), rating.neighborhood.getOrElse(0), rating.schools.getOrElse(0)
)
}
val cassandraFlow: Flow[(PropertyRating, CommittableMessage[String, String]), (PropertyRating, CommittableMessage[String, String]), NotUsed] =
CassandraFlow.create(
CassandraWriteSettings.defaults,
s"""INSERT INTO $table (partition_key, property_id, data_source, bathrooms, bedrooms, list_price, living_area, property_type, year_built, last_updated, street_address, city, state, zip, country, rating_affordability, rating_comfort, rating_neighborhood, rating_schools)
|VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""".stripMargin,
statementBinder
)
val control =
Consumer
.committableSource(consumerSettings, Subscriptions.topics(topic))
.via(PropertyRating.compute())
.via(cassandraFlow)
.map { case (_, msg) => msg.committableOffset }
.toMat(Committer.sink(committerSettings))(DrainingControl.apply)
.run()
Thread.sleep(2000)
control.drainAndShutdown()
}
For demonstration purpose, we create a dummy pipeline for rating of individual real estate properties in areas such as affordability, neighborhood, each returning just a Future of random integers between 1 and 5 after a random time delay. The rating related fields along with the computation logic are wrapped in class PropertyRating as shown below.
case class PropertyRating(
propertyId: Int,
affordability: Option[Int],
comfort: Option[Int],
neighborhood: Option[Int],
schools: Option[Int]
)
object PropertyRating {
def rand = java.util.concurrent.ThreadLocalRandom.current
def biasedRandNum(l: Int, u: Int, biasedNums: Set[Int], biasedFactor: Int = 1): Int = {
Vector
.iterate(rand.nextInt(l, u+1), biasedFactor)(_ => rand.nextInt(l, u+1))
.dropWhile(!biasedNums.contains(_))
.headOption match {
case Some(n) => n
case None => rand.nextInt(l, u+1)
}
}
def fakeRating()(implicit ec: ExecutionContext): Future[Int] = Future{ // Fake rating computation
Thread.sleep(biasedRandNum(1, 9, Set(3, 4, 5))) // Sleep 1-9 secs
biasedRandNum(1, 5, Set(2, 3, 4)) // Rating 1-5; mostly 2-4
}
def compute()(implicit ec: ExecutionContext): Flow[CommittableMessage[String, String], (PropertyRating, CommittableMessage[String, String]), NotUsed] =
Flow[CommittableMessage[String, String]].mapAsync(1){ msg =>
val propertyId = msg.record.key().toInt // let it crash in case of bad PK data
( for {
affordability <- PropertyRating.fakeRating()
comfort <- PropertyRating.fakeRating()
neighborhood <- PropertyRating.fakeRating()
schools <- PropertyRating.fakeRating()
}
yield new PropertyRating(propertyId, Option(affordability), Option(comfort), Option(neighborhood), Option(schools))
)
.map(rating => (rating, msg)).recover{ case e => throw new Exception("ERROR in computeRatingFlow()!") }
}
}
A Kafka consumer with a custom flow & stream destination
The application is also bundled with a consumer with the property rating pipeline followed by a custom flow to showcase how one can compose an arbitrary side-effecting operator with custom stream destination.
def customBusinessLogic(key: String, value: String, rating: PropertyRating)(
implicit ec: ExecutionContext): Future[Done] = Future {
println(s"KEY: $key VALUE: $value RATING: $rating")
// Perform custom business logic with key/value
// and save to an external storage, etc.
Done
}
def runPropertyListing(consumerGroup: String,
topic: String)(implicit
jsonFormat: JsonFormat[PropertyListing],
system: ActorSystem,
ec: ExecutionContext): Future[Done] = {
val consumerConfig = system.settings.config.getConfig("akkafka.consumer.with-brokers")
val consumerSettings =
ConsumerSettings(consumerConfig, new StringDeserializer, new StringDeserializer)
.withGroupId(consumerGroup)
.withProperty(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest")
val committerConfig = system.settings.config.getConfig("akka.kafka.committer")
val committerSettings = CommitterSettings(committerConfig)
val control =
Consumer
.committableSource(consumerSettings, Subscriptions.topics(topic))
.via(PropertyRating.compute())
.mapAsync(1) { case (rating, msg) =>
customBusinessLogic(msg.record.key, msg.record.value, rating)
.map(_ => msg.committableOffset)
}
.toMat(Committer.sink(committerSettings))(DrainingControl.apply)
.run()
Thread.sleep(5000)
control.drainAndShutdown()
}
Note that mapAsync is used to allow the stream transformation by the custom business logic to be carried out asynchronously.
Running the streaming ETL/pipelining system
To run the application that comes with sample real estate property listing data on a computer, go to the GitHub repo and follow the README instructions to launch the producers and consumers on one or more command-line terminals.
Also included in the README are instructions about how to run a couple of set queries to verify data that get ETL-ed to the Cassandra tables via Alpakka Cassandra’s CassandraSource which takes a CQL query as its argument.
Further enhancements
Depending on specific business requirement, the streaming ETL system can be further enhanced in a number of areas.
This streaming ETL system offers at-least-once delivery only in stream consumptions. If an end-to-end version is necessary, one could enhance the producers by using Producer.committabbleSink() or Producer.flexiFlow() instead of Producer.plainSink().
For exactly-once delivery, which is a generally much more stringent requirement, one approach to achieve that would be to atomically persist the in-flight data with the corresponding commit offset positions using a reliable storage system.
In case tracking of Kafka’s topic partition assignment is required, one can use Consumer.committablePartitionedSource[K,V] instead of Consumer.committableSource[K,V]. More details can be found in the tech doc.
To gracefully restart a stream on failure with a configurable backoff, Akka Stream provides method RestartSource.onFailuresWithBackoff for that as illustrated in an example in this tech doc.
In a previous startup I cofounded, our core product was a geospatial application that provided algorithmic ratings of the individual residential real estate properties for home buyers. Given that there were over 100+ millions of residential properties nationwide, the collective data volume of all the associated attributes necessary for the data engineering work was massive.
For the initial MVP (minimum viable product) releases in which we only needed to showcase our product features in a selected metropolitan area, we used PostgreSQL as the OLTP (online transaction processing) database. Leveraging Postgres’ table partitioning feature, we had an OLTP database capable of accommodating incremental geographical expansion into multiple cities and states.
Batch ETL
The need for a big data warehouse wasn’t imminent in the beginning, though we had to make sure a data processing platform for a highly scalable data warehouse along with efficient ETL (extract/transform/load) functions would be ready on a short notice. The main objective was to make sure the OLTP database could be kept at a minimal volume while less frequently used data got “archived” off to a big data warehouse for data analytics.
With limited engineering resources available in a small startup, I kicked off a R&D project on the side to build programmatic ETL processes to periodically funnel data from PostgreSQL to a big data warehouse in a batch manner. Cassandra was chosen to be the data warehouse and was configured on an Amazon EC2 cluster. The project was finished with a batch ETL solution that functionally worked as intended, although back in my mind a more “continuous” operational model would be preferred.
Real-time Streaming ETL
Fast-forward to 2021, I recently took on a big data streaming project that involves ETL and building data pipelines on a distributed platform. Central to the project requirement is real-time (or more precisely, near real-time) processing of high-volume data. Another aspect of the requirement is that the streaming system has to accommodate custom data pipelines as composable components of the consumers, suggesting that a streaming ETL solution would be more suitable than a batch one. Lastly, stream consumption needs to guarantee at-least-once delivery.
Given all that, Apache Kafka promptly stood out as a top candidate to serve as the distributed streaming brokers. In particular, its capability of keeping durable data in a distributed fault-tolerant cluster allows it to serve different consumers at various instances of time and locales. Next, Akka Stream was added to the tech stack for its versatile stream-based application integration functionality as well as benefits of reactive streams.
Alpakka – a reactive stream API and DSL
Built on top of Akka Stream, Alpakka provides a comprehensive API and DSL (domain specific language) for reactive and stream-oriented programming to address the application integration needs for interoperating with a wide range of prominent systems across various computing domains. That, coupled with the underlying Akka Stream’s versatile streaming functions, makes Alpakka a powerful toolkit for what is needed.
In this blog post, we’ll assemble in Scala a producer and a consumer using the Alpakka API to perform streaming ETL from a PostgreSQL database through Kafka brokers into a Cassandra data warehouse. In a subsequent post, we’ll enhance and package up these snippets to address the requirement of at-least-once delivery in consumption and composability of data pipelines.
Streaming ETL with Alpakka Kafka, Slick, Cassandra, …
The following diagram shows the near-real time ETL functional flow of data streaming from various kinds of data sources (e.g. a PostgreSQL database or a CSV file) to data destinations (e.g. a Cassandra data warehouse or a custom data stream outlet).
The Apache Kafka brokers provide a distributed publish-subscribe platform for keeping in-flight data in durable immutable logs readily available for consumption. Meanwhile, the Akka Stream based Alpakka API that comes with a DSL allows programmatic integrations to compose data pipelines as sources, sinks and flows, in addition to enabling “reactivity” by equipping the streams with non-blocking backpressure.
It should be noted that the same stream can be processed using various data sources and destinations simultaneously. For instance, data with the same schema from both the CSV file and Postgres database could be published to the same topic and consumed by a consumer group designated for the Cassandra database and another consumer group for a different data storage.
Example: ETL of real estate property listing data
The platform will be for general-purpose ETL/pipelining. For illustration purpose in this blog post, we’re going to use it to perform streaming ETL of some simplified dataset of residential real estate property listings.
First, we create a simple class to represent a property listing.
package alpakkafka
case class PropertyListing(
propertyId: Int,
dataSource: Option[String],
bathrooms: Option[Double],
bedrooms: Option[Int],
listPrice: Option[Double],
livingArea: Option[Int],
propertyType: Option[String],
yearBuilt: Option[String],
lastUpdated: Option[String],
streetAddress: Option[String],
city: Option[String],
state: Option[String],
zip: Option[String],
country: Option[String]
) {
def summary(): String = {
val ba = bathrooms.getOrElse(0)
val br = bedrooms.getOrElse(0)
val price = listPrice.getOrElse(0)
val area = livingArea.getOrElse(0)
val street = streetAddress.getOrElse("")
val cit = city.getOrElse("")
val sta = state.getOrElse("")
s"PropertyID: $propertyId | Price: $$$price ${br}BR/${ba}BA/${area}sqft | Address: $street, $cit, $sta"
}
}
Using the good old sbt as the build tool, relevant library dependencies for Akka Stream, Alpakka Kafka, Postgres/Slick and Cassandra/DataStax are included in build.sbt.
Note that the sample configuration is for running the application with all Kafka, PostgreSQL and Cassandra on a single computer. The host IPs (i.e. 127.0.0.1) should be replaced with their corresponding host IPs/names in case they’re on separate hosts. For example, relevant configurations for Kafka brokers and Cassandra database spanning across multiple hosts might look something like bootstrap.servers = "10.1.0.1:9092,10.1.0.2:9092,10.1.0.3:9092" and contact-points = ["10.2.0.1:9042","10.2.0.2:9042"].
PostgresProducerPlain – an Alpakka Kafka producer
The PostgresProducerPlain snippet below creates a Kafka producer using Alpakka Slick which allows SQL queries to be coded in Slick’s functional programming style.
package alpakkafka
import akka.actor.ActorSystem
import akka.stream.scaladsl._
import akka.{Done, NotUsed}
import akka.stream.alpakka.slick.scaladsl._
import akka.kafka.ProducerSettings
import akka.kafka.scaladsl.Producer
import org.apache.kafka.clients.producer.ProducerRecord
import org.apache.kafka.common.serialization.StringSerializer
import spray.json._
import spray.json.DefaultJsonProtocol._
import scala.concurrent.{ExecutionContext, Future}
import scala.util.Try
object PostgresProducerPlain {
def run(topic: String,
offset: Int = 0,
limit: Int = Int.MaxValue)(implicit
slickSession: SlickSession,
jsonFormat: JsonFormat[PropertyListing],
system: ActorSystem,
ec: ExecutionContext): Future[Done] = {
import slickSession.profile.api._
class PropertyListings(tag: Tag) extends Table[PropertyListing](tag, "property_listing") {
def propertyId = column[Int]("property_id", O.PrimaryKey)
def dataSource = column[Option[String]]("data_source")
def bathrooms = column[Option[Double]]("bathrooms")
def bedrooms = column[Option[Int]]("bedrooms")
def listPrice = column[Option[Double]]("list_price")
def livingArea = column[Option[Int]]("living_area")
def propertyType = column[Option[String]]("property_type")
def yearBuilt = column[Option[String]]("year_built")
def lastUpdated = column[Option[String]]("last_updated")
def streetAddress = column[Option[String]]("street_address")
def city = column[Option[String]]("city")
def state = column[Option[String]]("state")
def zip = column[Option[String]]("zip")
def country = column[Option[String]]("country")
def * =
(propertyId, dataSource, bathrooms, bedrooms, listPrice, livingArea, propertyType, yearBuilt, lastUpdated, streetAddress, city, state, zip, country) <> (PropertyListing.tupled, PropertyListing.unapply)
}
val source: Source[PropertyListing, NotUsed] =
Slick
.source(TableQuery[PropertyListings].sortBy(_.propertyId).drop(offset).take(limit).result)
val producerConfig = system.settings.config.getConfig("akkafka.producer.with-brokers")
val producerSettings =
ProducerSettings(producerConfig, new StringSerializer, new StringSerializer)
source
.map{ property =>
val prodRec = new ProducerRecord[String, String](
topic, property.propertyId.toString, property.toJson.compactPrint
)
println(s"[POSTRES] >>> Producer msg: $prodRec")
prodRec
}
.runWith(Producer.plainSink(producerSettings))
}
def main(args: Array[String]): Unit = {
implicit val system = ActorSystem()
implicit val ec = system.dispatcher
implicit val propertyListingJsonFormat: JsonFormat[PropertyListing] = jsonFormat14(PropertyListing)
implicit val slickSession = SlickSession.forConfig("slick-postgres")
val topic = "property-listing-topic"
val offset: Int = if (args.length >= 1) Try(args(0).toInt).getOrElse(0) else 0
val limit: Int = if (args.length == 2) Try(args(1).toInt).getOrElse(Int.MaxValue) else Int.MaxValue
run(topic, offset, limit) onComplete{ _ =>
slickSession.close()
system.terminate()
}
}
}
Method Slick.source[T]() takes a streaming query and returns a Source[T, NotUsed]. In this case, T is PropertyListing. Note that Slick.source() can also take a plain SQL statement wrapped within sql"..." as its argument, if wanted (in which case an implicit value of slick.jdbc.GetResult should be defined).
A subsequent map wraps each of the property listing objects in a ProducerRecord[K,V] with topic and key/value of type String/JSON, before publishing to the Kafka topic via Alpakka Kafka’s Producer.plainSink[K,V].
To run PostgresProducerPlain, simply navigate to the project root and execute the following command from within a command line terminal:
# sbt "runMain alpakkafka.PostgresProducerPlain "
# Stream the first 20 rows from property_listing in Postgres into Kafka under topic "property-listing"
sbt "runMain alpakkafka.PostgresProducerPlain 0 20"
# Stream all rows from property_listing in Postgres into Kafka under topic "property-listing"
sbt "runMain alpakkafka.PostgresProducerPlain"
CassandraConsumerPlain – an Alpakka Kafka consumer
Using Alpakka Kafka, CassandraConsumerPlain shows how a basic Kafka consumer can be formulated as an Akka stream that consumes data from Kafka via Consumer.plainSource followed by a stream processing operator, Alpakka Cassandra’s CassandraFlow to stream the data into a Cassandra database.
package alpakkafka
import akka.actor.ActorSystem
import akka.stream.scaladsl._
import akka.{Done, NotUsed}
import akka.kafka.{CommitterSettings, ConsumerSettings, Subscriptions}
import akka.kafka.scaladsl.{Committer, Consumer}
import akka.kafka.scaladsl.Consumer.DrainingControl
import org.apache.kafka.clients.consumer.{ConsumerConfig, ConsumerRecord}
import org.apache.kafka.common.serialization.StringDeserializer
import akka.stream.alpakka.cassandra.{CassandraSessionSettings, CassandraWriteSettings}
import akka.stream.alpakka.cassandra.scaladsl.{CassandraSession, CassandraSessionRegistry}
import akka.stream.alpakka.cassandra.scaladsl.{CassandraFlow, CassandraSource}
import com.datastax.oss.driver.api.core.cql.{BoundStatement, PreparedStatement}
import spray.json._
import spray.json.DefaultJsonProtocol._
import scala.concurrent.{ExecutionContext, Future}
import java.util.concurrent.atomic.AtomicReference
import scala.util.{Failure, Success, Try}
object CassandraConsumerPlain {
def run(consumerGroup: String,
topic: String)(implicit
cassandraSession: CassandraSession,
jsonFormat: JsonFormat[PropertyListing],
system: ActorSystem,
ec: ExecutionContext): Future[Done] = {
val consumerConfig = system.settings.config.getConfig("akkafka.consumer.with-brokers")
val consumerSettings =
ConsumerSettings(consumerConfig, new StringDeserializer, new StringDeserializer)
.withGroupId(consumerGroup)
.withProperty(ConsumerConfig.AUTO_OFFSET_RESET_CONFIG, "earliest")
val table = "propertydata.property_listing"
val partitions = 10 // number of partitions
val statementBinder: (ConsumerRecord[String, String], PreparedStatement) => BoundStatement = {
case (msg, preparedStatement) =>
val p = msg.value().parseJson.convertTo[PropertyListing]
preparedStatement.bind(
(p.propertyId % partitions).toString, Int.box(p.propertyId), p.dataSource.getOrElse("unknown"),
Double.box(p.bathrooms.getOrElse(0)), Int.box(p.bedrooms.getOrElse(0)), Double.box(p.listPrice.getOrElse(0)), Int.box(p.livingArea.getOrElse(0)),
p.propertyType.getOrElse(""), p.yearBuilt.getOrElse(""), p.lastUpdated.getOrElse(""), p.streetAddress.getOrElse(""), p.city.getOrElse(""), p.state.getOrElse(""), p.zip.getOrElse(""), p.country.getOrElse("")
)
}
val cassandraFlow: Flow[ConsumerRecord[String, String], ConsumerRecord[String, String], NotUsed] =
CassandraFlow.create(
CassandraWriteSettings.defaults,
s"""INSERT INTO $table (partition_key, property_id, data_source, bathrooms, bedrooms, list_price, living_area, property_type, year_built, last_updated, street_address, city, state, zip, country)
|VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""".stripMargin,
statementBinder
)
val control: DrainingControl[Done] =
Consumer
.plainSource(consumerSettings, Subscriptions.topics(topic))
.via(cassandraFlow)
.toMat(Sink.ignore)(DrainingControl.apply)
.run()
Thread.sleep(5000)
control.drainAndShutdown()
}
def query(sql: String)(implicit
cassandraSession: CassandraSession,
system: ActorSystem,
ec: ExecutionContext): Future[Seq[(String, PropertyListing)]] = {
CassandraSource(sql)
.map{ r =>
val partitionKey = r.getString("partition_key")
val propertyListingTuple = (
r.getInt("property_id"),
Option(r.getString("data_source")),
Option(r.getDouble("list_price")),
Option(r.getInt("bedrooms")),
Option(r.getDouble("bathrooms")),
Option(r.getInt("living_area")),
Option(r.getString("property_type")),
Option(r.getString("year_built")),
Option(r.getString("last_updated")),
Option(r.getString("street_address")),
Option(r.getString("city")),
Option(r.getString("state")),
Option(r.getString("zip")),
Option(r.getString("country"))
)
val propertyListing = PropertyListing.tupled(propertyListingTuple)
(partitionKey, propertyListing)
}
.runWith(Sink.seq)
}
def main(args: Array[String]): Unit = {
implicit val system = ActorSystem()
implicit val ec = system.dispatcher
implicit val propertyListingJsonFormat: JsonFormat[PropertyListing] = jsonFormat14(PropertyListing)
implicit val cassandraSession: CassandraSession =
CassandraSessionRegistry.get(system).sessionFor(CassandraSessionSettings())
val consumerGroup = "datawarehouse-consumer-group"
val topic = "property-listing-topic"
run(consumerGroup, topic) onComplete(println)
// Query for property listings within a Cassandra partition
val sql = s"SELECT * FROM propertydata.property_listing WHERE partition_key = '0';"
query(sql) onComplete {
case Success(res) => res.foreach(println)
case Failure(e) => println(s"ERROR: $e")
}
Thread.sleep(5000)
system.terminate()
}
}
A few notes:
Consumer.plainSource: As a first stab at building a consumer, we use Alpakka Kafka’s Consumer.plainSource[K,V] as the stream source. To ensure the stream to be stopped in a controlled fashion, Consumer.Drainingcontrol is included when composing the stream graph. While it’s straight forward to use, plainSource doesn’t offer programmatic tracking of the commit offset position thus cannot guarantee at-least-once delivery. An enhanced version of the consumer will be constructed in a subsequent blog post.
Partition key: Cassandra mandates having a partition key as part of the primary key of every table for distributing across cluster nodes. In our property listing data, we make the modulo of the Postgres primary key property_id by the number of partitions to be the partition key. It could certainly be redefined to something else (e.g. locale or type of the property) in accordance with the specific business requirement.
CassandraSource: Method query() simply executes queries against a Cassandra database using CassandraSource which takes a CQL query with syntax similar to standard SQL’s. It isn’t part of the consumer flow, but is rather as a convenient tool for verifying stream consumption result.
CassandraFlow: Alpakka’s CassandraFlow.create[S]() is the main processing operator responsible for streaming data into the Cassandra database. It takes a CQL PreparedStatement and a “statement binder” that binds the incoming class variables to the corresponding Cassandra columns before executing the insert/update. In this case, S is ConsumerRecord[K,V].
To run CassandraConsumerPlain, Navigate to the project root and execute the following from within a command line terminal:
# Stream any uncommitted data from Kafka topic "property-listing" into Cassandra
sbt "runMain alpakkafka.CassandraConsumerPlain"
Table schema in PostgreSQL & Cassandra
Obviously, the streaming ETL application is supposed to run in the presence of one or more Kafka brokers, a PostgreSQL database and a Cassandra data warehouse. For proof of concept, getting all these systems with basic configurations on a descent computer (Linux, Mac OS, etc) is a trivial exercise. The ETL application is readily scalable that it would require only configurative changes when, say, needs rise for scaling up of Kafka and Cassandra to span clusters of nodes in the cloud.
Below is how the table schema of property_listing can be created in PostgreSQL via psql:
CREATE ROLE pipeliner WITH createdb login ENCRYPTED PASSWORD 'pa$$word';
CREATE DATABASE propertydb WITH OWNER 'pipeliner' ENCODING 'utf8';
CREATE TABLE property_listing (
property_id integer PRIMARY KEY,
bathrooms numeric,
bedrooms integer,
list_price double precision,
living_area integer,
property_type text,
year_built text,
data_source text,
last_updated timestamp with time zone,
street_address character varying(250),
city character varying(50),
state character varying(50),
zip character varying(10),
country character varying(3)
);
ALTER TABLE property_listing OWNER TO pipeliner;
To create keyspace propertydata and the corresponding table property_listing in Cassandra, one can launch cqlsh and execute the following CQL statements:
CREATE KEYSPACE propertydata
WITH REPLICATION = {
'class' : 'SimpleStrategy', // use 'NetworkTopologyStrategy' for multi-node
'replication_factor' : 2 // use 'datacenter1' for multi-node
};
CREATE TABLE propertydata.property_listing (
partition_key text,
property_id int,
data_source text,
bathrooms double,
bedrooms int,
list_price double,
living_area int,
property_type text,
year_built text,
last_updated text,
street_address text,
city text,
state text,
zip text,
country text,
PRIMARY KEY ((partition_key), property_id)
);
What’s next?
So, we now have a basic streaming ETL system running Alphakka Kafka on top of a cluster of Kafka brokers to form the reactive stream “backbone” for near real-time ETL between data stores. With Alpakka Slick and Alpakka Cassandra, a relational database like PostgreSQL and a Cassandra data warehouse can be made part of the system like composable stream components.
As noted earlier, the existing Cassandra consumer does not guarantee at-least-once delivery, which is part of the requirement. In the next blog post, we’ll enhance the existing consumer to address the required delivery guarantee. We’ll also add a data processing pipeline to illustrate how to construct additional data pipelines as composable stream operators. All relevant source code along with some sample dataset will be published in a GitHub repo.