Carregar dados TsFile

TsFile é um formato de arquivo colunar projetado para dados de séries temporais e usado como a camada de armazenamento nativa do Apache IoTDB. 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:

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 daquele dispositivo, ordenada em ordem crescente de tempo. As colunas TAG aparecem como colunas escalares string.

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

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:

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

Mapeie arquivos para splits explicitamente:

>>> 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. Como os arquivos .tsfile são reconhecidos automaticamente, você pode carregá-lo pelo id do repositório sem 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 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:

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

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

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

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

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

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

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

>>> 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 para a lista completa de parâmetros.