> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omni.co/llms.txt
> Use this file to discover all available pages before exploring further.

<AgentInstructions>

## Submitting Feedback

If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:

POST https://docs.omni.co/feedback

```json
{
  "path": "/modeling/dimensions/parameters/timeframes",
  "feedback": "Description of the issue"
}
```

Only submit feedback when you have something specific and actionable to report.

</AgentInstructions>

# timeframes

> Sets the default time segments available for date/time fields in workbooks.

If absent, Omni uses default timeframes: `raw`, `date`, `week`, `month`, `quarter`, `year`.

Timezone handling is possible using the [`convert_tz`](/modeling/dimensions/parameters/convert-tz) argument, done in concert with connection-level [timezone settings](/connect-data/timezones).

Date or time fields can reference parameterized timeframes in the model as follows:

* `timestamp_created_at` (the 'raw' reference)
* `timestamp_created_at[date]`
* `timestamp_created_at[year]`
* `timestamp_created_at[day_of_week_name]`
* `timestamp_created_at[month_name]`

## Syntax

```yaml theme={null}
<dimension_name>:
  timeframes: [<timeframe_1>, <timeframe_2>, ...]
```

## Properties

<ParamField path="dimension_name" type="object">
  The name of the dimension. Dimension names must:

  * Be unique within the view
  * Start with a letter
  * Contain only alphanumeric characters and underscores

  <Expandable title="dimension_name properties" defaultOpen="true">
    <ParamField path="timeframes" type="string[]">
      An array of timeframe names to make available for this date/time field. The following timeframes are supported:

      | Name               | Notes                                                                  |
      | ------------------ | ---------------------------------------------------------------------- |
      | `date`             |                                                                        |
      | `day_of_month`     |                                                                        |
      | `day_of_quarter`   | Behaves as fiscal day of quarter when fiscal offset is applied         |
      | `day_of_week_name` | Sorts by `day_of_week_num`                                             |
      | `day_of_week_num`  |                                                                        |
      | `day_of_year`      |                                                                        |
      | `fiscal_quarter`   | Requires [`fiscal_month_offset`](/modeling/models/fiscal-month-offset) |
      | `fiscal_year`      | Requires [`fiscal_month_offset`](/modeling/models/fiscal-month-offset) |
      | `hour`             |                                                                        |
      | `hour_of_day`      |                                                                        |
      | `millisecond`      |                                                                        |
      | `minute`           |                                                                        |
      | `month`            |                                                                        |
      | `month_name`       | Sorts by `month_num`                                                   |
      | `month_num`        |                                                                        |
      | `quarter`          |                                                                        |
      | `quarter_of_year`  |                                                                        |
      | `raw`              |                                                                        |
      | `second`           |                                                                        |
      | `week`             |                                                                        |
      | `year`             |                                                                        |
    </ParamField>
  </Expandable>
</ParamField>

## Examples

```yaml title="Custom timeframes" theme={null}
created_at:
  sql: created_at
  timeframes: [date, week, day_of_week_name]
  convert_tz: false
```

```yaml title="Timezone-specific field" theme={null}
timestamp_created_pst:
  sql: DATETIME(${marketing_orders_new.timestamp_created}, 'America/Los_Angeles')
  timeframes:
    - DATE
    - HOUR_OF_DAY
    - MONTH_NAME
```

Custom timeframes can be included using [`group_label`](/modeling/dimensions/parameters/group-label). The `group_label` should match the label rather than the underlying field:

```yaml title="Custom timeframe in existing group" theme={null}
created_at_minute_5:
  sql: id+1
  group_label: Created At
```