---
title: "Use the YEARTODATE Function to Cumulate Time Based Metrics Yearly"
slug: "yeartodate-function"
description: "Learn to use YEARTODATE to cumulate Metrics by Day or Month, resetting the total at the start of each year."
updated: 2025-05-30T09:43:38Z
published: 2025-08-22T11:59:25Z
---
> ## Documentation Index
> Fetch the complete documentation index at: https://kb.pigment.com/llms.txt
> Use this file to discover all available pages before exploring further.
# YEARTODATE function
## Description
Cumulates a Metric defined on a Time Dimension (Day, Month or Quarter) and resets the cumulation each year.
> Equivalent of: CUMULATE(Metric, Quarter, Quarter.Year) or CUMULATE(Metric, Month, Month.Year) or CUMULATE(Metric, Day, Day.Year)
## Syntax
`YEARTODATE(Metric [, Aggregation])`
## Arguments
| Argument | Type | Dimensions | Description |
| --- | --- | --- | --- |
| *Metric* (required) | Number | Time Dimension more granular than Year | Number to cumulate. |
| *Aggregation* (optional) | Aggregation | | Available values: SUM, AVG, MIN, MAX. By default, the aggregation is SUM. |
## Returns
| Type | Dimensions |
| --- | --- |
| Number | Same Dimensions as argument *Metric* |
## Examples
| Formula | Description |
| --- | --- |
| `YEARTODATE('Quantity Sold')` | Cumulates the Metric ‘Quantity Sold’ (each day/month/quarter is added to the sum of the previous day/month/quarter and reset when the year changes). |
> ### Calculated Item, Show Value As or Formula?
>
> Pigment also has Calculated Item and Show Value as presets for Year to Date calculations.
>
> Check out [this article](/v1/docs/show-values-as/#presets) to see how you can use Show value as to calculate year to date for the entire Metric or use the [calculated item preset](/v1/docs/compare-data-with-calculated-items/#presets) for getting a Year to Date calculation for an individual item or up until a particular time period. Its important to note, that while theses calculations are easier and more flexible, they can not be referenced by other Metrics.
## See also
Related articles: [CUMULATE](/v1/docs/cumulate-function), [QUARTERTODATE](/v1/docs/quartertodate-function), [MONTHTODATE](/v1/docs/monthtodate-function)
> [!TIP]
> **More of a hands-on learner?**
>
> Talk to your Customer Success Manager about downloading the Functions and Modifiers in Pigment Application into your workspace. It includes examples of every formula and modifier in Pigment!