Ruby client for Druid
#3 Compare This branch is 56 commits ahead, 6 commits behind liquidm:master.
Latest commit 74bc05e Oct 17, 2016 @hollow hollow committed on GitHub Merge pull request #5 from ruby-druid/fix-group-by-dimension-handling
add backwards compatibility for group_by queries.
Failed to load latest commit information.
lib add backwards compatibility Oct 17, 2016
.gitignore add pkg to gitignore Jul 18, 2016
.travis.yml use ruby 2.2.2 for travis Jul 18, 2016
LICENSE readme update for repo location Jul 18, 2016
Rakefile add bundler gem tasks Jul 18, 2016


A Ruby client for Druid. Includes a Squeel-like query DSL and generates a JSON query that can be sent to Druid directly.

Gem Version Build Status Code Climate Dependency Status


Add this line to your application's Gemfile:

gem 'ruby-druid'

And then execute:


Or install it yourself as:

gem install ruby-druid


returns a query object on which all other methods can be called to create a full and valid Druid query.

A query object can be sent like this:

client ='zk1:2181,zk2:2181/druid')
query ='service/source')

The send method returns the parsed response from the druid server as an array. If the response is not empty it contains one ResponseRow object for each row. The timestamp by can be received by a method with the same name (i.e. row.timestamp), all row values by hashlike syntax (i.e. `row['dimension'])

An options hash can be passed when creating Druid::Client instance:

client ='zk1:2181,zk2:2181/druid', http_timeout: 20)

Supported options are:

  • static_setup to explicitly specify a broker url, e.g. static_setup: { 'my/source_name' => '' }
  • http_timeout to define a timeout for sending http queries to a broker (in minutes, default value is 2)


A GroupByQuery sets the dimensions to group the data.

queryType is set automatically to groupBy.'service/source').group_by([:dimension1, :dimension2])


A TimeSeriesQuery returns an array of JSON objects where each object represents a value asked for by the timeseries query.'service/source').time_series([:aggregate1, :aggregate2])


longSum, doubleSum, count, min, max, hyperUnique'service/source').long_sum([:aggregate1, :aggregate2])

In the same way could be used the following methods for aggregations adding: double_sum, count, min, max, hyper_unique

cardinality'service/source').cardinality(:aggregate, [:dimension1, dimension2], <by_row: true | false>)


For example calculation for sum(log(x)/y) + 10:'service/source').js_aggregation(:aggregate, [:x, :y],
  aggregate: "function(current, a, b)      { return current + (Math.log(a) * b); }",
  combine:   "function(partialA, partialB) { return partialA + partialB; }",
  reset:     "function()                   { return 10; }"

Post Aggregations

A simple syntax for post aggregations with +,-,/,* can be used like:

query ='service/source').long_sum([:aggregate1, :aggregate2])
query.postagg { (aggregate2 + aggregate2).as output_field_name }

Required fields for the postaggregation are fetched automatically by the library.

Javascript post aggregations are also supported:

query.postagg { js('function(aggregate1, aggregate2) { return aggregate1 + aggregate2; }').as result }

Query Interval

The interval for the query takes a string with date and time or objects that provide an iso8601 method.

query ='service/source').long_sum(:aggregate1)

Result Granularity

The granularity can be :all, :none, :minute, :fifteen_minute, :thirthy_minute, :hour or :day.

It can also be a period granularity as described in the Druid documentation.

The period 'day' or :day will be interpreted as 'P1D'.

If a period granularity is specifed, the (optional) second parameter is a time zone. It defaults to the machines local time zone. i.e.

query ='service/source').long_sum(:aggregate1)

is (on my box) the same as

query ='service/source').long_sum(:aggregate1)
query.granularity('P1D', 'Europe/Berlin')

Having filters

# equality'service/source').having { metric == 10 }
# inequality'service/source').having { metric != 10 }
# greater, less'service/source').having { metric > 10 }'service/source').having { metric < 10 }

Compound having filters

Having filters can be combined with boolean logic.

# and'service/source').having { (metric != 1) & (metric2 != 2) }
# or'service/source').having { (metric == 1) | (metric2 == 2) }
# not'service/source').having{ !metric.eq(1) }


Filters are set by the filter method. It takes a block or a hash as parameter.

Filters can be chained filter{...}.filter{...}

Base Filters

# equality'service/source').filter{dimension.eq 1}'service/source').filter{dimension == 1}
# inequality'service/source').filter{dimension.neq 1}'service/source').filter{dimension != 1}
# greater, less'service/source').filter{dimension > 1}'service/source').filter{dimension >= 1}'service/source').filter{dimension < 1}'service/source').filter{dimension <= 1}
# JavaScript'service/source').filter{a.javascript('dimension >= 1 && dimension < 5')}

Compound Filters

Filters can be combined with boolean logic.

# and'service/source').filter{dimension.neq 1 & dimension2.neq 2}
# or'service/source').filter{dimension.neq 1 | dimension2.neq 2}
# not'service/source').filter{!dimension.eq(1)}

Inclusion Filter

This filter creates a set of equals filters in an or filter.'service/source').filter{,2,3)}

Geographic filter

These filters have to be combined with time_series and do only work when coordinates is a spatial dimension GeographicQueries'service/source').time_series().long_sum([:aggregate1]).filter{coordinates.in_rec [[50.0,13.0],[54.0,15.0]]}'service/source').time_series().long_sum([:aggregate1]).filter{coordinates.in_circ [[53.0,13.0], 5.0]}

Exclusion Filter

This filter creates a set of not-equals fitlers in an and filter.'service/source').filter{dimension.nin(1,2,3)}

Hash syntax

Sometimes it can be useful to use a hash syntax for filtering for example if you already get them from a list or parameter hash.'service/source').filter{dimension => 1, dimension1 =>2, dimension2 => 3}
# which is equivalent to'service/source').filter{dimension.eq(1) & dimension1.eq(2) & dimension2.eq(3)}


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request