---
title: "Use the PREVIOUS Function to Return the Prior Value in a Metric"
slug: "previous-function"
description: "Use PREVIOUS to return a previous cell value in a iteration Dimension of the base Metric. You can create single Metric iterative calculations. "
updated: 2026-07-16T16:47:26Z
published: 2026-07-16T16:47:26Z
canonical: "kb.pigment.com/previous-function"
---

> ## 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.

# PREVIOUS function

## Description

Returns the value of the previous cell of the current Metric in the iteration Dimension.

This function allows you to create single Metric iterative calculations.

> [!NOTE]
> ℹ️ Note
> 
> For usage information and examples, see [Iterative Calculations Within a Block Using PREVIOUS](/v1/docs/iterative-calculations-using-previous).
> 
> To fill blanks across a Metric without iteration, see also [FILLFORWARD function](/v1/docs/fillforward-function).

**Related function**: `FILLFORWARD`

## Syntax

```plaintext
PREVIOUS(Iteration Dimension [, Offset])
```

## Arguments

| Argument | Type | Dimensions | Descriptions |
| --- | --- | --- | --- |
| Iteration Dimension (required) | Number | Any Dimension included in the Metric structure | Dimension of the current Metric to which you want to apply an offset. |
| Offset (optional) | Integer or Metric | No Dimension or same as the Metric | Number of cells to offset. If you leave this argument blank, a default value of `1` is used. Negative offsets are ignored and considered blank. If you offset by calling a Metric, blank cells in the Metric result in PREVIOUS not being applied. Note that Metrics for offsetting can have the same or fewer Dimensions as the current Metric. |

## Returns

| Type | Dimensions |
| --- | --- |
| Same as the current Metric | Same as the current Metric |

## Examples

| Formula | Description |
| --- | --- |
| `PREVIOUS(Month)` | Returns the value of the previous month value of the current Metric. |
| `PREVIOUS(Month,2)` | Returns the value of the current Metric cell, from two months previous. |

> [!WARNING]
> ⚠️ Important
> 
> Sparse datasets allow for much faster computation. The PREVIOUS function can densify your model, as it adds values in its Metrics, reducing performance.
> 
> Integer offsets in PREVIOUS tend to result in faster computation speeds than offsets through a Metric.

## Limitations

To avoid cell-level circular dependencies and optimize computation time, Pigment restricts the use of the PREVIOUS function in the following ways:

1. **Iterating Dimension used with PREVIOUS has a maximum of 10,000 Items**

You can use `PREVIOUS()` with any Dimension, but it can’t have more than 10,000 Items.
2. **Combining Multiple Dimensions to Offset**

It is not possible to combine multiple PREVIOUS() functions using different Dimensions to offset in a given formula. For example, you can’t use this formula: `PREVIOUS(Month) + PREVIOUS(Product)`

However you could achieve similar results with an expression such as: `PREVIOUS(Month)[SELECT: Product -1]`
3. **Advanced Function Compatibility** Use of PREVIOUS with the following is not possible:
  - IRR / XIRR/ NPV
  - DOUBLE_EXPONENTIAL_SMOOTHING / SIMPLE_EXPONENTIAL_SMOOTHING
  - FORECAST_LINEAR, FORECAST_ETS, SEASONAL_LINEAR_REGRESSION
  - DAYSINPERIOD, PRORATA

For more context around limitations of using `PREVIOUS()`, see [Iterative Calculations Within a Block Using PREVIOUS](/v1/docs/iterative-calculations-using-previous).

## See Also

**Excel:** no equivalent