groupdate

# Groupdate

The simplest way to group by:

- day
- week
- hour of the day
- and more (complete list below)

:tada: Time zones - including daylight saving time - supported!! **the best part**

:cake: Get the entire series - **the other best part**

Supports PostgreSQL, MySQL, MariaDB, SQLite, and Redshift, plus arrays and hashes

:cupid: Goes hand in hand with [Chartkick](https://www.chartkick.com)

[![Build Status](https://github.com/ankane/groupdate/actions/workflows/build.yml/badge.svg)](https://github.com/ankane/groupdate/actions)

## Installation

Add this line to your application’s Gemfile:

```ruby
gem "groupdate"
```

For MySQL and MariaDB, also follow [these instructions](#additional-instructions).

## Getting Started

```ruby
User.group_by_day(:created_at).count
# {
#   Thu, 01 Jan 2026 => 50,
#   Fri, 02 Jan 2026 => 100,
#   Sat, 03 Jan 2026 => 34
# }
```

Results are returned in ascending order by default, so no need to sort.

You can group by:

- second
- minute
- hour
- day
- week
- month
- quarter
- year

and

- minute_of_hour
- hour_of_day
- day_of_week (Sunday = 0, Monday = 1, etc)
- day_of_month
- day_of_year
- month_of_year

Use it anywhere you can use `group`. Works with `count`, `sum`, `minimum`, `maximum`, and `average`. For `median` and `percentile`, check out [ActiveMedian](https://github.com/ankane/active_median).

### Time Zones

The default time zone is `Time.zone`.  Change this with:

```ruby
Groupdate.time_zone = "Pacific Time (US & Canada)"
```

or

```ruby
User.group_by_week(:created_at, time_zone: "Pacific Time (US & Canada)").count
# {
#   Sun, 04 Jan 2026 => 70,
#   Sun, 11 Jan 2026 => 54,
#   Sun, 18 Jan 2026 => 80
# }
```

Time zone objects also work. To see a list of available time zones in Rails, run `rake time:zones:all`.

### Week Start

Weeks start on Sunday by default. Change this with:

```ruby
Groupdate.week_start = :monday
```

or

```ruby
User.group_by_week(:created_at, week_start: :monday).count
```

### Day Start

You can change the hour days start with:

```ruby
Groupdate.day_start = 2 # 2 am - 2 am
```

or

```ruby
User.group_by_day(:created_at, day_start: 2).count
```

### Time Range

To get a specific time range, use:

```ruby
User.group_by_day(:created_at, range: 2.weeks.ago.midnight..Time.now).count
```

To expand the range to the start and end of the time period, use:

```ruby
User.group_by_day(:created_at, range: 2.weeks.ago..Time.now, expand_range: true).count
```

To get the most recent time periods, use:

```ruby
User.group_by_week(:created_at, last: 8).count # last 8 weeks
```

To exclude the current period, use:

```ruby
User.group_by_week(:created_at, last: 8, current: false).count
```

### Order

You can order in descending order with:

```ruby
User.group_by_day(:created_at, reverse: true).count
```

### Keys

Keys are returned as date or time objects for the start of the period.

To get keys in a different format, use:

```ruby
User.group_by_month(:created_at, format: "%b %Y").count