Skip to main content
Datasets are containers for reference data used across calculations, dashboards, and forms. In Azalt, a Dataset belongs to an organization (private) or to the system (public). Each Dataset contains multiple DatasetItems (rows) that hold actual coefficient values as JSON. What this doc covers:
  • How datasets are modeled and secured in Azalt
  • How to use datasets in calculation code and dashboards
  • How to manage data via the UI (import/export/delete)
  • Best practices to keep your data clean and fast

​
Data Model (Actual)

  • Dataset: id, name, organizationId|null, timestamps
  • DatasetItem (in a dataset): see the “DatasetItem” doc for full details. Key fields: name (key), year, data (JSON), description, link, tags
Notes:
  • Public datasets have organizationId = null and require ADMIN permissions to create/update/delete/export
  • Datasets can be deleted only if they don’t have any DatasetItems

​
Using Datasets in Calculations

Activity Definitions get a $datasets helper object in the calculation context. Use it to fetch coefficients by dataset name, item name, and optional year. 
// Available context: $datasets, $year, $period, $periodUnit, $siteId
async function calculate({ rooms, nights, country }) {
  const ef = await $datasets.getCoefficient(
    "hotel-emission-factors",     // datasetName
    country.toLowerCase(),         // itemName
    "kgCO2e",                     // coefficientKey in item.data
    $year,                         // optional year; latest if omitted
  );

  if (!ef) return { value: 0 };
  return { value: ef * rooms * nights };
}
Other methods available in calculations:
  • $datasets.getItem(datasetName, itemName, year?) → {...data} or null
  • $datasets.getDataset(datasetName, year?) → [ { name, data, year }, ... ]
  • $datasets.getCoefficients(datasetName, year?) → { [itemName]: data }
These mirror server-side tRPC procedures under datasets.getItem/get/getCoefficient/getCoefficients.

​
Datasets in Dashboards

Indicators can be linked to DatasetItems, and widgets can map indicator values to a dataset field. Mapping format internally uses datasetId::itemName::field. The server validates mappings and reports issues (missing dataset/field/data for a year) in the widget panel.

​
Managing Datasets in the UI

Location: Customization → Datasets
  • Create Dataset (ADMIN can mark as Public)
  • View / search datasets and their items
  • Import or export items as CSV
  • Delete dataset (only if it has no items)

​
CSV Import (DatasetItems)

Required columns:
  • name (item key)
  • year (number)
  • one of datasetId or datasetName
Optional columns:
  • description, link, tags
  • any data_* columns; everything after data_ becomes a key under data. Numbers are parsed where the cell is a plain number (e.g., 53.02).
Minimal 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 factors
Import behaviors:
  • If datasetName doesn’t exist, it’s created for the current organization
  • Duplicate guard: items are unique per (datasetId, name, year)
  • Large imports are batched; problematic rows are reported

​
CSV Export

Exports all items in a dataset to a CSV with data_* columns. Exporting public datasets is restricted to ADMIN.

​
Security & Permissions

  • All reads/writes are RLS‑scoped to the current organization
  • System (public) datasets require ADMIN to create/update/delete/export

​
Performance Notes

  • For very large datasets, the UI uses server‑side search with pagination
  • Prefer compact name keys (e.g., us_grid_avg) and keep JSON small

​
Best Practices

  • Use stable, lowercase name keys for DatasetItems; avoid spaces
  • Keep numeric fields as numbers in data (parsed via CSV data_*)
  • Avoid duplicating (name, year) within the same dataset
  • Tag items meaningfully to help search (e.g., electricity, scope-2)
  • For dashboards, map to specific fields you want to visualize