Skip to main content
Granularities determine how to bucket data across the time dimension - how to aggregate by hour, day, minute, etc., and how data is stored.
This document describes native query granularities. For SQL time functions, see SQL date and time functions.
Use granularities in: Specify granularity as:

​
Simple Granularities

Simple granularities are strings that bucket timestamps by UTC time (days start at 00:00 UTC). Supported granularities:
  • all - Single bucket for everything
  • none - Millisecond granularity (equivalent to internal index granularity)
  • second
  • minute
  • five_minute
  • ten_minute
  • fifteen_minute
  • thirty_minute
  • hour
  • six_hour
  • eight_hour
  • day
  • week
  • month
  • quarter
  • year
  • Don’t use none in timeseries queries - Druid fills empty interior buckets with zeroes, creating results for every millisecond
  • Avoid week for ingestion partitioning - weeks don’t align with months/years

​
Example Data

{"timestamp": "2013-08-31T01:02:33Z", "page": "AAA", "language": "en"}
{"timestamp": "2013-09-01T01:02:33Z", "page": "BBB", "language": "en"}
{"timestamp": "2013-09-02T23:32:45Z", "page": "CCC", "language": "en"}
{"timestamp": "2013-09-03T03:32:45Z", "page": "DDD", "language": "en"}

​
Hour Granularity Query

{
  "queryType": "groupBy",
  "dataSource": "my_dataSource",
  "granularity": "hour",
  "dimensions": ["language"],
  "aggregations": [{"type": "count", "name": "count"}],
  "intervals": ["2000-01-01T00:00Z/3000-01-01T00:00Z"]
}
Result: 
[
  {"version": "v1", "timestamp": "2013-08-31T01:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-01T01:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-02T23:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-03T03:00:00.000Z", "event": {"count": 1, "language": "en"}}
]

​
Day Granularity Query

{
  "queryType": "groupBy",
  "dataSource": "my_dataSource",
  "granularity": "day",
  "dimensions": ["language"],
  "aggregations": [{"type": "count", "name": "count"}],
  "intervals": ["2000-01-01T00:00Z/3000-01-01T00:00Z"]
}
Result: 
[
  {"version": "v1", "timestamp": "2013-08-31T00:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-01T00:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-02T00:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-03T00:00:00.000Z", "event": {"count": 1, "language": "en"}}
]

​
All Granularity Query

{
  "queryType": "groupBy",
  "dataSource": "my_dataSource",
  "granularity": "all",
  "dimensions": ["language"],
  "aggregations": [{"type": "count", "name": "count"}],
  "intervals": ["2000-01-01T00:00Z/3000-01-01T00:00Z"]
}
Result: 
[
  {"version": "v1", "timestamp": "2000-01-01T00:00:00.000Z", "event": {"count": 4, "language": "en"}}
]
Query time granularity smaller than ingestion queryGranularity produces results equivalent to the ingestion granularity, since finer detail isn’t stored in the data.

​
Duration Granularities

Duration granularities specify exact duration in milliseconds. Timestamps are returned as UTC. Basic duration: 
{"type": "duration", "duration": 7200000}
Chunks every 2 hours. Duration with origin: 
{"type": "duration", "duration": 3600000, "origin": "2012-01-01T00:30:00Z"}
Chunks every hour on the half-hour.
PropertyDescriptionRequired
typeMust be “duration”Yes
durationDuration in millisecondsYes
originStart counting from this timestampNo (defaults to 1970-01-01T00:00:00Z)

​
Example: 24-Hour Duration

{
  "queryType": "groupBy",
  "dataSource": "my_dataSource",
  "granularity": {"type": "duration", "duration": 86400000},
  "dimensions": ["language"],
  "aggregations": [{"type": "count", "name": "count"}],
  "intervals": ["2000-01-01T00:00Z/3000-01-01T00:00Z"]
}
Result: 
[
  {"version": "v1", "timestamp": "2013-08-31T00:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-01T00:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-02T00:00:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-03T00:00:00.000Z", "event": {"count": 1, "language": "en"}}
]

​
With Custom Origin

{"type": "duration", "duration": 86400000, "origin": "2012-01-01T00:30:00Z"}
Result - buckets start at :30 minutes: 
[
  {"version": "v1", "timestamp": "2013-08-31T00:30:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-01T00:30:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-02T00:30:00.000Z", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-03T00:30:00.000Z", "event": {"count": 1, "language": "en"}}
]

​
Period Granularities

Period granularities use ISO8601 period format (e.g., P2W, P3M, PT1H30M, PT0.750S). They support time zones which determine:
  • Where period boundaries start
  • Timezone of returned timestamps
Basic period: 
{"type": "period", "period": "P2D", "timeZone": "America/Los_Angeles"}
Buckets by 2-day chunks in Pacific timezone. Period with origin: 
{"type": "period", "period": "P3M", "timeZone": "America/Los_Angeles", "origin": "2012-02-01T00:00:00-08:00"}
Buckets by 3-month quarters starting from February.
PropertyDescriptionRequired
typeMust be “period”Yes
periodISO8601 period (e.g., P1D, PT1H)Yes
timeZoneTimezone (e.g., America/Los_Angeles)No (defaults to UTC)
originStart counting from this timestampNo (defaults to 1970-01-01T00:00:00 in timeZone)

​
Example: 1-Day Period in Pacific Time

{
  "queryType": "groupBy",
  "dataSource": "my_dataSource",
  "granularity": {"type": "period", "period": "P1D", "timeZone": "America/Los_Angeles"},
  "dimensions": ["language"],
  "aggregations": [{"type": "count", "name": "count"}],
  "intervals": ["1999-12-31T16:00:00.000-08:00/2999-12-31T16:00:00.000-08:00"]
}
Result - timestamps in Pacific time: 
[
  {"version": "v1", "timestamp": "2013-08-30T00:00:00.000-07:00", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-08-31T00:00:00.000-07:00", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-02T00:00:00.000-07:00", "event": {"count": 2, "language": "en"}}
]
Note: Rows at 2013-09-02T23:32:45Z and 2013-09-03T03:32:45Z are in the same bucket (same Pacific day).
The intervals in the query are NOT converted to the specified timezone. The timezone only affects result timestamps and bucketing.

​
With Custom Origin

{"type": "period", "period": "P1D", "timeZone": "America/Los_Angeles", "origin": "1970-01-01T20:30:00-08:00"}
Result - buckets start at 20:30: 
[
  {"version": "v1", "timestamp": "2013-08-29T20:30:00.000-07:00", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-08-30T20:30:00.000-07:00", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-01T20:30:00.000-07:00", "event": {"count": 1, "language": "en"}},
  {"version": "v1", "timestamp": "2013-09-02T20:30:00.000-07:00", "event": {"count": 1, "language": "en"}}
]
Origin only determines where to start the very first bucket - it doesn’t affect timezone behavior.

​
Supported Timezones

Druid uses Joda Time library with standard IANA timezones. See Joda Time supported timezones.

Build docs developers (and LLMs) love

Get started for freeTalk to us