# Muat data TsFile

[TsFile](https://tsfile.apache.org/) adalah format file kolom yang dirancang untuk data deret waktu dan digunakan sebagai lapisan penyimpanan native dari [Apache IoTDB](https://iotdb.apache.org/). Dibandingkan dengan format kolom umum seperti Parquet, TsFile memahami model data deret waktu (stempel waktu, perangkat, dan pengukuran) serta mempertahankan indeks waktu internal yang memungkinkan pemangkasan rentang waktu tanpa memindai seluruh file.

Loader ini disediakan sebagai panduan terpisah karena tidak mengikuti konvensi tabular satu baris per rekaman yang umum: setiap baris output sesuai dengan satu *device*, dan nilai per pengukuran dikembalikan sebagai kolom Arrow `list<...>`. Pemetaan ini dijelaskan secara rinci di bawah.

## Instalasi

Loader bergantung pada paket Python [`tsfile`](https://pypi.org/project/tsfile/):

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

## Model data dan tata letak output

Loader mengikuti *model tabel* TsFile. Setiap kolom tabel adalah salah satu dari:

- **TAG** — pengidentifikasi bertipe string; tuple dari nilai TAG secara unik mengidentifikasi sebuah *device* (yaitu satu sumber time-series).
- **FIELD** — pengukuran yang nilainya berubah seiring waktu.
- **TIME** — kolom timestamp, secara default diberi nama `time`.

Loader mengeluarkan satu baris dataset per perangkat. Di dalam baris, kolom `time` dan setiap kolom FIELD adalah kolom Arrow `list<...>` yang berisi seluruh deret waktu perangkat tersebut, diurutkan berdasarkan waktu secara menaik. Kolom TAG muncul sebagai kolom `string` skalar.

Secara konkret, skema output memiliki bentuk:

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

Ketika perangkat yang sama muncul di beberapa file input dari sebuah split, chunk per file-nya digabungkan dan diurutkan berdasarkan timestamp sebelum dikeluarkan sebagai satu baris. Timestamp duplikat untuk perangkat yang sama akan memicu `ValueError`.

## Penggunaan dasar

Muat satu TsFile:

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

Petakan file ke split secara eksplisit:

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

## Contoh dataset di Hub

Contoh yang siap digunakan tersedia di [`tsfile/lotsa_data`](https://huggingface.co/datasets/tsfile/lotsa_data). Karena file `.tsfile` dikenali secara otomatis, Anda dapat memuatnya dengan id repositori tanpa menentukan `data_files`:

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

Setiap baris adalah satu perangkat. Kolom TAG `timeseries_id` mengidentifikasi perangkat, sedangkan `time` dan `value` adalah kolom `list<...>` yang menyimpan seluruh seri data perangkat tersebut:

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

## Memilih tabel

TsFile dapat berisi beberapa tabel. Ketika `table_name` diabaikan, tabel pertama yang ditemukan di file valid pertama akan digunakan. Pencarian tidak membedakan huruf besar dan kecil.

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

## Memilih kolom

`columns` membatasi kolom FIELD yang dibaca. Kolom TAG dan kolom `time` selalu dikembalikan karena keduanya mengidentifikasi perangkat dan linimasa-nya. Nama di `columns` yang merujuk ke TAG atau ke kolom `time` diabaikan secara diam-diam (kolom tersebut tetap dikeluarkan seperti biasa, hanya sekali); nama yang cocok dengan field yang tidak ada di semua file menjadi kolom daftar yang seluruhnya null.

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

## Filtering berdasarkan rentang waktu

`start_time` dan `end_time` adalah batas inklusif; salah satunya dapat diabaikan. Batas-batas ini diteruskan ke indeks waktu internal TsFile, sehingga hanya blok data yang cocok yang dibaca dari disk. Kedua batas menerima salah satu dari:

- `int` — epoch mentah dalam `timestamp_unit` (default milidetik);
- `datetime.datetime` — nilai naive diinterpretasikan sebagai UTC, nilai yang aware terhadap zona waktu dikonversi ke UTC;
- `datetime.date`;
- ISO-8601 `str`, mis. `"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",
... )
```

## Evolusi skema di antara file

Ketika file yang berbeda mengekspos kolom yang berbeda — misalnya, bidang sensor baru diperkenalkan kemudian — loader mengambil gabungan dari semua kolom FIELD dan mengisi nilai yang hilang dengan null. Tipe FIELD numerik dipromosikan mengikuti aturan pelebaran IoTDB (`INT32 → INT64 → DOUBLE`, `INT32 → FLOAT → DOUBLE`).

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

## Menangani file yang tidak dapat dibaca

Secara default, input yang tidak dapat dibaca atau bukan TsFile akan memicu error. Atur `on_bad_files` ke `"warn"` untuk mencatat dan melanjutkan, atau `"skip"` untuk menghapus file secara diam-diam.

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

## Unit timestamp dan zona waktu

`timestamp_unit` (default `"ms"`, sesuai dengan IoTDB) mengontrol resolusi kolom `time` dan interpretasi batas waktu integer. `timestamp_tz` menempelkan zona waktu ke tipe timestamp Arrow; `None` (default) menghasilkan tipe yang tidak memiliki zona waktu.

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

## Memori dan batching

Dua parameter mengontrol penggunaan memori:

- `input_batch_size` (default `65_536`) — jumlah maksimum baris yang diambil per batch Arrow dari `TsFileReader.query_table`. Membatasi memori puncak saat streaming satu perangkat.
- `output_batch_size` (default `32`) — jumlah perangkat yang dikemas ke dalam setiap Arrow record batch yang diberikan ke writer. Nilai yang lebih kecil memberikan pelaporan progres yang lebih responsif; nilai yang lebih besar mengurangi overhead per-batch.

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

Memori puncak dibatasi oleh muatan satu perangkat di seluruh pemecahan, bukan oleh ukuran pemecahan secara keseluruhan.

Lihat [TsFileConfig](/docs/datasets/main/id/package_reference/loading_methods#datasets.packaged_modules.tsfile.TsFileConfig) untuk daftar lengkap parameter.

