What's new in 0.37.0 for Metabase driver authors

There is one change in Metabase 0.37.0 for Metabase drivers: we have made start of week settable in Metabase Admin rather than using whatever the underlying database uses. This means that for week-related datetime groupings (:week, :day-of-week, and week-of-year) we have to do some arithmetics to align them correctly. Implementing this change of behaviour is not mandatory, but highly recommended for consistency sake (the option to set start of week will be enabled irregardless of whether the drivers support it or not, potentially leading to confusion).

Changes are as follows:

New method metabase.driver/db-start-of-week

With the signature

(defmulti db-start-of-week  
  {:added "0.37.0" :arlists '([driver])}
  dispatch-on-initialized-driver
  :hierarchy #'hierarchy)

returning the day the DB considers start of week as a keyword: :monday, :tuesday, :wednesday, :thursday, :friday, :saturday, or :sunday.

Note: there is a limitation in the current implementation where we assume that all the DBs using the same driver have the same start of week. You can track developments around this in https://github.com/metabase/metabase/issues/13496.

If value returned is not a constant, we suggest you cache it as to not hit the DB needlessly.

week bucketing now adjusts start of week according to start-of-week setting

If you are using an SQL-derived driver, you can use sql.qp/adjust-start-of-week helper to transform the existing truncation function. In addition there is a driver-agnostic driver.common/start-of-week-offset which returns the shift in number of days needed to arrive at desired start of week. The offset is defined in such a way that adding the offset (modulo 7) to DB day of week will yield the adjusted day of week and assumes days of week being numbered 1-7.

day-of-week bucketing now adjusts day of week according to start-of-week setting

If you are using an SQL-derived driver, you can use sql.qp/adjust-day-of-week helper to transform the existing extractor function. In addition there is a driver-agnostic driver.common/start-of-week-offset which returns the shift in number of days needed to arrive at desired start of week. The offset is defined in such a way that adding the offset (modulo 7) to DB day of week will yield the adjusted day of week and assumes days of week being numbered 1-7.

sql.qp/date for week-of-year is now expressed in terms of other sql.qp/date truncations and does not need to be implemented explicitly

Note: this applies only to SQL-derived drivers.

Implementation notes

• You can get the start-of-week setting via (metabase.models.setting/get-keyword :start-of-week).