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

> Hesaplamalar, panolar ve formlar için kullanılan referans veri konteynerleri

Dataset’ler; emisyon katsayıları gibi referans verilerin tutulduğu konteynerlerdir. Azalt'ta bir Dataset ya kuruma aittir (özel) ya da sisteme aittir (genel). Her Dataset, gerçek katsayıları JSON olarak tutan çok sayıda DatasetItem (satır) içerir.

Bu sayfa şunları açıklar:

* Azalt'ta dataset modeli ve yetkilendirme
* Dataset’lerin hesaplama ve panolarda kullanımı
* UI üzerinden yönetim (içe/dışa aktarma, silme)
* Veri temizliği ve performans için öneriler

## Veri Modeli (Gerçek)

* Dataset: `id`, `name`, `organizationId|null`, zaman damgaları
* DatasetItem: ayrıntılar için “DatasetItem” sayfasına bakın. Temel alanlar: `name` (anahtar), `year`, `data` (JSON), `description`, `link`, `tags`

Notlar:

* Genel dataset’lerde `organizationId = null` olur; oluşturma/güncelleme/silme/dışa aktarma için ADMIN gerekir
* Bir Dataset, içinde hiç item yoksa silinebilir

## Hesaplamalarda Kullanım

Aktivite Tanımlarında hesaplama bağlamında `$datasets` yardımcı nesnesi bulunur. Dataset adı, item adı ve opsiyonel yıl ile katsayı çekebilirsiniz.

```javascript theme={null}
// Bağlamda mevcut: $datasets, $year, $period, $periodUnit, $siteId
async function calculate({ rooms, nights, country }) {
  const ef = await $datasets.getCoefficient(
    "hotel-emission-factors",     // datasetName
    country.toLowerCase(),         // itemName
    "kgCO2e",                     // item.data içindeki alan
    $year,                         // opsiyonel yıl; verilmezse en güncel yıl
  );

  if (!ef) return { value: 0 };
  return { value: ef * rooms * nights };
}
```

Diğer yöntemler:

* `$datasets.getItem(datasetName, itemName, year?)` → `{...data}` veya `null`
* `$datasets.getDataset(datasetName, year?)` → `[ { name, data, year }, ... ]`
* `$datasets.getCoefficients(datasetName, year?)` → `{ [itemName]: data }`

Bu yöntemler sunucu tarafındaki `datasets.getItem/get/getCoefficient/getCoefficients` tRPC uçlarına karşılık gelir.

## Panolarda Dataset Kullanımı

Göstergeler (indicator) DatasetItem’lara bağlanabilir ve widget’lar gösterge değerini bir dataset alanına eşleyebilir. İç format `datasetId::itemName::field` şeklindedir. Sunucu yıl/alan eksikleri gibi eşleme sorunlarını tespit edip widget panelinde bildirir.

## UI Üzerinden Yönetim

Konum: `Özelleştirme → Dataset’ler`

* Dataset oluştur (ADMIN genel yapabilir)
* Dataset ve item’ları görüntüle/ara
* CSV ile içe/dışa aktar
* Dataset sil (yalnızca item yoksa)

### CSV İçe Aktarma (DatasetItem)

Gerekli sütunlar:

* `name` (item anahtarı)
* `year` (sayı)
* `datasetId` veya `datasetName` (ikincisinden biri)

Opsiyonel sütunlar:

* `description`, `link`, `tags`
* `data_*` ile başlayan sütunlar; `data_` sonrası anahtar adı olarak `data` içine yazılır. Hücre değeri düz bir sayıysa sayı olarak parse edilir (örn. `53.02`).

Minimal örnek:

```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",Ticari NG faktörleri
```

İçe aktarma davranışı:

* Satır `datasetName` içeriyor ve bu ad yoksa, mevcut kurum altında dataset oluşturulur
* Çakışma koruması: `(datasetId, name, year)` tekrarlanamaz
* Büyük dosyalar partiler halinde işlenir; sorunlu satırlar raporlanır

### CSV Dışa Aktarma

Bir dataset’teki tüm item’ları `data_*` sütunları ile dışa aktarır. Genel dataset dışa aktarma yalnızca ADMIN için açıktır.

## Güvenlik ve Yetkiler

* Tüm işlemler geçerli kurumla sınırlıdır (RLS)
* Sistem (genel) dataset’lerinde oluşturma/güncelleme/silme/dışa aktarma için ADMIN gerekir

## Performans Notları

* Çok büyük dataset’lerde sayfalama + sunucu tarafı arama kullanılır
* `name` anahtarlarını kısa ve kararlı tutun; `data` içeriğini lean tutun

## En İyi Uygulamalar

* DatasetItem `name` değerlerinde boşluk yerine kısa, küçük harfli anahtarlar kullanın
* Sayısal alanları gerçekten sayı olarak tutun (CSV `data_*` sütunları ile)
* Aynı dataset içinde `(name, year)` tekrarından kaçının
* Aramayı kolaylaştırmak için anlamlı `tags` ekleyin (örn. `electricity`, `scope-2`)
* Panolarda görselleştirmek istediğiniz alanlara eşleme yapın