# DATE_EXTRACT
URL: https://docs.valsight.ai/date-extract/
Description: Extracts the year, quarter, month, week, or day from a given time level value.
**Category:** [Project variables](/project-variables/)

> `DATE_EXTRACT` works only in **dynamic project variables**, not in node formulas.

## Overview

The **DATE\_EXTRACT** function **extracts the year, quarter, month, week, or day from a given time level value**.

Use this function in dynamic project variables when you need to derive one time level value from another (for example, the forecast year from the forecast start month).

## Syntax

`DATE_EXTRACT("TimeLevelValue", "TimeLevel")`

**Example usage:** `DATE_EXTRACT("$FORECAST_START", "Year")`

## Parameters

| Parameter          | Description                                                                                                                                                      | Type        | Required |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------- |
| **TimeLevelValue** | A value of any time level in the project's time dimension, given as a quoted string or as a variable reference (for example `"2026-01"` or `"$FORECAST_START"`). | Level value | Yes      |
| **TimeLevel**      | The time level whose value should be returned. Allowed values: `"Year"`, `"Quarter"`, `"Month"`, `"Week"`, `"Day"`.                                              | Level name  | Yes      |

## Output shape

| Aspect      | Behavior                       |
| ----------- | ------------------------------ |
| Return type | Level value                    |
| Format      | Format of the chosen TimeLevel |

## Watch out

* `TimeLevelValue` must be a valid level value within the [project's time horizon](/changing-the-time-horizon/).
* When the requested level is smaller than your input's level, the function extracts the first finer value of your input. See the "Step from a coarser to a finer level" example below.
* Only time-dimension levels are accepted. Other dimensions cannot be passed here.

## Examples

### Extract the year from a month

**Formula:** `DATE_EXTRACT("2026-06", "Year")`

| TimeLevelValue | TimeLevel | DATE\_EXTRACT Result |
| -------------- | --------- | -------------------- |
| `"2026-06"`    | `"Year"`  | `"2026"`             |

### Extract the quarter from a day

**Formula:** `DATE_EXTRACT("20260515", "Quarter")`

| TimeLevelValue | TimeLevel   | DATE\_EXTRACT Result |
| -------------- | ----------- | -------------------- |
| `"20260515"`   | `"Quarter"` | `"2026-Q2"`          |

### Derive a value from another variable

If a project has a fixed variable `$FORECAST_START = "2026-04"`, you can define a derived variable `FORECAST_YEAR` as:

**Formula:** `DATE_EXTRACT("$FORECAST_START", "Year")`

| TimeLevelValue | DATE\_EXTRACT Result |
| -------------- | -------------------- |
| `"2026-04"`    | `"2026"`             |

The derived variable updates automatically whenever `$FORECAST_START` is changed.

### Step from a coarser to a finer level

`"2026"` is a year. When you ask for a finer level (Quarter, Month, Week, or Day), the function returns the first value at that level.

| Formula                           | DATE\_EXTRACT Result | Why                                |
| --------------------------------- | -------------------- | ---------------------------------- |
| `DATE_EXTRACT("2026", "Quarter")` | `"2026-Q1"`          | Q1 is the first quarter of 2026    |
| `DATE_EXTRACT("2026", "Month")`   | `"2026-01"`          | January is the first month of 2026 |
| `DATE_EXTRACT("2026", "Day")`     | `"20260101"`         | January 1 is the first day of 2026 |

### Extract the quarter of the forecast end

To compute the quarter that the forecast end falls in, first offset the forecast start by 12 months with [DATE\_OFFSET](/date-offset/), then extract the quarter.

If `$FORECAST_START = "2026-04"`:

**Formula:** `DATE_EXTRACT(DATE_OFFSET("$FORECAST_START", "Month", 12), "Quarter")`

| Step                                          | Result      |
| --------------------------------------------- | ----------- |
| `DATE_OFFSET("$FORECAST_START", "Month", 12)` | `"2027-04"` |
| `DATE_EXTRACT("2027-04", "Quarter")`          | `"2027-Q2"` |

The combined result is `"2027-Q2"`.

## Related

| Function                      | When to use instead                                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| [DATE\_OFFSET](/date-offset/) | When you want to offset a value forward or backward rather than return it at a different time level. |