Supercharging Internet UIs with Druid Databases

Getting ready and ingesting Druid databases from Delta Lake tables on Amazon’s S3 cloud – the nuances you want to know. 

On my group at ZipRecruiter we handle the net BI reporting dashboards for 1000’s of enterprise employers and businesses. Our internet UI (Fig. 1) offers these companies with necessary Information about job seeker engagement with their open positions utilizing comparative graphs, traits and statistics to narrate funds and spend to views, clicks and applies. 

In our preliminary model, knowledge got here from MySQL DBs which weren’t very nicely optimized for the use case. Because of this, the dashboards would incessantly fail to load or crash, significantly when trying to tug massive chunks of information over very long time ranges. 

Fig. 1: Instance our web-based employer BI dashboard

After some investigation, we determined to transform these databases to Druid, which utterly revolutionized the dashboards’ efficiency and person expertise. Determine 2 reveals load instances for a few of the pages in our dashboard. Though that is your entire HTTP request and never simply the database question, IT nonetheless displays how nicely these pages are working. The pink line within the center denotes the day we switched from MySQL on the left to Druid on the precise. Loading turned rather more steady and constant, permitting us to deal with all kinds of information and nonetheless return a response in an affordable period of time. What’s extra, as soon as we switched to Druid, the necessity to cancel web page requests and queries working over our time restrict has been practically eradicated (Fig. 3).

On this article I’ll cowl the important thing points of Druid related to one of these use case and clarify the nuances of prepping and ingesting your knowledge into Druid from Delta Lake. 

Fig. 2: Stabilized and constant load instances after switching from MySQL to Druid
Fig. 3: After switching to Druid, web page request cancellations turned a factor of the previous

Druid is optimized for time sequence aggregations 

Druid is a distributed database optimized for aggregations over time sequence knowledge. IT does this quick sufficient to be appropriate for real-time user-facing workloads, like an internet UI dashboard.

‘Time sequence knowledge’ refers to occasions or observations occurring over successive time situations. A single occasion, resembling a click on, apply, or web page view can have a number of identifier attributes (like click on ID and marketing campaign ID), person particular attributes (like an IP tackle) and a full-resolution timestamp (date, minute, seconds and so forth). As this knowledge accumulates over time, the database will get greater and greater. 

‘Aggregations’ confer with a manipulation or mixture of uncooked occasion knowledge over a sure vary into a worth that’s extra helpful and insightful. For instance, one sort of aggregation are ratios like ‘impressions per placement by day’ or ‘job titles per location’. Aggregations additionally embody calculations like sums, averages, or percentages; for instance, ‘complete applies throughout a particular week in a marketing campaign’ or ‘the proportion of applies from complete views’. In dashboards and queries, these aggregations or ‘rollups’ are quite common.

Whereas Druid is nicely suited to storing uncooked occasion knowledge and aggregating in real-time, for this mission we selected to ingest pre-aggregated knowledge into Druid. We already had a system, constructed utilizing Scala on Spark, that aggregates and denormalizes income knowledge, together with knowledge from different programs, into tables optimized for reporting, after which saves them utilizing Delta. Ingesting these current tables into Druid signifies that we are able to select which database is finest suited to every use-case (Druid for real-time, Delta for batch) whereas utilizing the identical acquainted schema. IT additionally overcomes Druid’s largest limitation: Joins.

Druid can solely ingest and retailer the information that you simply feed to IT. This implies IT can’t actively acquire or mix what IT has with different knowledge from different sources (apart from restricted lookup operations). What’s extra, in favor of effectivity, Druid has restricted assist for joins in the meanwhile and prefers that your whole knowledge be denormalized and merged previous to ingestion. 

Now that we perceive what Druid is finest fitted to, let’s roll up our sleeves and convey Druid into the world of Delta Lake and S3 cloud storage. 

Pointing Druid to the latest Parquet file in Delta Lake

Earlier than we are able to begin ingesting our knowledge, we have to perceive slightly bit about Delta Lake. On this context, consider Delta Lake as a layer of partitioning and metadata on high of Parquet information which can be saved in S3 (or different object storage). Though Druid can simply learn Parquet information, IT isn’t geared up to learn the metadata or handle the partitions that Delta Lake creates. To level Druid to the precise knowledge we want to use requires a fundamental understanding of Delta desk structuring.

Inside a selected S3 bucket, and a selected desk path, you will see that a listing of partitions. Inside these partitions are the Parquet information (Fig. 4). 

Fig. 4: Discovering the trail to the latest parquet file in every partition

The primary problem is that the partition column worth is saved within the S3 path itself and never really saved in any respect within the Parquet file. When Druid reads a Parquet file, IT gained’t have entry to this column worth.

