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: 
{
  "name": "natural-gas-commercial",
  "year": 2024,
  "data": { "kgCO2e": 53.02, "kgCO2": 52.91, "label": "Commercial NG" },
  "description": "Commercial natural gas factors",
  "link": "https://example.com/source",
  "tags": ["natural-gas", "scope-1"]
}

​
Using DatasetItems in Calculations

Use the $datasets helper in Activity Definitions: 
// Get a specific item’s full data (latest year if year omitted)
const item = await $datasets.getItem("epa-factors", "natural-gas-commercial", $year);

// Get one coefficient from an item
const ef = await $datasets.getCoefficient("epa-factors", "natural-gas-commercial", "kgCO2e", $year);

// Get multiple items from a dataset (optionally filtered by year)
const items = await $datasets.getDataset("epa-factors", $year);

// Get an object keyed by item names → data
const all = await $datasets.getCoefficients("epa-factors", $year);
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: 
name,year,datasetName,data_kgCO2e,data_kgCO2,tags,description
natural-gas-commercial,2024,epa-factors,53.02,52.91,"natural-gas,scope-1",Commercial NG
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