# Cargar datos de TsFile

[TsFile](https://tsfile.apache.org/) es un formato de archivo columnar diseñado para datos de series temporales y utilizado como capa de almacenamiento nativa de [Apache IoTDB](https://iotdb.apache.org/). 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`](https://pypi.org/project/tsfile/):

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

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

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

Mapear archivos a divisiones explícitamente:

```py
>>> 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`](https://huggingface.co/datasets/tsfile/lotsa_data). Como los archivos `.tsfile` se reconocen automáticamente, puedes cargarlo por id de repositorio sin especificar `data_files`:

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

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

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

```py
>>> 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 propagan 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`.

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

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

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

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

```py
>>> 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](/docs/datasets/v5.2.0/es/package_reference/loading_methods#datasets.packaged_modules.tsfile.TsFileConfig) para obtener la lista completa de parámetros.

