TsFile verilerini yükle

TsFile, zaman serisi verileri için tasarlanmış sütun tabanlı bir dosya biçimidir ve Apache IoTDB'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 Python paketine bağımlıdır:

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 artan zaman sırasına göre sıralanmış tam zaman serisini 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:

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

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

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

>>> 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 adresinde mevcuttur. .tsfile dosyaları otomatik olarak tanındığından, data_files belirtmeden depoyu kimliğiyle yükleyebilirsiniz:

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

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

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

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

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

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

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

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

>>> 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'e bakın.