--- title: "KEEP modifier" slug: "keep-modifier" description: "Learn how to retain specific dimensions in a block while removing others, using aggregation methods like SUM for effective data management." tags: ["Retained Dimensions", "Aggregation Method", "Metric Definition"] updated: 2026-10-09T09:54:35Z published: 2026-10-09T09:54:35Z canonical: "kb.pigment.com/keep-modifier" --- > ## 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. # KEEP modifier ## Description Retains the listed Dimensions on a Block and removes all others. ## Syntax `source_block [KEEP [aggregator] [ON (<dimension1>[, <dimension2>])]: dimension3[, dimension4]]` - `source_block` The Metric whose Dimensions you want to keep. - `aggregator` The aggregation method applied to the removed Dimensions (e.g. `SUM`, `AVG`, `FIRST`, `FIRSTNONBLANK`). If omitted, the default is `SUM`. - `ON` Defines the order in which the removed Dimensions are aggregated. It only applies to ordered aggregators (`FIRST`, `LAST`, `FIRSTNONBLANK`, `LASTNONBLANK`, `FIRSTNONZERO`, `LASTNONZERO`, `TEXTLIST`). When more than one Dimension is removed and you don't write an `ON` expression, Pigment adds it automatically so the order is explicit in the formula. You can then edit it to change the order. - `dimension1` (only after an ON expression) A Dimension you want to remove. - `dimension2` (only after an ON expression) Any additional Dimensions you want to remove, executed in order after `dimension1`, separated by a comma. - `dimension3` The Dimension you want to retain. - `dimension4` Any additional Dimensions you want to retain, separated by a comma. The default aggregator, if omitted, is `SUM` for objects of the Number data type. Other aggregators are described in the article [Aggregation data in formulas](/v1/docs/aggregate-data-in-formulas#aggregation-methods). ## Return type `same as source object` ## Examples `Revenue` is a Metric of the Number data type, with the following Dimensions: `Country`, `Product`, and `Month`. | Case | Results | | --- | --- | | `Revenue[KEEP SUM: Country]` | Returns the Revenue by Country where all other Dimensions were aggregated using sum. | | `Revenue[KEEP AVG: Month]` | Returns the Revenue by Month where all other Dimensions were aggregated using average. | | `Revenue[KEEP FIRSTNONBLANK: Country]` | Returns the Revenue by Country, taking the first non-blank value across the removed Dimensions. As `Product` and `Month` are both removed with an [ordered aggregator](/v1/docs/aggregate-data-in-formulas#ordered-aggregators-and-dimension-order), Pigment saves the formula as `Revenue[KEEP FIRSTNONBLANK ON (Product, Month): Country]`. Edit the `ON` expression to aggregate `Month` before `Product`. | | `Revenue[KEEP FIRSTNONBLANK ON (Product, Month): Country]` | As above. You can set up formulas directly to specify the aggregation order. | **See also**: [REMOVE](/v1/docs/remove-modifier) ## Related - [Aggregate Data in Formulas](/aggregate-data-in-formulas.md) - [Aggregation and allocation methods](/aggregators-and-allocators.md)