Tải dữ liệu TsFile

TsFile là định dạng tệp dạng cột được thiết kế cho dữ liệu chuỗi thời gian và được sử dụng làm lớp lưu trữ gốc của Apache IoTDB. So với các định dạng cột đa dụng như Parquet, TsFile nhận thức được mô hình dữ liệu chuỗi thời gian (dấu thời gian, thiết bị và phép đo) và duy trì một chỉ mục thời gian nội bộ, cho phép loại bỏ theo khoảng thời gian mà không cần quét toàn bộ tệp.

Loader này được cung cấp dưới dạng một hướng dẫn riêng biệt vì nó không tuân theo quy ước bảng dữ liệu thông thường với mỗi dòng tương ứng một bản ghi: mỗi dòng đầu ra tương ứng với một thiết bị, và các giá trị theo từng phép đo được trả về dưới dạng các cột Arrow list<...>. Bản ánh xạ được mô tả chi tiết bên dưới.

Cài đặt

Trình nạp phụ thuộc vào gói Python tsfile:

pip install "tsfile>=2.3.0"

Mô hình dữ liệu và bố cục đầu ra

Trình nạp làm theo mô hình bảng của TsFile. Mỗi cột bảng là một trong các loại sau:

• TAG — một định danh có kiểu chuỗi; bộ giá trị TAG xác định duy nhất một device (tức là một nguồn chuỗi thời gian đơn lẻ).
• FIELD — một phép đo có giá trị thay đổi theo thời gian.
• TIME — cột dấu thời gian, mặc định có tên là time.

Loader phát ra một dòng dataset cho mỗi thiết bị. Trong một dòng, cột time và mọi cột FIELD là các cột Arrow list<...> chứa toàn bộ chuỗi thời gian của thiết bị đó, sắp xếp theo thứ tự thời gian tăng dần. Các cột TAG xuất hiện dưới dạng các cột string vô hướng.

Cụ thể, schema đầu ra có dạng:

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

Khi cùng một thiết bị xuất hiện trong nhiều tệp đầu vào của một phép tách, các khối theo từng tệp của thiết bị đó sẽ được nối và sắp xếp theo dấu thời gian trước khi được phát ra dưới dạng một hàng duy nhất. Các dấu thời gian trùng lặp cho cùng một thiết bị sẽ gây ra ValueError.

Cách sử dụng cơ bản

Tải một tệp TsFile đơn lẻ:

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

Áp dụng các tệp vào các phần chia một cách rõ ràng:

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

Bộ dữ liệu mẫu trên Hub

Một ví dụ sẵn sàng để sử dụng có sẵn tại tsfile/lotsa_data. Vì các tệp .tsfile được nhận diện tự động, bạn có thể tải chúng bằng id kho mà không cần chỉ định 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
    })
})

Mỗi hàng là một thiết bị. Cột TAG timeseries_id xác định thiết bị, trong khi time và value là các cột list<...> chứa toàn bộ chuỗi dữ liệu của thiết bị đó:

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

Chọn một bảng

Một tệp TsFile có thể chứa nhiều bảng. Khi table_name bị bỏ qua, bảng đầu tiên được tìm thấy trong tệp hợp lệ đầu tiên sẽ được sử dụng. Việc tra cứu không phân biệt chữ hoa chữ thường.

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

Chọn các cột

columns giới hạn các cột FIELD được đọc. Các cột TAG và cột time luôn được trả về vì chúng xác định thiết bị và dòng thời gian của nó. Các tên trong columns tham chiếu đến một TAG hoặc cột time sẽ bị bỏ qua một cách im lặng (chúng vẫn được phát ra như bình thường, chỉ một lần); các tên khớp với một trường vắng mặt trong mọi tệp sẽ trở thành các cột danh sách toàn null.

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

Lọc theo khoảng thời gian

start_time và end_time là các cận bao gồm; có thể bỏ qua một trong hai. Các cận này được đẩy xuống chỉ mục thời gian nội bộ của TsFile, do đó chỉ các khối dữ liệu khớp mới được đọc từ đĩa. Cả hai cận đều chấp nhận bất kỳ giá trị nào trong số:

• int — epoch thô theo timestamp_unit (mặc định là mili giây);
• datetime.datetime — các giá trị naive được hiểu là UTC, các giá trị có múi giờ được chuyển đổi sang UTC;
• datetime.date;
• ISO-8601 str, ví dụ "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",
... )

Tiến hóa schema giữa các tệp

Khi các tệp khác nhau phơi bày các cột khác nhau — chẳng hạn như một trường cảm biến mới được giới thiệu sau đó — trình nạp sẽ lấy hợp của tất cả các cột FIELD và điền các giá trị thiếu bằng null. Các kiểu FIELD số học sẽ được nâng cấp theo các quy tắc mở rộng của IoTDB (INT32 → INT64 → DOUBLE, INT32 → FLOAT → DOUBLE).

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

Xử lý tệp không thể đọc

Mặc định, đầu vào không đọc được hoặc không phải là tệp TsFile sẽ gây ra lỗi. Đặt on_bad_files thành "warn" để ghi log và tiếp tục, hoặc "skip" để bỏ qua tệp một cách im lặng.

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

Đơn vị timestamp và múi giờ

timestamp_unit (mặc định "ms", khớp với IoTDB) kiểm soát độ phân giải của cột time và cách diễn giải các cận thời gian dạng số nguyên. timestamp_tz gắn một múi giờ vào kiểu timestamp của Arrow; None (mặc định) tạo ra kiểu không có múi giờ.

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

Bộ nhớ và phân lô

Hai tham số kiểm soát việc sử dụng bộ nhớ:

• input_batch_size (mặc định 65_536) — số dòng tối đa được lấy cho mỗi Arrow batch từ TsFileReader.query_table. Giới hạn bộ nhớ đỉnh khi streaming một thiết bị duy nhất.
• output_batch_size (mặc định 32) — số lượng thiết bị được đóng gói vào mỗi Arrow record batch được chuyển đến writer. Giá trị nhỏ hơn cho phép báo cáo tiến độ phản hồi nhanh hơn; giá trị lớn hơn làm giảm chi phí xử lý cho mỗi batch.

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

Bộ nhớ đỉnh bị giới hạn bởi kích thước dữ liệu trên một thiết bị duy nhất trong quá trình chia, chứ không phải bởi kích thước tổng thể của phần chia.

Xem TsFileConfig để biết danh sách đầy đủ các tham số.