Muat data TsFile

TsFile adalah format file kolom yang dirancang untuk data deret waktu dan digunakan sebagai lapisan penyimpanan native dari Apache IoTDB. 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:

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:

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

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

Petakan file ke split secara eksplisit:

>>> 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. Karena file .tsfile dikenali secara otomatis, Anda dapat memuatnya dengan id repositori tanpa menentukan data_files:

>>> 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 untuk perangkat tersebut:

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

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

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

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

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

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

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

>>> 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 untuk daftar lengkap parameter.