Add custom date granularities documentation

Generated-By: mintlify-agent

Author: mintlify[bot]

references/dimensions.mdx

@@ -157,7 +157,7 @@ The table below shows all the dimension properties you can customize:
 | [type](#type) | No  | Dimension type | The dimension type is automatically pulled from your table schemas in Lightdash but you can override the type using this property. |
 | [description](#description) | No    | string | Description of the dimension in Lightdash. You can use this to override the description you have for the dimension in dbt. |
 | sql | No            | string | Custom SQL applied to the column used to define the dimension. |
-| [time_intervals](#time-intervals) | No | 'default' or OFF or an array[] containing elements of [date](#date-options), [numeric](#numeric-options) or [string](#string-options) options | 'default' (or not setting the time_intervals property) will be converted into ['DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR'] for dates and ['RAW', 'DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR'] for timestamps; if you want no time intervals set 'OFF'. |
+| [time_intervals](#time-intervals) | No | 'default' or OFF or an array[] containing elements of [date](#date-options), [numeric](#numeric-options), [string](#string-options) options, or [custom granularity](#using-custom-granularities) names | 'default' (or not setting the time_intervals property) will be converted into ['DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR'] for dates and ['RAW', 'DAY', 'WEEK', 'MONTH', 'QUARTER', 'YEAR'] for timestamps; if you want no time intervals set 'OFF'. You can also include custom granularity names defined in `lightdash.config.yml`. |
 | hidden | No       | boolean | If set to true, the dimension is hidden from Lightdash. By default, this is set to false if you don't include this property. Hidden dimensions are also excluded from drilldowns (View underlying data). |
 | [compact](#compact) | No     | string | This option will compact the number value (e.g. 1,500 to 1.50K). Currently supports one of the following: ['thousands', 'millions', 'billions', 'trillions', 'kilobytes', 'megabytes', 'gigabytes', 'terabytes', 'petabytes', 'kibibytes', 'mebibytes', 'gibibytes', 'tebibytes', 'pebibytes'] |
 | [format](#format) | No       | string | This option will format the output value on the results table and CSV export. Supports spreadsheet-style formatting (e.g. #,##0.00). Use [this website](https://customformats.com) to help build your custom format. |
@@ -677,9 +677,67 @@ You can see all of the standard interval options for date and timestamp fields b
 | QUARTER_NAME     | Quarter name    | String | Q3              |
 
 
-### Custom time intervals
+### Using custom granularities
 
-You can set custom versions of time intervals by using additional dimensions and groups. Here's an example of how that might look if you wanted to add `year_of_week_iso` to your drop down list for the `delivery_date` dimension. Note that by definiting the `groups:` option, we ensure that the new "Year of week" options is displayed as expected.
+You can define reusable custom time granularities in your `lightdash.config.yml` file and reference them in the `time_intervals` array. Custom granularities appear in the date zoom dropdown alongside standard options.
+
+**Step 1**: Define custom granularities in `lightdash.config.yml`:
+
+```yaml
+# lightdash.config.yml
+custom_granularities:
+  fiscal_quarter:
+    label: "Fiscal Quarter"
+    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
+  week_monday:
+    label: "Week (Mon-Sun)"
+    sql: "DATE_TRUNC('week', ${COLUMN})"
+```
+
+**Step 2**: Reference them in your dimension's `time_intervals`:
+
+<Tabs>
+  <Tab title="dbt v1.9 and earlier">
+    ```yaml
+    - name: order_date
+      description: 'Date the order was placed'
+      meta:
+        dimension:
+          type: date
+          time_intervals: ['DAY', 'WEEK', 'fiscal_quarter', 'YEAR']
+    ```
+  </Tab>
+  <Tab title="dbt v1.10+ and Fusion">
+    ```yaml
+    - name: order_date
+      description: 'Date the order was placed'
+      config:
+        meta:
+          dimension:
+            type: date
+            time_intervals: ['DAY', 'WEEK', 'fiscal_quarter', 'YEAR']
+    ```
+  </Tab>
+  <Tab title="Lightdash YAML">
+    ```yaml
+    dimensions:
+      - name: order_date
+        description: 'Date the order was placed'
+        type: date
+        time_intervals: ['DAY', 'WEEK', 'fiscal_quarter', 'YEAR']
+    ```
+  </Tab>
+</Tabs>
+
+The `${COLUMN}` placeholder in the SQL expression is automatically replaced with the dimension's column SQL at runtime. Custom granularities also inherit `requiredAttributes` and `anyAttributes` from the parent dimension.
+
+<Info>
+  See [lightdash.config.yml reference](/references/lightdash-config-yml#custom-granularities-configuration) for the full configuration options for custom granularities.
+</Info>
+
+### Custom time intervals with additional dimensions
+
+You can also set custom versions of time intervals by using additional dimensions and groups. Here's an example of how that might look if you wanted to add `year_of_week_iso` to your drop down list for the `delivery_date` dimension. Note that by definiting the `groups:` option, we ensure that the new "Year of week" options is displayed as expected.
 
 
 

references/lightdash-config-yml.mdx

@@ -93,6 +93,10 @@ parameters:
 # Configuration for project-wide defaults
 defaults:
   # ...
+
+# Configuration for custom date granularities
+custom_granularities:
+  # ...
 ```
 
 
@@ -248,4 +252,69 @@ models:
 
 <Info>
   See [Tables reference](/references/tables#case-sensitive) for explore-level configuration and [Dimensions reference](/references/dimensions#case-sensitive) for dimension-level configuration.
+</Info>
+
+
+## Custom granularities configuration
+
+The `custom_granularities` section allows you to define reusable custom time granularities that appear in the date zoom dropdown alongside standard options (Day, Week, Month, Quarter, Year). This is useful for business-specific time periods like fiscal quarters, Monday-to-Sunday weeks, or other custom date groupings.
+
+```yaml
+custom_granularities:
+  fiscal_quarter:
+    label: "Fiscal Quarter"
+    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
+  week_monday:
+    label: "Week (Mon-Sun)"
+    sql: "DATE_TRUNC('week', ${COLUMN})"
+  fiscal_year:
+    label: "Fiscal Year"
+    sql: "EXTRACT(YEAR FROM ${COLUMN} + INTERVAL '1 month')"
+```
+
+Each custom granularity is defined as a key-value pair where the key is the granularity name (must be alphanumeric with underscores) and the value is an object with the following properties:
+
+| Property | Required | Value  | Description |
+| :------- | :------- | :----- | :---------- |
+| `label`  | Yes      | string | A user-friendly label for the granularity as it will be displayed in the date zoom dropdown. |
+| `sql`    | Yes      | string | SQL expression that defines how to truncate/transform the date. Use `${COLUMN}` as a placeholder for the actual date column - it will be replaced with the column's SQL at runtime. |
+
+### How custom granularities work
+
+Custom granularities are defined at the project level in `lightdash.config.yml` and become available on date dimensions through the `time_intervals` property. The `${COLUMN}` template in the SQL expression is automatically replaced with the actual column SQL when generating queries.
+
+**Example**: Define a fiscal quarter granularity and use it on a dimension:
+
+```yaml
+# lightdash.config.yml
+custom_granularities:
+  fiscal_quarter:
+    label: "Fiscal Quarter"
+    sql: "DATE_TRUNC('quarter', ${COLUMN} + INTERVAL '1 month')"
+```
+
+```yaml
+# In your model yml file
+columns:
+  - name: order_date
+    meta:
+      dimension:
+        type: date
+        time_intervals: ['DAY', 'WEEK', 'MONTH', 'fiscal_quarter', 'YEAR']
+```
+
+The custom granularity `fiscal_quarter` will now appear in the date zoom dropdown for `order_date`, alongside the standard intervals.
+
+<Info>
+  Custom granularities inherit `requiredAttributes` and `anyAttributes` from the parent dimension, so access controls are automatically applied.
+</Info>
+
+### Use cases
+
+- **Fiscal calendars**: Define fiscal quarters or years that don't align with calendar quarters
+- **Week start customization**: Create weeks that start on Monday or any other day
+- **Custom periods**: Define business-specific time periods like "retail weeks" or "academic terms"
+
+<Info>
+  See [Dimensions reference](/references/dimensions#time-intervals) for more information on configuring time intervals on dimensions, including how to reference custom granularities.
 </Info>