> ## 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.

# DatasetItem

> Rows inside a Dataset that hold coefficients and metadata

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:

```json theme={null}
{
  "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:

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

```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
```

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