# The time dimension
URL: https://docs.valsight.ai/time-dimension/
Description: Time is the one dimension Valsight generates for you, with its levels and level values derived from the project's time horizon.
Time is the one dimension you never create. Valsight generates it for every project, derives its level values from the project time horizon, and regenerates them when the horizon changes. That makes it behave differently from the dimensions you build yourself, which matters before you upload data, write a formula, or pick a chart level.

For the vocabulary used below (dimension, level, level value, hierarchy) see [How dimensions work](/how-dimensions-work/).

## How it is generated

The project time horizon defines the start and end of the planning period. Valsight walks every date in that range and derives one level value per level from each date, so the levels are always complete and always consistent with one another.

Two consequences matter in practice:

* You cannot add or remove time level values by hand. Change the horizon instead, see [Changing the Time Horizon](/changing-the-time-horizon/).
* A date outside the horizon has no level value, so uploading data for it raises an error rather than extending the dimension.

## Levels

Every time dimension starts with an `ALL` level that aggregates the whole horizon. Below it sit the levels that carry dates, and a project uses one of two structures for them.

The month-based structure is the default:

| Level   | Level value shape                 | Example  |
| ------- | --------------------------------- | -------- |
| Year    | four-digit year                   | 2025     |
| Quarter | year, hyphen, `Q`, quarter number | 2025-Q4  |
| Month   | year, hyphen, two-digit month     | 2025-01  |
| Day     | eight digits, no separators       | 20250101 |

The week-based structure replaces Quarter and Month with a single Week level:

| Level | Level value shape                     | Example  |
| ----- | ------------------------------------- | -------- |
| Year  | four-digit ISO week-based year        | 2025     |
| Week  | year, hyphen, `W`, two-digit ISO week | 2025-W04 |
| Day   | eight digits, no separators           | 20250101 |

Which structure a project uses is a project property, set when the project is created and changeable afterwards. Two things are worth knowing before changing it:

* In a week-based project the top level is still named `Year`, but it holds the **ISO week-based** year. Early January can therefore belong to the previous year, because a week is never split across two years.
* Switching an existing project from month-based to week-based **deletes its Quarter and Month levels** and unlinks the CalendarMonth dimension; switching back deletes the Week level. Either direction also clears the horizon overrides on every model and workspace. Anything referencing the removed levels stops resolving, so this is not a setting to revisit casually.

## How time columns are loaded from Excel

On upload, Valsight links a column to a time level by its header name. Alongside the level names above it accepts a set of aliases, and header case and surrounding spaces do not matter. See [Recognized Column Names](/recognized-column-names/) for the full list and the value format each level expects.

## Companion dimensions

Two other dimensions deal with time without being part of it:

* **CalendarMonth** holds the months `01` to `12` without a year and is linked to the Month level, so you can compare the same month across years. Optional, see [Calendar Months Dimension](/calendar-months-dimension/).
* **Sequence** describes abstract steps relative to a starting point ("Year 0", "Year 1") rather than calendar dates, for models such as depreciation or ramp-up curves. See [Configure the Sequence Dimension](/configure-the-sequence-dimension/).

## Related

* [How dimensions work](/how-dimensions-work/): the vocabulary and mental model behind every dimension
* [Changing the Time Horizon](/changing-the-time-horizon/): the setting that drives which level values exist
* [Project Settings](/project-settings/): **Divide years into** is where the calendar is chosen, and therefore where the shape above is decided
* [Recognized Column Names](/recognized-column-names/): the column headers an upload links to time levels automatically
* [Calendar Months Dimension](/calendar-months-dimension/): comparing the same month across years