Skip to main content
DatasetItems are the individual rows inside a Dataset. Each item represents a key (name), a year, and a JSON payload with coefficients (e.g., kgCO2e, kgCO2, …), plus optional description, link, and tags.

​
Data Model (Actual)

Required fields:
  • datasetId: the parent Dataset id
  • name: item key (string; recommended: lowercase, kebab/underscore)
  • year: number
  • data: JSON object with one or more fields (coefficients and attributes)
Optional fields:
  • description: string
  • link: string (reference URL)
  • tags: string[] (for filtering/search)
Uniqueness & behavior:
  • Items are considered duplicates if (datasetId, name, year) repeats
  • Import enforces this and skips/conflicts duplicate rows
Example:

​
Using DatasetItems in Calculations

Use the $datasets helper in Activity Definitions:
Notes:
  • getItem/getCoefficient return null on no‑match
  • getDataset/getCoefficients return empty collections on no‑match

​
Managing Items via CSV Import/Export

Import is available from Customization → Datasets and from the dataset detail page. The importer supports both providing an existing datasetId or a datasetName per row. If a datasetName doesn’t exist, it is created under the current organization. Required columns per row:
  • name (item key)
  • year (number)
  • one of datasetId or datasetName
Optional columns:
  • description, link, tags
  • any data_* columns → become keys under data (e.g., data_kgCO2e → { kgCO2e: <value> }).
Minimal CSV example:
Export produces the same shape with data_* columns. Public dataset export is restricted to ADMIN.

​
Searching and Large Datasets

  • The dataset detail page supports search across name, description, tags, and the text content of data
  • For large datasets, pagination + server‑side search keeps the UI responsive

​
Dashboard Mappings

When an indicator uses dataset values, widgets store mappings as datasetId::itemName::field. The system validates mappings and flags missing data or fields for selected years.

​
Best Practices

  • Choose a stable name per conceptual item (e.g., us_grid_avg, natural-gas-commercial)
  • Keep your numeric values as numbers (CSV parser converts plain numeric cells)
  • Add a short label inside data if you want nicer display text in selectors
  • Use tags to help searching (e.g., electricity, scope-2)
  • Avoid duplicates of (name, year) inside the same dataset