The second problem is that there could be a number of Parquet information in a single partition. This may occur for 2 causes. Delta will cut up a partition into a number of information if the quantity of information in IT turns into too massive. As well as, Delta saves outdated variations of information till you vacuum them. We, for instance, have a course of that runs each hour, reprocessing knowledge from the prior 24–48 hours, and overwrites the outdated partitions. Each hour a brand new, more energizing file is created. This leads to new parquet information being created each hour. 

To seek out the latest Parquet file(s) observe the _symlink_format_manifest/ path into the related partition. There you’ll discover a single manifest file which lists S3 paths for the most recent parquet file(s).

Timestamps are essential for ingesting knowledge

Druid helps a restricted set of information sorts which embody longs, floats, doubles and strings in addition to  some “complicated” statistical approximation sorts. Most significantly, for the aim of efficiently working with Druid, are timestamps (saved as Unix epoch milliseconds) and a particular timestamp referred to as __time.

As a result of Druid is optimized for time sequence knowledge, each single desk in Druid should have a __time column. That is essential. If Druid can’t discover a worth for the __time column, IT won’t ingest your knowledge. 

So, what column can we use for the __time? If we have been ingesting uncooked occasion knowledge, we might have an “occasion time” timestamp that we naturally map to Druid’s idea of __time. Nevertheless, we’re ingesting aggregated knowledge and the occasion time is the dimension that we have now aggregated right into a easy date. This column can be our partition column which, as beforehand talked about, isn’t out there within the parquet file. As a result of Druid isn’t going to have the ability to learn the partition column, earlier than writing the information we duplicate the partition column in order that IT can be saved within the parquet. Druid can discover this duplicate copy of the column when IT reads the parquet file. Throughout our implementation and roll-out, we’ve discovered that this answer has some downsides. The duplicate column could cause confusion and IT signifies that current knowledge, with out the duplicate column, can’t be ingested as-is. An alternate answer is mentioned later.

Time intervals in Druid

Most queries in Druid can be filtering your knowledge utilizing an interval between two moments in time. Intervals are additionally used throughout ingestion. Druid makes use of the ISO-8601 time interval format, made up of start-time/end-time, the place the start-time is inclusive, however the end-time is unique; which means the end-time isn’t included within the vary. That is helpful for capturing complete months. By selecting the primary day of the following month because the end-time you possibly can make sure you don’t miss that pesky thirty first… or was IT thirtieth? 

One other helpful Druid shortcut pertains to intervals. As a substitute of a particular end-date, we are able to describe a period utilizing ISO 8601 period illustration: P1M for ‘interval one month’ or PT1H for ‘time frame one hour’. For instance, 2023-07-01/P1M or 2023-07-01T12:00:00Z/PT1H.

Getting Knowledge into Druid – Batch vs Stream Ingestion

To ingest knowledge, Druid makes use of ‘append’ or ‘exchange’ strategies, quite than ‘insert’ and ‘replace’. For instance, IT is feasible via batch ingestion to interchange the information for a sure month with a brand new set of information. As a result of Druid doesn’t have any form of scheduler, after we wish to set off an ingestion we sometimes use the Apache Airflow knowledge pipeline orchestrator. 

An alternative choice is stream ingestion, implementable with Kafka, for instance. We determined to not use stream ingestion, primarily as a result of Druid would solely have the information that’s on the stream, which means IT wouldn’t be denormalized nor enriched except we did dwell stream enrichments. 

Writing a Druid ingestion spec in JSON

An ‘ingestion spec’ is a JSON file that tells Druid the place your knowledge is, what IT seems like and easy methods to retailer IT. Here’s a typical fundamental model (explanations observe):

