# TsFile verilerini yükle

[TsFile](https://tsfile.apache.org/), zaman serisi verileri için tasarlanmış sütun tabanlı bir dosya biçimidir ve [Apache IoTDB](https://iotdb.apache.org/)'nin yerel depolama katmanı olarak kullanılır. Parquet gibi genel amaçlı sütun tabanlı biçimlerle karşılaştırıldığında TsFile, zaman serisi veri modelinin (zaman damgaları, cihazlar ve ölçümler) farkındadır ve tüm dosyaları taramadan zaman aralığına göre budama yapılmasını sağlayan dahili bir zaman dizini sürdürür.

Bu yükleyici, standart satır-başına-kayıt tablo düzenini takip etmediği için ayrı bir kılavuz olarak sunulmaktadır: her çıktı satırı bir *cihaza* karşılık gelir ve ölçüm başına değerler Arrow `list<...>` sütunları olarak döndürülür. Eşleme aşağıda ayrıntılı olarak açıklanmıştır.

## Kurulum

Yükleme aracı [`tsfile`](https://pypi.org/project/tsfile/) Python paketine bağımlıdır:

```bash
pip install "tsfile>=2.3.0"
```

## Veri modeli ve çıktı düzeni

Yükleme aracı, TsFile *tablo modelini* izler. Her tablo sütunu aşağıdakilerden biridir:

- **TAG** — string tipinde bir tanımlayıcı; TAG değerlerinin demeti, bir *device*'ı (yani tek bir zaman serisi kaynağını) benzersiz şekilde tanımlar.
- **FIELD** — değeri zamanla değişen bir ölçüm.
- **TIME** — zaman damgası sütunu, varsayılan olarak `time` adıyla adlandırılır.

Yükleyici, cihaz başına bir veri seti satırı yazar. Satır içinde, `time` sütunu ve her FIELD sütunu, o cihazın tam zaman serisini artan zaman sırasına göre içeren Arrow `list<...>` sütunlarıdır. TAG sütunları, skaler `string` sütunları olarak görünür.

Somut olarak, çıktı şeması şu biçimde olur:

```text
<tag_1>:    string
<tag_2>:    string                       # one column per TAG
...
time:       list<timestamp[unit, tz]>
<field_1>:  list<original_type>          # one column per FIELD
<field_2>:  list<original_type>
...
```

Aynı cihaz, bir bölünmenin (split) birden fazla giriş dosyasında görünüyorsa, dosya başına parçalar (chunks) tek bir satır olarak yayımlanmadan önce birleştirilir ve zaman damgasına göre sıralanır. Aynı cihaz için yinelenen zaman damgaları `ValueError` hatası oluşturur.

## Temel kullanım

Tek bir TsFile yükleyin:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("tsfile", data_files="my_data.tsfile")
```

Dosyaları bölümlere açıkça eşleyin:

```py
>>> dataset = load_dataset(
...     "tsfile",
...     data_files={"train": "train_data.tsfile", "test": "test_data.tsfile"},
... )
```

## Hub'daki örnek veri seti

Hazır bir örnek [`tsfile/lotsa_data`](https://huggingface.co/datasets/tsfile/lotsa_data) adresinde mevcuttur. `.tsfile` dosyaları otomatik olarak tanındığından, `data_files` belirtmeden depoyu kimliğiyle yükleyebilirsiniz:

```py
>>> from datasets import load_dataset
>>> dataset = load_dataset("tsfile/lotsa_data")
>>> dataset
DatasetDict({
    train: Dataset({
        features: ['timeseries_id', 'time', 'value'],
        num_rows: 91
    })
})
```

Her satır bir cihazı temsil eder. `timeseries_id` sütunu cihazı tanımlarken, `time` ve `value` sütunları, o cihazın tam serisini içeren `list<...>` sütunlarıdır:

```py
>>> row = dataset["train"][0]
>>> row["timeseries_id"]
'Bear_assembly_Angel'
>>> len(row["time"]), len(row["value"])
(8760, 8760)
>>> row["time"][:3]
[datetime.datetime(2017, 1, 1, 0, 0), datetime.datetime(2017, 1, 1, 1, 0), datetime.datetime(2017, 1, 1, 2, 0)]
```

## Tablo seçme

Bir TsFile birden fazla tablo içerebilir. `table_name` atlandığında, ilk geçerli dosyada bulunan ilk tablo kullanılır. Aramalar büyük/küçük harf duyarlı değildir.

```py
>>> dataset = load_dataset("tsfile", data_files="my_data.tsfile", table_name="sensor_data")
```

## Sütun seçimi

`columns`, okunan FIELD sütunlarını kısıtlar. TAG sütunları ve `time` sütunu, cihazı ve zaman çizelgesini tanımladıkları için her zaman döndürülür. `columns` içindeki, bir TAG veya `time` sütununa atıfta bulunan adlar sessizce yok sayılır (normalde olduğu gibi, yalnızca bir kez yayımlanır); hiçbir dosyada bulunmayan bir alana eşleşen adlar, tümü null olan liste sütunlarına dönüşür.

```py
>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     columns=["temperature", "humidity"],
... )
```

## Zaman aralığına göre filtreleme

`start_time` ve `end_time` dahil sınırlardır; her biri atlanabilir. Sınırlar, TsFile'in dahili zaman dizinine aktarılır, böylece diskten yalnızca eşleşen veri blokları okunur. Her iki sınır da aşağıdakilerden herhangi birini kabul eder:

- `int` — `timestamp_unit` birimindeki ham epoch (varsayılan milisaniye);
- `datetime.datetime` — naive değerler UTC olarak yorumlanır, saat dilimi bilgisi içeren değerler UTC'ye dönüştürülür;
- `datetime.date`;
- ISO-8601 `str`, örn. `"2024-01-01T00:00:00"`;
- `pyarrow.TimestampScalar`.

```py
>>> from datetime import datetime
>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     start_time=datetime(2023, 11, 14),
...     end_time="2023-11-15T00:00:00",
... )
```

## Dosyalar arası şema evrimi

Farklı dosyalar farklı sütunları açığa çıkardığında — örneğin yeni bir sensör alanı daha sonra tanıtıldığında — yükleyici, tüm FIELD sütunlarının birleşimini alır ve eksik değerleri null ile doldurur. Sayısal FIELD türleri, IoTDB'nin genişletme kurallarına (`INT32 → INT64 → DOUBLE`, `INT32 → FLOAT → DOUBLE`) göre yükseltilir.

```py
>>> dataset = load_dataset("tsfile", data_files=["day1.tsfile", "day2.tsfile"])
```

## Okunamayan dosyalarla başa çıkmak

Varsayılan olarak, okunamayan veya TsFile olmayan bir girdi hata oluşturur. Kaydı günlüğe alıp devam etmek için `on_bad_files` değerini `"warn"` olarak, dosyayı sessizce atlamak için ise `"skip"` olarak ayarlayın.

```py
>>> dataset = load_dataset("tsfile", data_files="data/*.tsfile", on_bad_files="skip")
```

## Zaman damgası birimi ve saat dilimi

`timestamp_unit` (varsayılan `"ms"`, IoTDB ile uyumlu) `time` sütununun çözünürlüğünü ve tamsayı zaman sınırlarının yorumlanmasını kontrol eder. `timestamp_tz`, Arrow zaman damgası türüne bir saat dilimi ekler; `None` (varsayılan) saat dilimi bilgisi olmayan bir tür üretir.

```py
>>> dataset = load_dataset(
...     "tsfile",
...     data_files="my_data.tsfile",
...     timestamp_unit="us",
...     timestamp_tz="UTC",
... )
```

## Bellek ve toplu işleme

Bellek kullanımını iki parametre kontrol eder:

- `input_batch_size` (varsayılan `65_536`) — `TsFileReader.query_table` üzerinden her Arrow partisi için getirilen maksimum satır sayısı. Tek bir cihazda akış sırasında tepe belleği sınırlar.
- `output_batch_size` (varsayılan `32`) — yazarın ürettiği her Arrow kayıt grubuna (record batch) paketlenen cihaz sayısı. Daha küçük değerler daha duyarlı ilerleme raporlaması sağlar; daha büyük değerler grup başına düşen yükü azaltır.

```py
>>> dataset = load_dataset(
...     "tsfile",
...     data_files="large_data.tsfile",
...     input_batch_size=32_768,
...     output_batch_size=128,
... )
```

Zirve bellek, bölünme boyunca tek bir cihazın yüküyle sınırlıdır, bölünmenin tamamının boyutuyla değil.

Parametrelerin tam listesi için [TsFileConfig](/docs/datasets/main/tr/package_reference/loading_methods#datasets.packaged_modules.tsfile.TsFileConfig)'e bakın.