تحميل بيانات TsFile

TsFile هو تنسيق ملفات عمودي مصمم لبيانات السلاسل الزمنية ويُستخدم كطبقة تخزين أصلية في Apache IoTDB. مقارنةً بتنسيقات عمودية عامة مثل Parquet، فإن TsFile يدرك نموذج بيانات السلاسل الزمنية (الطوابع الزمنية، والأجهزة، والقياسات) ويحافظ على فهرس زمني داخلي يتيح تقليم نطاقات زمنية دون الحاجة إلى مسح الملفات بأكملها.

يُقدَّم هذا المُحمِّل كدليل منفصل لأنه لا يتبع عادةً الجدولية القياسية التي تعتمد على صف واحد لكل سجل: فكل صف في المخرجات يتوافق مع جهاز واحد، وتُعاد قيم كل قياس على شكل أعمدة من نوع list<...> في Arrow. ويُوصف هذا الترميز بالتفصيل أدناه.

التثبيت

يعتمد المُحمِّل على حزمة tsfile بلغة بايثون:

pip install "tsfile>=2.3.0"

نموذج البيانات وتخطيط المخرجات

يتبع المُحمِّل نموذج الجدول الخاص بـ TsFile. كل عمود في الجدول هو أحد ما يلي:

• TAG — مُعرِّف من نوع نصي؛ يُحدِّد tuple من قيم TAG بشكل فريد device (أي مصدر سلسلة زمنية واحد).
• FIELD — قياس تتطور قيمته مع مرور الوقت.
• TIME — عمود الطابع الزمني، واسمه الافتراضي time.

يُصدر المُحمِّل صف بيانات واحد لكل جهاز. داخل الصف، تكون عمود time وكل أعمدة FIELD من أعمدة Arrow من نوع list<...> تحتوي على سلسلة الوقت الكاملة لذلك الجهاز، مرتبةً بترتيب تصاعدي حسب الوقت. تظهر أعمدة TAG كأعمدة string قياسية.

تحديداً، يكون مخطط الإخراج على النحو التالي:

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

عندما يظهر نفس الجهاز في ملفات إدخال متعددة ضمن تقسيم، يتم دمج مقاطعه لكل ملف وترتيبها حسب الطابع الزمني قبل إصدارها كصف واحد. تثير الطوابع الزمنية المكررة لنفس الجهاز ValueError.

الاستخدام الأساسي

تحميل ملف TsFile واحد:

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

Map files to splits explicitly:

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

مثال على مجموعة بيانات على Hub

يتوفر مثال جاهز للاستخدام في tsfile/lotsa_data. نظرًا لأن ملفات .tsfile تُعرَّف تلقائيًا، يمكنك تحميلها عبر معرف المستودع دون تحديد 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
    })
})

كل صف يمثل جهازًا واحدًا. عمود TAG timeseries_id يحدد الجهاز، بينما time وvalue هما عمودان من نوع list<...> يحتويان على السلسلة الكاملة لذلك الجهاز:

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

اختيار جدول

يمكن أن يحتوي ملف TsFile على عدة جداول. عند إغفال table_name، يُستخدم أول جدول يُعثر عليه في أول ملف صالح. عمليات البحث غير حساسة لحالة الأحرف.

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

اختيار الأعمدة

columns يقيّد أعمدة FIELD التي يتم قراءتها. تُعاد أعمدة TAG وعمود time دائمًا لأنها تحدد الجهاز وخطه الزمني. تُتجاهل بأثر صامت الأسماء في columns التي تشير إلى TAG أو إلى عمود time (تُصدر كما هو معتاد، مرة واحدة فقط)؛ أما الأسماء التي تطابق حقلًا غير موجود في أي ملف فتصبح أعمدة قوائم فارغة بالكامل.

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

التصفية حسب نطاق زمني

start_time وend_time حدّان شاملان؛ يمكن حذف أيٍّ منهما. تُدفع الحدود إلى فهرس الوقت الداخلي في TsFile، بحيث تُقرأ من القرص كتل البيانات المطابقة فقط. تقبل كلتا الحديدين أيًّا مما يلي:

• int — الحقبة الخام بوحدة timestamp_unit (الافتراضي: مللي ثانية)؛
• datetime.datetime — تُفسَّر القيم غير المرتبطة بمنطقة زمنية على أنها بتوقيت UTC، وتُحوَّل القيم المرتبطة بمنطقة زمنية إلى UTC؛
• datetime.date;
• ISO-8601 str، على سبيل المثال "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",
... )

تطور المخطط عبر الملفات

عندما تعرض ملفات مختلفة أعمدة مختلفة — على سبيل المثال، يُقدَّم حقل مستشعر جديد لاحقًا — يقوم المُحمِّل بأخذ اتحاد جميع أعمدة FIELD ويملأ القيم الناقصة بقيم null. يتم ترقية أنواع FIELD الرقمية وفقًا لقواعد IoTDB للتوسيع (INT32 → INT64 → DOUBLE، INT32 → FLOAT → DOUBLE).

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

التعامل مع الملفات غير القابلة للقراءة

بشكل افتراضي، يثير إدخال غير قابل للقراءة أو غير من نوع TsFile خطأً. اضبط on_bad_files على "warn" لتسجيل الأمر والمضي قدماً، أو "skip" لإسقاط الملف بصمت.

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

وحدة الطابع الزمني ومنطقة التوقيت

timestamp_unit (الافتراضي "ms"، بما يتوافق مع IoTDB) يتحكم في دقة عمود time وتفسير حدود الوقت الصحيحة. يربط timestamp_tz منطقة زمنية بنوع Arrow timestamp؛ بينما يعطي None (الافتراضي) نوعًا غير مرتبط بمنطقة زمنية.

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

الذاكرة والتجميع

يتحكم معاملان في استخدام الذاكرة:

• input_batch_size (الافتراضي 65_536) — الحد الأقصى لعدد الصفوف المستخرجة لكل دفعة Arrow من TsFileReader.query_table. يحدد ذروة الذاكرة أثناء بث جهاز واحد.
• output_batch_size (الافتراضي 32) — عدد الأجهزة المُجمَّعة في كل دفعة سجلات Arrow المُقدَّمة إلى الكاتب. تمنح القيم الأصغر تقارير تقدّم أكثر استجابة؛ بينما تقلل القيم الأكبر من النفقات التشغيلية لكل دفعة.

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

الحد الأقصى للذاكرة محكوم بحجم الحمولة على جهاز واحد عبر التقسيم، وليس بحجم التقسيم ككل.

راجع TsFileConfig للحصول على القائمة الكاملة للمعاملات.