Announcing the preview of native support for custom calendars
Most of us live in a world aligned with the Gregorian calendar, where the year starts on January 1st, ends on December 31st and every four years, February has a 29th day. But in industries like Retail, what defines a month is not always the same when it comes to operating and analyzing business. To make working in a world with custom calendars easier, we are announcing the preview of native custom calendar support in Looker, enabling retailers and others to easily report on their data in the language their business speaks.
Time Isn’t Always Straightforward
In retail, for example, companies often follow one of the NRF standard calendars, like the 4-5-4, architected to cover 13 weeks, or a quarter year. In a 4-5-4 calendar, each quarter is broken into “months” or “periods” of 7-day weeks in the pattern of 4 weeks - 5 weeks - 4 weeks. This helps to facilitate consistent temporal analysis. Since holidays and promotional sales events, which have significant impact for most retailers, don’t necessarily fall on the same date every year, custom calendars help retailers compare similar activity in a reliable period-over-period fashion. They also help analysts align business operations like seasonal buying and labor planning because weeks, “months” (periods) and quarters all start on the same day of the week.
The 4-5-4 calendar is just one flavor. Some companies use a 4-4-5 calendar and some use a 5-4-4. Still others use a different iteration. But the end goal is the same: standardize periodic time comparisons.
A Win for LookML Developers and End Users
Supporting a custom calendar in Looker had previously required a significant amount of custom effort. Now, with native custom calendar support, LookML developers can save hours of development and maintenance by mapping their existing calendar table to Looker, and take advantage of native explore and dashboard filters.
How It Works
We’ve introduced a new LookML parameter, calendar_definition, which captures the mapping of your custom calendar to Looker’s Gregorian default.
Example:
Here, we create the custom calendar view. In this example, “fiscal_calendar_table” is the name of the existing calendar table in the data warehouse.
view: fiscal_calendar {
sql_table_name: your_dataset.fiscal_calendar_table ;; # The name of your custom calendar table
calendar_definition: {
reference_date: reference_date # The link to the Gregorian world
timeframe_mapping: { # String values
custom_year: fiscal_year_name # Custom Year Name: e.g., "FY2025"
custom_quarter: fiscal_q_name # Custom Quarter Name: e.g., "Q1"
custom_period: fiscal_p_name # Custom Month Name: e.g., "P01"
custom_week: fiscal_w_name # Custom Week Name: e.g., "W12"
}
timeframe_ordinal_mapping: { # Integer values
custom_year: fiscal_year_num # Custom Year Number: e.g., 2025
custom_quarter: fiscal_q_num # Custom Quarter Number: e.g., 1
custom_period: fiscal_p_num # Custom Month Number: e.g., 1
custom_week: fiscal_w_num # Custom Week Number: e.g., 12
}
}
dimension: reference_date {
type: date
primary_key: yes
sql: ${TABLE}.gregorian_date ;; # The field in the source table that represents a unique date
}
# ... other dimensions for the mappings above
}
We then have a fact view named orders and in this view, we’ll create a dimension group based on the custom calendar defined above.
We’ll also tell Looker that the created_at timestamp should be interpreted through the lens of that custom calendar.
include: "/views/fiscal_calendar.view"
view: orders {
sql_table_name: public.orders ;;
dimension_group: created {
type: custom_calendar # This tells Looker to use custom time periods vs. Gregorian defaults
sql: ${TABLE}.created_at ;;
based_on_calendar: fiscal_calendar # Implicit join to the custom calendar view
custom_timeframes: [custom_date, custom_week, custom_period, custom_year] # List of optional timeframes to include in the dimension group
}
# ... other dimensions and measures from the orders table
}
Looker automatically handles the complex joins and ordinal arithmetic behind the scenes. When a user filters for “Last 2 Custom Periods,” Looker knows exactly which rows to fetch based on your custom calendar mapping, even if that period spans across different Gregorian months.
Why This Matters
This isn’t just about making LookML cleaner, it’s about governed and trustworthy insights. When you standardize these calendar definitions in the semantic layer, you ensure that every user and AI agent is speaking the same language. No more manual table calculations as workarounds for calendar filters. No more misalignment of period-to-date reporting. You have a single, governed source of truth that accurately reflects how (and when) your business operates.
Call to Action
This feature is currently in Preview and we want you to try it for yourself.
How to get started:
- Ensure you’re connected to a database dialect that supports custom calendars.
- Make sure your instance is using the new LookML Runtime.
- Check out the official Custom Calendars Documentation for the full schema requirements.
Your feedback is encouraged. If you find a bug, have a suggestion, or just want to tell us how much you love what we’re doing, send us a note at looker-custom-calendars@google.com.