ankane / groupdate.sql

The simplest way to group temporal data

Groupdate.sql

The simplest way to group by:

• day
• week
• month
• day of the week
• hour of the day
• and more

🎉 Time zones supported!!

Supports PostgreSQL and MySQL

Installation

Run this SQL

• PostgreSQL
• MySQL

For MySQL, time zone support must be installed on the server.

mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

Getting Started

Groupdate.sql creates SQL functions, which are stored by the database. You can use these functions with any ORM or without one. Times stored in your database are assumed to be UTC (this is the default for frameworks like Rails).

Group by day

SELECT gd_day(created_at, 'America/Los_Angeles') AS day, COUNT(*) FROM users GROUP BY day;
-- result
    day     | count
------------+-------
 2013-04-11 |   145
 2013-04-12 |    65
 2013-04-13 |   293

Group by week

SELECT gd_week(created_at, 'America/Chicago') AS week, COUNT(*) FROM users GROUP BY week;
-- result
    week    | count
------------+-------
 2013-05-05 |  1327
 2013-05-12 |  3432
 2013-05-19 |   673

Weeks start on Sunday by default

Group by dynamic period

SELECT gd_period('day', created_at, 'America/Los_Angeles') AS period, COUNT(*) FROM users GROUP BY period;

Works with day, week, month, and year

Functions

Here’s the complete list of functions. All are prefixed with gd_ to prevent conflicts with MySQL functions.

• second
• minute
• hour
• day
• week
• month
• quarter
• year
• hour_of_day
• day_of_week
• day_of_month
• day_of_year
• month_of_year

A list of time zones can be found here.

Options

Time Zone

With PostgreSQL, the time zone is optional.

SELECT gd_day(created_at) AS day, COUNT(*) FROM users GROUP BY day;

The default is UTC. Change this to your preferred time zone by running:

CREATE OR REPLACE FUNCTION gd_time_zone()
  RETURNS text AS
$$
  SELECT 'America/Los_Angeles'::text;
$$
  LANGUAGE SQL IMMUTABLE;

Week Start

Set the day weeks start. The default is Sunday.

For PostgreSQL, run:

CREATE OR REPLACE FUNCTION gd_week_start()
  RETURNS int AS
$$
  SELECT 6; -- mon=0, tue=1, wed=2, thu=3, fri=4, sat=5, sun=6
$$
  LANGUAGE SQL IMMUTABLE;

For MySQL, run:

START TRANSACTION;

DROP FUNCTION IF EXISTS gd_week_start;
CREATE FUNCTION gd_week_start()
  RETURNS INT DETERMINISTIC
  RETURN 6; -- mon=0, tue=1, wed=2, thu=3, fri=4, sat=5, sun=6

COMMIT;

Uninstall

Run this SQL

• PostgreSQL
• MySQL

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

groupdate.sql's Issues

Windows Error

I apologize for asking this question as I'm on a Windows machine. I've installed this on my Macbook and it works brilliantly. But I'm having issues with Windows.

When running

$curl https://raw.github.com/ankane/groupdate.sql/master/mysql.sql | mysql [db_name]

I receive the following error

ERROR 1064 (42000) at line 1: You have an error in your SQL syntax; check the manual that corresponds to your MySQL server version for the right syntax to use near 'HTTP/1.1 200 OK
Date: Sun, 18 Aug 2013 08:31:01 GMT
Server: GitHub.com
Content-T at line 1

Add gd_version function

To make it easy to tell which version is installed.

Add volatility classification

http://www.postgresql.org/docs/9.2/static/xfunc-volatility.html

Add N minute intervals

Grouping by 5, 10, 15 and 30 minute intervals would be nice

Create uninstaller

To remove functions

Question about use of timezone function

Thank you for all these very useful udf's here (including the recent gd_quarter function too 🎉)

This might be a stupid question but I failed to see through the reason why we used CONVERT_TZ twice here for some of the functions. for ex:

CONVERT_TZ(DATE_FORMAT(CONVERT_TZ(ts, '+00:00', time_zone), '%Y-%m-%d 00:00:00'), time_zone, '+00:00');

once to convert timestamp to a desired timezone only to convert it back to UTC.