> ## Documentation Index
> Fetch the complete documentation index at: https://docs.azalt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Dataset

> Containers for reference data used in calculations, dashboards, and forms

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.

```javascript theme={null}
// 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:

```csv theme={null}
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