> ## 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/duration",
  "feedback": "Description of the issue"
}
```

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

</AgentInstructions>

# duration

> Calculates the time difference between two timestamp fields in various intervals.

Duration dimensions automatically generate multiple interval variations (such as days, weeks, months, years) to provide flexible time difference analysis.

Duration dimensions behave similarly to timeframe dimensions, automatically creating parameterized versions of the field for different time intervals.

<Tip>
  You can also create duration fields directly from the workbook UI by right-clicking on a timestamp field and selecting **Duration**. Refer to [Creating duration fields from the workbook](/analyze-explore/custom-fields#duration-fields) for more information.
</Tip>

## Syntax

```yaml theme={null}
<dimension_name>:
  duration:
    intervals: [<interval_1>, <interval_2>, ...]
    sql_start: <start_timestamp_field>
    sql_end: <end_timestamp_field>
```

## 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="duration" type="object">
      An object that defines the duration calculation.

      <Expandable title="duration properties" defaultOpen="true">
        <ParamField path="sql_start" type="string" required>
          The starting timestamp field for the duration calculation. Use Omni field reference syntax (e.g., `${view.field_name}`).
        </ParamField>

        <ParamField path="sql_end" type="string" required>
          The ending timestamp field for the duration calculation. Use Omni field reference syntax (e.g., `${view.field_name}`).
        </ParamField>

        <ParamField path="intervals" type="string[]">
          An array of interval names to generate for this duration field. The following intervals are supported:

          | Interval  | Description            |
          | --------- | ---------------------- |
          | `second`  | Difference in seconds  |
          | `minute`  | Difference in minutes  |
          | `hour`    | Difference in hours    |
          | `day`     | Difference in days     |
          | `week`    | Difference in weeks    |
          | `month`   | Difference in months   |
          | `quarter` | Difference in quarters |
          | `year`    | Difference in years    |
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Referencing duration dimensions

Duration dimensions can be referenced in the model using parameterized syntax, similar to timeframes:

* `${order_fulfillment_time[days]}`
* `${order_fulfillment_time[hours]}`
* `${order_fulfillment_time[weeks]}`

**Note**: Unparameterized references will always return `null`. For example, a reference like `${order_fulfillment_time}` will be `null`.

## Examples

```yaml title="Order fulfillment duration" theme={null}
order_fulfillment_time:
  duration:
    sql_start: ${orders.created_at}
    sql_end: ${orders.shipped_at}
    intervals: [hours, days, weeks]
```

```yaml title="User account age" theme={null}
account_age:
  duration:
    sql_start: ${users.created_at}
    sql_end: ${users.last_login_at}
    intervals: [days, months, years]
```

```yaml title="Project duration with all intervals" theme={null}
project_length:
  duration:
    sql_start: ${projects.start_date}
    sql_end: ${projects.end_date}
    intervals: [days, weeks, months, quarters, years]
```

## Related parameters

* [`timeframes`](/modeling/dimensions/parameters/timeframes) - For time segmentation of timestamp fields
* [`sql`](/modeling/dimensions/parameters/sql) - For custom field calculations