---
title: "Model with Lists"
slug: "model-lists"
description: "Explore the essential types of Lists in Pigment, including Dimension and Transaction Lists, and learn how they structure your data effectively."
tags: ["Applications ", "blocks", "calendar", "Dimension Lists", "List Properties", "Modeling Formulas", "Transaction Lists"]
updated: 2026-06-30T14:10:41Z
published: 2026-07-15T09:48:38Z
canonical: "kb.pigment.com/model-lists"
---

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

# Model with Lists

Lists are groups of related Items, such as people in a department, products, or the regions comprising a geographic area. They are fundamental to Pigment as they define the structure and content of a model.

> [!TIP]
> 🎓 **Pigment Academy**
> 
> Check out this three-minute video on the difference between Dimensions and Transaction Lists in the Academy course [Pigment Lists](https://academy.gopigment.com/pigment-lists).

## List types

### Dimension Lists

Dimensions define the **structure** of your data. These Lists are created once and then used throughout your entire Application. They can also be [shared to other Applications](/v1/docs/use-libraries). In most Applications, you have Calendar Dimensions, such as `Years`, `Quarters`, and `Months`. There are also Application-specific examples such as `Products`, `Countries`, `Departments`, and `Employees`.

Think of Dimensions as a way to describe how you want to display your data. A good practice is to use the word “by” before them. For example, I want to display the list of Employees **by** Month, **by** Country and **by** Cost center in a Table. In this case, create the Months, Countries and Cost Center Dimensions in the Application so that you can reuse them within other Metrics and Tables.

Lists are made of Items. Each Item in a Dimension List must be unique. Pigment needs to know which Item is being referenced when you are using the Dimension Lists in multiple Metrics.

Options such as [Hide empty rows or columns](/v1/docs/filter-data-pigment) or [Dynamic Selection](/v1/docs/adaptive-display-controls-page-selectors#dynamic-selection) can be used to hide sparse cells.

### Transaction Lists

Transactions Lists are **lists of Items** that need to be **transformed** or **grouped** for analysis. Unlike Dimension Lists, Transaction List Items do not need to be unique.

They usually represent a **list of events.** For example a list of orders, transactions or a human resources ledger that use functions and formulas such as the [BY modifier](/v1/docs/by-modifier) to group for analysis.

Transactions Lists cannot be used to structure a Metric. They can only be referenced in formulas.

### Change the type of List

You can change the type of List from Dimension to Transaction and vice versa. If a Dimension List is used in the structure of a Metric, it must be removed from the structure before it can be converted into a Transaction List. If it is just referenced, it can be changed.

Use the following steps to change the List type:

1. Navigate to the List you wish to change
2. Select Block settings (cog wheel) in the top right corner.
3. In the General section, under List type, click the **Change to** button.

## Properties

List **Properties** contain metadata—additional information about List Items. For example, in a list of *Employees*, you could add Properties such as *Employee Preferred Name*, the *Department* they work in, etc.

Properties can be used in calculations or to drive the aggregation of data through a model. [Group properties](/v1/docs/set-up-properties-in-lists/#group) can be used to establish hierarchies.

### Create a new Property

To create a new Property:

1. Select the List you would like to work on from the left sidebar.
2. Select **Properties** from the top toolbar. The **CONFIGURE DATA** panel opens to the right.
3. In the panel’s **Properties** tab, select the `+` button by the **Properties** section.
4. In the dialog that opens, **Name** your Property.
5. Select a [**Data type**](/v1/docs/data-types-in-pigment).
6. Choose from the [**Text display**](/v1/docs/format-text-data-types-rich-text) options.
7. Define whether the Items of this new Property should be **Unique** or not. This constraint ensures that all values are different from one another, preventing users from entering the same value twice.
8. Select **Save**, if you want to add another Property, select **Save & add another.**

When you’re done creating Properties, drag and drop them in the panel to reorder them.

You can also right-select a heading in the List and select `Insert new Property right` or `Insert new Property left`. This allows you to easily choose the location of your Property.

### Convert Property formula to values

List Properties can be defined either with manual inputs (values) or with a formula.

For columns defined by formulas, you can convert to values:

1. After selecting any cell of the Property, select the three dots menu to the right of the formula bar.
2. Select **Convert formula to values**.
3. Select **Convert** in the precautionary dialog.

> [!WARNING]
> ⚠️ **Important**
> 
> - Members with the **Configure Blocks** permission always see the **Convert formula to values** button.
> - However, if Access Rights inheritance is enabled in the Application, the button is **disabled** for any Members without the Can Define Security permission.

### Edit and delete Properties

To modify or delete a Property:

1. In your List, select **Properties** from the top toolbar.
2. Go to the **Properties** section.
3. Select the three dots for Property settings in the Property you want to edit.
4. Select **Edit Property** or **Delete Property.**

From there, you can change the Property’s **name** or **type**.

> [!CAUTION]
> **🛡️Warning**
> 
> Note that if you change the type of a Property with data in it, the data is deleted. If you add a unicity constraint, duplicated inputs are removed.

## Reference Lists' Items

Items belong to a List. They can be referenced anywhere in the model by using a formula with syntax `'<List Name>'."<List Item>"`

> [!CAUTION]
> **🛡️ Warning**
> 
> Note that if you change an Item of a List, all the Metrics associated with it are immediately updated.

## Add an Item

To add Items:

1. Select the List you want to work on from the left sidebar.
2. Select **+ Add Item** in the top toolbar.
3. Choose between adding 1, 5, 10, or a custom amount of Items.

## Manage Items

1. Select the List you want to work on from the left sidebar.
2. Select **Manage Items** from the top toolbar.
3. Use the arrows by the Items to reorder them.
4. Check the box of the Items you want to delete.
5. Select the button Delete to remove the Items.
6. Once finished, select **Manage Items** again.

### Export Lists and formulas

You can batch export Lists with their formulas as follows:

1. Select **All Blocks** in the left sidebar.
2. Select **Export** in the top toolbar.
3. From the dialog that opens, select **All Dimension Lists** or **All Transaction Lists**.

The output is a searchable CSV file containing a column with all the Lists’ formulas, if there are any. This allows you to search for keywords in your List formulas.

> [!NOTE]
> ℹ️ Note
> 
> The **Export** button is also available from folders that you open within **All Blocks**. Selecting **All Dimension Lists** or **All Transaction Lists** only exports Dimensions or Transaction Lists within that folder.