# Carregar dados TsFile

[TsFile](https://tsfile.apache.org/) é um formato de arquivo colunar projetado para dados de séries temporais e usado como a camada de armazenamento nativa do [Apache IoTDB](https://iotdb.apache.org/). Em comparação com formatos colunares de uso geral, como Parquet, o TsFile é consciente do modelo de dados de séries temporais (timestamps, dispositivos e medições) e mantém um índice de tempo interno que permite a poda por intervalo de tempo sem varrer arquivos inteiros.

Este loader é fornecido como um guia separado porque não segue a convenção tabular usual de uma linha por registro: cada linha de saída corresponde a um *device*, e os valores por medição são retornados como colunas `list<...>` do Arrow. O mapeamento é descrito em detalhes abaixo.

## Instalação

O carregador depende do pacote Python [`tsfile`](https://pypi.org/project/tsfile/):

```bash
pip install "tsfile>=2.3.0"
```

## Modelo de dados e layout de saída

O carregador segue o *modelo de tabela* do TsFile. Cada coluna da tabela é uma das seguintes:

- **TAG** — um identificador do tipo string; a tupla de valores de TAG identifica de forma única um *device* (ou seja, uma única fonte de série temporal).
- **CAMPO** — uma medição cujo valor evolui ao longo do tempo.
- **HORA** — a coluna de timestamp, nomeada `time` por padrão.

O loader emite uma linha de dataset por dispositivo. Dentro de uma linha, a coluna `time` e todas as colunas FIELD são colunas Arrow `list<...>` contendo a série temporal completa do dispositivo, ordenada em ordem crescente de tempo. As colunas TAG aparecem como colunas escalares `string`.

Concretamente, o esquema de saída tem a 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>
...
```

Quando o mesmo dispositivo aparece em vários arquivos de entrada de uma divisão, seus blocos por arquivo são concatenados e ordenados por timestamp antes de serem emitidos como uma única linha. Timestamps duplicados para o mesmo dispositivo geram `ValueError`.

## Uso básico

Carregue um único TsFile:

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

Mapeie arquivos para splits explicitamente:

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

## Conjunto de dados de exemplo no Hub

Um exemplo pronto para uso está disponível em [`tsfile/lotsa_data`](https://huggingface.co/datasets/tsfile/lotsa_data). Como os arquivos `.tsfile` são reconhecidos automaticamente, você pode carregá-lo pelo id do repositório sem 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 linha é um dispositivo. A coluna TAG `timeseries_id` identifica o dispositivo, enquanto `time` e `value` são colunas `list<...>` que contêm a série completa daquele 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)]
```

## Selecionando uma tabela

Um arquivo TsFile pode conter várias tabelas. Quando `table_name` é omitido, a primeira tabela encontrada no primeiro arquivo válido é utilizada. As buscas não diferenciam maiúsculas de minúsculas.

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

## Selecionando colunas

`columns` restringe as colunas FIELD que são lidas. As colunas TAG e a coluna `time` são sempre retornadas, pois identificam o dispositivo e sua linha do tempo. Nomes em `columns` que se referem a uma TAG ou à coluna `time` são ignorados silenciosamente (eles são emitidos como de costume, apenas uma vez); nomes que correspondem a um campo ausente em todos os arquivos tornam-se colunas de lista com todos os valores nulos.

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

## Filtrando por intervalo de tempo

`start_time` e `end_time` são limites inclusivos; qualquer um deles pode ser omitido. Os limites são propagados para o índice de tempo interno do TsFile, de modo que apenas os blocos de dados correspondentes são lidos do disco. Ambos os limites aceitam qualquer um dos seguintes:

- `int` — epoch bruto em `timestamp_unit` (padrão: milissegundos);
- `datetime.datetime` — valores sem fuso horário são interpretados como UTC, valores com fuso horário são convertidos para UTC;
- `datetime.date`;
- ISO-8601 `str`, por exemplo, `"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",
... )
```

## Evolução de esquema entre arquivos

Quando diferentes arquivos expõem colunas diferentes — por exemplo, um novo campo de sensor é introduzido posteriormente — o loader assume a união de todas as colunas FIELD e preenche os valores ausentes com nulos. Os tipos numéricos FIELD são promovidos seguindo as regras de alargamento do IoTDB (`INT32 → INT64 → DOUBLE`, `INT32 → FLOAT → DOUBLE`).

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

## Tratando arquivos ilegíveis

Por padrão, uma entrada ilegível ou não-TsFile gera um erro. Defina `on_bad_files` como `"warn"` para registrar e continuar, ou `"skip"` para descartar o arquivo silenciosamente.

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

## Unidade de timestamp e fuso horário

`timestamp_unit` (padrão `"ms"`, compatível com IoTDB) controla a resolução da coluna `time` e a interpretação dos limites de tempo inteiros. `timestamp_tz` associa um fuso horário ao tipo de timestamp do Arrow; `None` (o padrão) resulta em um tipo sem fuso horário.

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

## Memória e lotes

Dois parâmetros controlam o uso de memória:

- `input_batch_size` (padrão `65_536`) — número máximo de linhas obtidas por lote Arrow de `TsFileReader.query_table`. Limita a memória de pico durante o streaming de um único dispositivo.
- `output_batch_size` (padrão `32`) — número de dispositivos agrupados em cada lote de registros Arrow enviado ao escritor. Valores menores resultam em relatórios de progresso mais responsivos; valores maiores reduzem a sobrecarga por lote.

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

A memória de pico é limitada pela carga útil de um único dispositivo ao longo da divisão, não pelo tamanho da divisão como um todo.

Veja [TsFileConfig](/docs/datasets/v5.2.0/pt/package_reference/loading_methods#datasets.packaged_modules.tsfile.TsFileConfig) para a lista completa de parâmetros.