{ "type": "index_parallel",
 "spec": {
   "ioConfig": {
     "type": "index_parallel",
     "inputSource": {
       "type": "s3",
       "uris": [ "s3://bucket/path/file.parquet" ]
     "inputFormat": {
       "sort": "parquet",
       "binaryAsString": false
     "appendToExisting": false,
     "dropExisting": true
   "tuningConfig": {
     "sort": "index_parallel",
     "partitionsSpec": {
       "sort": "dynamic"
     "maxNumConcurrentSubTasks": 100,
     "maxRetry": 10
   "dataSchema": {
     "dataSource": "agg_flight_revenue_by_day",
     "granularitySpec": {
       "queryGranularity": "day",
       "rollup": false,
       "segmentGranularity": "day"
     "timestampSpec": {
       "column": "_druid_time",
       "format": "auto"
     "transformSpec": {
       "transforms": [
           "type": "expression",
           "name": "is_open_flight",
           "expression": "if(is_open_flight == 'true', 1, 0)"
     "dimensionsSpec": {
       "dimensions": [
           "name" : "campaign_id",
           "type" : "long"
           "name" : "flight_start_date",
           "type" : "long"
           "name" : "daily_click_rev_usd",
           "type" : "double"
           "name" : "currency_code",
           "type" : "string"
  • appendToExisting and dropExisting are set in a particular way that makes sense for our use-case, where, every hour we replace the entire data for the day. Depending on what your data processing is like, adjust those accordingly.
  • dataSource defines our table. Note that Druid doesn’t have a concept similar to schema – everything is in one big database. So, be careful to name your tables reasonably so as not to interfere with others sharing your cluster. 
  • The granularitySpec section refers to the way that the data is stored. If you have data that’s getting updated every hour and you’re confident you’ll never query at minute resolution, you can optimize a little bit and store by the hour or day etc.
  • timestampSpec is the crucial __time column mentioned earlier. Here you point to the time column which is the duplicate of our partition column.
  • transformSpec is where we prepare or manipulate data for Druid. In this example we had a boolean column when Druid doesn’t support boolean. We simply translate IT from ‘true’ or ‘false’ strings into 1 and 0, accordingly. To learn more about Druid expression language, refer to the documentation which is pretty straightforward. 
  • dimensionsSpec is where we get into our actual columns, our dimensions, specifying the name of the dimension and the type one by one. 

Triggering a Druid ingestion event in Python

Without going into all the details, here are the key parts of the API (don’t blindly copy-paste this)

import boto3
import json
import urllib.request
from datetime import datetime

# Assume we're loading knowledge for in the present day
date ='%Y-%m-%d')

druid_host = 'http://localhost:8888'

json_spec = 'path_to/ingestion_specs/tablename.json'

s3_bucket = 'bucket_name'
manifest_path = f'table_path/_symlink_format_manifest/partition={date}/manifest'

# Learn manifest file from S3
shopper = boto3.shopper('s3')
response = shopper.get_object(Bucket=s3_bucket, Key=manifest_path)
manifest = response["Body"].learn().decode("utf-8")
paths = manifest.rstrip().cut up('n')

# Learn in our ingestion spec json
with open(json_spec, 'r') as f:
   contents = f.learn()
   spec = json.hundreds(contents)

# Fill within the path to our S3 parquet information
spec["spec"]["ioConfig"]["inputSource"]["uris"] = paths
# Inform Druid we wish to overwrite the information for in the present day's partition
spec["spec"]["dataSchema"]["granularitySpec"]["intervals"] = [ f"{date}/P1D" ]
# If a time column isn't out there within the parquet, Druid will use this worth
spec["spec"]["dataSchema"]["timestampSpec"]["missingValue"] = date

req = urllib.request.Request(f'{druid_host}/druid/indexer/v1/job',
                            {'Content material-Kind' : 'software/json'})

# Add person/cross to fundamental auth headers if wanted

# Submit the ingestion request
response = urllib.request.urlopen(req)
# You can too parse the response if you wish to examine the standing of the duty

First we hook up with S3 to learn the textual content contents of that manifest file. Then we merely cut up that by line to get a listing of S3 paths for the parquet information we wish to ingest. 

Subsequent, we parse the json ingestion file that we wrote earlier. Now, we are able to insert the up to date values which can be particular to the partition we wish to ingest. The checklist of parquet URIs is used for our inputSource and we specify an interval, for in the present day, telling Druid what vary of information we wish to overwrite.

And right here comes the essential one, the timestampSpec/missingValue. Within the case the place Druid can’t discover a timestamp column in your knowledge, as an alternative of failing the ingestion, we instruct IT to make use of the date we offer right here. This answer works nicely when processing one partition at a time and also you don’t wish to have the aforementioned duplicated column. 

Lastly, we are able to POST the up to date json ingestion spec to the suitable API on our Druid host.

Checking ingestion standing with task_id

Druid’s ingestion operate instantly returns a task_id which we are able to use to examine the ingestion standing. Duties are often surprisingly quick, however when you’ve got a lot of knowledge IT might take a couple of minutes. By pulling the Batch Ingestion API and querying the standing of the task_id you’ll be capable to see when a job completed and whether or not IT was profitable or not. 

General we have now discovered Druid to be extraordinarily handy, quick and dependable for managing our personal exploration queries in addition to these of our clients via the online UI. 

Should you’re considering engaged on options like these, go to our Careers web page to see open roles.

* * *

Concerning the Creator

Stuart Johnston is a Senior Software program Engineer at ZipRecruiter. Presently on the Enterprise Efficiency Advertising group, he builds and maintains the databases that assist employers handle their recruitment campaigns by way of refined internet UIs. Throughout the previous 8 years on the firm Stuart has had the chance to design and ship logging programs, APIs and monitoring instruments for all kinds of inner and exterior stakeholders. Being a part of a tight-knit group of elite engineers offering employment alternatives to anybody, wherever is what retains Stuart fueled with ardour and a way of function each day.

Leave a Comment

Your email address will not be published. Required fields are marked *

Scroll to Top