Cargar datos de TsFile

TsFile es un formato de archivo columnar diseñado para datos de series temporales y utilizado como capa de almacenamiento nativa de Apache IoTDB. En comparación con formatos columnares de uso general como Parquet, TsFile es consciente del modelo de datos de series temporales (marcas de tiempo, dispositivos y mediciones) y mantiene un índice de tiempo interno que permite la poda por rango de tiempo sin necesidad de escanear archivos completos.

Este loader se proporciona como una guía separada porque no sigue la convención tabular habitual de una fila por registro: cada fila de salida corresponde a un device y los valores por medición se devuelven como columnas Arrow list<...>. El mapeo se describe en detalle a continuación.

Instalación

El cargador depende del paquete de Python tsfile:

pip install "tsfile>=2.3.0"

Modelo de datos y disposición de la salida

El cargador sigue el modelo de tabla de TsFile. Cada columna de la tabla es una de las siguientes:

• TAG — un identificador de tipo cadena; la tupla de valores de TAG identifica de forma única un device (es decir, una única fuente de serie temporal).
• FIELD — una medición cuyo valor evoluciona con el tiempo.
• HORA — la columna de marca de tiempo, llamada time de forma predeterminada.

El cargador emite una fila de datos por dispositivo. Dentro de una fila, la columna time y cada columna FIELD son columnas Arrow list<...> que contienen la serie temporal completa de ese dispositivo, ordenada en orden ascendente de tiempo. Las columnas TAG aparecen como columnas escalares string.

Concretamente, el esquema de salida tiene la siguiente forma:

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

Cuando el mismo dispositivo aparece en varios archivos de entrada de una división, sus fragmentos por archivo se concatenan y ordenan por marca de tiempo antes de emitirse como una sola fila. Las marcas de tiempo duplicadas para el mismo dispositivo generan ValueError.

Uso básico

Cargar un solo archivo TsFile:

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

Mapear archivos a divisiones explícitamente:

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

Conjunto de datos de ejemplo en el Hub

Hay un ejemplo listo para usar disponible en tsfile/lotsa_data. Como los archivos .tsfile se reconocen automáticamente, puedes cargarlo por id de repositorio sin especificar 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
    })
})

Cada fila es un dispositivo. La columna TAG timeseries_id identifica el dispositivo, mientras que time y value son columnas list<...> que contienen la serie completa de ese dispositivo:

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

Seleccionar una tabla

Un archivo TsFile puede contener varias tablas. Cuando se omite table_name, se utiliza la primera tabla encontrada en el primer archivo válido. Las búsquedas no distinguen entre mayúsculas y minúsculas.

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

Seleccionar columnas

columns restringe las columnas FIELD que se leen. Las columnas TAG y la columna time siempre se devuelven porque identifican el dispositivo y su línea de tiempo. Los nombres en columns que se refieren a una TAG o a la columna time se ignoran silenciosamente (se emiten como de costumbre, solo una vez); los nombres que coinciden con un campo ausente en todos los archivos se convierten en columnas de lista con todos los valores nulos.

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

Filtrado por rango de tiempo

start_time y end_time son límites inclusivos; cualquiera de ellos puede omitirse. Los límites se aplican al índice de tiempo interno de TsFile, de modo que solo se leen del disco los bloques de datos que coinciden. Ambos límites aceptan cualquiera de:

• int — época bruta en timestamp_unit (por defecto, milisegundos);
• datetime.datetime — los valores sin zona horaria se interpretan como UTC y los valores con zona horaria se convierten a UTC;
• datetime.date;
• ISO-8601 str, p. ej. "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",
... )

Evolución del esquema entre archivos

Cuando diferentes archivos exponen columnas distintas, por ejemplo, cuando se introduce un campo de sensor nuevo más adelante, el cargador toma la unión de todas las columnas FIELD y rellena los valores faltantes con nulos. Los tipos numéricos FIELD se promueven siguiendo las reglas de ampliación de IoTDB (INT32 → INT64 → DOUBLE, INT32 → FLOAT → DOUBLE).

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

Gestión de archivos ilegibles

Por defecto, una entrada ilegible o no-TsFile genera un error. Establezca on_bad_files en "warn" para registrar y continuar, o en "skip" para descartar el archivo en silencio.

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

Unidad de marca de tiempo y zona horaria

timestamp_unit (por defecto "ms", en concordancia con IoTDB) controla la resolución de la columna time y la interpretación de los límites de tiempo enteros. timestamp_tz asigna una zona horaria al tipo de marca de tiempo de Arrow; None (el valor predeterminado) genera un tipo sin zona horaria.

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

Memoria y lotes

Dos parámetros controlan el uso de memoria:

• input_batch_size (valor predeterminado 65_536) — número máximo de filas obtenidas por lote de Arrow desde TsFileReader.query_table. Limita la memoria máxima mientras se transmite un solo dispositivo.
• output_batch_size (valor predeterminado 32) — número de dispositivos empaquetados en cada lote de registros Arrow entregado al escritor. Los valores más pequeños ofrecen una información de progreso más receptiva; los valores más grandes reducen la sobrecarga por lote.

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

La memoria máxima está acotada por la carga de un solo dispositivo a lo largo de la división, no por el tamaño de la división en su conjunto.

Consulte TsFileConfig para obtener la lista completa de parámetros.