---
title: "Use the SPREAD Function to Distribute Values Across Dimensions"
slug: "spread-function"
description: "Learn to master the SPREAD function in Pigment to allocate numeric values across ordered items dynamically and efficiently."
updated: 2025-05-30T09:40:48Z
published: 2025-08-22T10:57:28Z
---
> ## 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.
# SPREAD function
## Description
Spreads numerical values on a certain number of items on any ordered Dimension.
## Syntax
`SPREAD(Source Block, Ranking Dimension, Spread Number [, Starting Index])`
- `Source Block` - can be a List or a Metric that must be a number or integer data type.
- `Ranking Dimension` - this is a dimension from the Source Block that you want to spread the numbers across
- `Spread Number` - defines how many items to split the total across. This needs to be an integer.
- `Starting Index` - defines a starting point of each spread, that is to say a List Property or a Metric using a subset of the Source Block dimensions and of type the Ranking Dimension.
## Return type
`number`
## Examples
| **Case** | **Results** | **Return Type** |
| --- | --- | --- |
| `SPREAD('Quantity Sold', Month, 3)` | split the `Quantity Sold` of each month over 3 months (Jan 20 will be split 1/3 over Jan, Feb and March) | `number` |
| `SPREAD('Quantity Sold', Month, 'country'.'spread')` | split the `Quantity Sold` of each month over a number of periods defined on a Property of the `Country list` | `number` |
| `SPREAD(10[BY: Month."Feb 20"], Month, 6)` | set `Feb 20` to 10 and split it over 6 months (1.67 from February to July) | `number` |
| `SPREAD('Cards', Participant, 2)` | each `participant` will receive a number of cards stored in the Metric `Cards` and split them in half (one half that they will keep, the other one to the participant next in ranking. | `number` |
| `SPREAD('Employee Start Bonus',Month,3,'Employee Start Date')` | each Employee will receive a Start Bonus stored in the Metric `Employee Start Bonus` and split over the next `3` month after their `Employee Start Date`. | `number` |
**Excel equivalent**: None