Understanding Pigment Modeling

by gopigment6fec49f4ce9dNo licenseListed Oct 8, 2026Updated Oct 8, 2026

Foundational skill. Read first before any modeling task. Provides the mental model (in-memory sparse multidimensional engine), block-type taxonomy, engine vocabulary, common decision mistakes, and hard rules.

Instructions onlyLearning & Education

AI-generated overview

Foundational reference on Pigment's modeling engine: block types, invariants, and common decision mistakes.

What it does: This skill supplies a conceptual reference for Pigment modeling. It explains the in-memory sparse multidimensional engine, defines the block-type taxonomy (dimension lists, calendars, version dimensions, metrics, transaction lists, tables, boards, views, folders), and lists hard invariants covering structure, naming, build order, formula safety, and structural changes. It also presents a table of decisions agents most often get wrong, such as dimension versus transaction list and dimension-typed versus simple properties.
When to use it: Use it before starting any Pigment modeling task, as the skill itself instructs, to establish the mental model and vocabulary. It is also useful when deciding between block types or checking invariants before making structural changes.
Requirements: No scripts or tools are required; it is an instructions-only reference document. It references other skills and Pigment tools by name but does not execute anything.

Understanding Pigment Modeling

Read this before any modeling task.

Mental Model

Pigment is an in-memory, sparse, multidimensional engine. An Application is a collection of typed blocks. Two orthogonal layers (Native Scenarios for what-if sandboxes, Snapshots for frozen copies) apply across all blocks.

Block type	What it is	When to use
Dimension list	Analysis axis with unique items (rows) and typed properties (columns: Number / Date / Text / Bool / Dimension). A dimension placed in a metric's grid is a structural dimension.	Anything you slice metrics by: Country, Product, Employee, Account
Calendar	Built-in time dimensions: Month, Quarter, Year, Date.	Always reuse. Never recreate time lists.
Version Dimension	Dimension holding Budget / Actual / Forecast items, with switchover and gating properties.	Any planning cycle. See `skill:building-versions-and-planning-cycles`.
Metric	Multidimensional sparse grid (Number / Date / Text / Dim / Bool). Each cell = one value at one combination of structural items. Blank cells are not stored (sparsity). Formulas evaluate within a dimensional context called scope.	Anything you compute, plan, or report
Transaction List	High-volume row store. Items not unique. Never structural.	Granular events (GL, orders, HRIS) to aggregate into metrics with `BY`
Table	Groups metrics sharing dimensions, with calculated rows/columns.	P&L, Balance Sheet, multi-metric reporting
Board	Container page of Widgets.	Dashboards, reports, input screens
View	Configured visual of a Metric or Table (pivots, filters, sort, display mode: Grid / Chart / KPI). Reusable across Boards.	Any reusable data presentation
Folder	Organizational only. No logic.	Sorting and governance

Invariants

These are never negotiable.

Structure

Only dimension lists can be structural. Transaction lists never. Aggregate with BY.
A metric cell = one item per structural dimension. Blank cells are not stored (sparsity).
Every app with planning metrics gets a Version Dimension. Do not skip or defer.
List Subsets delete data irreversibly on membership change. Prefer filters unless the use case is clear.

Naming and organization

Never use ., :, ', or " in block names. Prefer ASCII.
Never place a block at the root level. Use numbered folders.
Folders are inert. They affect discovery, not calculation.

Build order

Calendar (verify/configure) → Dimensions → Version Dimension → Transaction Lists → Metrics (input, then calculated) → Tables → Boards. Always create prerequisites before dependents.
Never recreate time dimensions. Reuse the app calendar.

Formula safety

Never hard-code dimension item references for Time, Version, countries, or planning periods. Use a Dimension-typed input metric. Stable type/class/category items (e.g. 'FX Rate Types'."AVG") may stay hard-coded.
Never use DATE() with literal year/month for period bounds. Use a Date-typed input metric.
When T&D is active: never use a disconnected dimension as the property type on a connected dimension. Ask the user about connectivity if unknown.

Structural changes on existing blocks

A structural change (adding/removing a dimension, changing type) does not automatically propagate to the metrics that reference the changed one. Pigment aligns mismatched dimensions silently (broadcast/collapse) instead of failing, which can produce wrong numbers with no visible error. Before editing, use tool:get_data_dependency_tree (direction Sources) to trace back to the originating metric(s) and transaction list, so you know what grain of detail already exists upstream. Before declaring such a change done, use tool:get_data_dependency_tree (direction Usages) to find dependent formulas, then tool:validate_formula (with target.metric_id) on each to catch a silent mismatch — see skill:writing-pigment-formulas ("Structural Dimension Changes") for the full workflow.
Removing a dimension from a metric's structure is lossy and irreversible. Unlike adding a dimension, once the metric no longer stores that grain the historical detail cannot be recovered from the metric itself. Say so explicitly when proposing the change, even if the detail still exists upstream (e.g. on a source metric or transaction list).

Decisions the Agent Gets Wrong Most Often

Decision	Choose A when	Choose B when
Dimension vs Transaction List	Unique items you slice by	High-volume events, no uniqueness, not structural
Dimension-typed property vs simple property	Values form a finite set you may slice or aggregate by (create a dimension list, reference it as property type)	Free text, measure, date, or boolean that is never a slicing axis
Metric vs Transaction List	Aggregated planning / reporting values	Atomic events from ERP / CRM (then aggregate with `BY`)

When unsure about property types: do not default categorical fields to Text. If the values form a finite set that could become a slicing axis, make it a Dimension.

Source and attribution

Source:gopigment/ai-pluginsinskills/understanding-pigment-modelingat commit6fec49f

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from gopigment/ai-plugins

Writing Pigment Formulas

gopigment

Guides writing, editing and validating Pigment metric formulas, covering quoting, data types, modifiers and BLANK.

Business & FinanceOct 8, 2026

Writing Performant Formulas

gopigment

Checklist and rules for writing sparse, performant Pigment formulas before delivery.

Data & AnalyticsOct 8, 2026

Using Search Tools

gopigment

Execution skill. Choosing between the discovery tools and calling them cheaply: why breadth is free but call count is not, and lineage versus full impact analysis. Load before exploring an application, resolving block names, or checking what a change breaks.

Awaiting classificationOct 8, 2026

Using Mapped Dimensions

gopigment

Explains how to model time-dependent hierarchies in Pigment using mapped dimensions and joined pivots in views.

Data & AnalyticsOct 8, 2026

Using List Subsets

gopigment

Guides when and how to use List Subsets in Pigment, covering decision gates, risks, and safe implementation patterns.

Data & AnalyticsOct 8, 2026

Using Formula Modifiers

gopigment

Explains how to apply Pigment formula modifiers such as BY, ADD, REMOVE, KEEP, SELECT, FILTER and EXCLUDE to align metric dimensions.

AI & AgentsOct 8, 2026

Understanding Pigment Modeling

Understanding Pigment Modeling

Mental Model

Invariants

Decisions the Agent Gets Wrong Most Often

Source and attribution

More from gopigment/ai-plugins

Writing Pigment Formulas

Writing Performant Formulas

Using Search Tools

Using Mapped Dimensions

Using List Subsets

Using Formula Modifiers

More in Learning & Education

Azuresql Db Faq

Airtable Overview

Ui5 Best Practices Tables

Teach

Scaffold Exercises