Charger des données TsFile

TsFile est un format de fichier en colonnes conçu pour les données de séries temporelles et utilisé comme couche de stockage native d'Apache IoTDB. Par rapport aux formats en colonnes généralistes tels que Parquet, TsFile prend en compte le modèle de données de séries temporelles (horodatages, appareils et mesures) et maintient un index temporel interne qui permet l'élagage par plage de temps sans balayage des fichiers entiers.

Ce chargeur est présenté dans un guide distinct car il ne suit pas la convention tabulaire habituelle d’une ligne par enregistrement : chaque ligne de sortie correspond à un device, et les valeurs par mesure sont renvoyées sous forme de colonnes Arrow list<...>. Le mapping est décrit en détail ci-dessous.

Installation

Le chargeur dépend du paquet Python tsfile :

pip install "tsfile>=2.3.0"

Modèle de données et disposition de la sortie

Le chargeur suit le modèle de table de TsFile. Chaque colonne de table est l'une des suivantes :

• TAG — un identifiant de type chaîne de caractères ; le tuple des valeurs de TAG identifie de manière unique un device (c’est-à-dire une source de séries temporelles unique).
• FIELD — une mesure dont la valeur évolue dans le temps.
• TIME — la colonne horodatée, nommée time par défaut.

Le chargeur émet une ligne de jeu de données par appareil. Au sein d’une ligne, la colonne time et chaque colonne FIELD sont des colonnes Arrow list<...> contenant la série temporelle complète de cet appareil, triée par ordre chronologique croissant. Les colonnes TAG apparaissent sous forme de colonnes scalaires string.

Concrètement, le schéma de sortie a la forme suivante :

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

Lorsqu'un même appareil apparaît dans plusieurs fichiers d'entrée d'une partition, ses segments par fichier sont concaténés et triés par horodatage avant d'être émis en tant que ligne unique. Les horodatages en double pour le même appareil déclenchent une ValueError.

Utilisation de base

Charger un fichier TsFile unique :

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

Associer explicitement les fichiers à des splits :

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

Exemple de jeu de données sur le Hub

Un exemple prêt à l’emploi est disponible dans tsfile/lotsa_data. Comme les fichiers .tsfile sont reconnus automatiquement, vous pouvez le charger par identifiant de dépôt sans spécifier 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
    })
})

Chaque ligne correspond à un appareil. La colonne TAG timeseries_id identifie l’appareil, tandis que time et value sont des colonnes list<...> contenant la série complète de cet appareil :

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

Sélectionner un tableau

Un fichier TsFile peut contenir plusieurs tables. Lorsque table_name est omis, la première table trouvée dans le premier fichier valide est utilisée. Les recherches sont insensibles à la casse.

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

Sélection de colonnes

columns restreint les colonnes FIELD qui sont lues. Les colonnes TAG et la colonne time sont toujours renvoyées car elles identifient l’appareil et sa chronologie. Les noms dans columns qui font référence à un TAG ou à la colonne time sont ignorés silencieusement (ils sont émis comme d’habitude, une seule fois) ; les noms qui correspondent à un champ absent de tous les fichiers deviennent des colonnes de listes entièrement nulles.

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

Filtrage par plage de temps

start_time et end_time sont des bornes inclusives ; l’une ou l’autre peut être omise. Les bornes sont propagées jusqu’à l’index temporel interne de TsFile, de sorte que seuls les blocs de données correspondants sont lus depuis le disque. Les deux bornes acceptent l’un des éléments suivants :

• int — époque brute en timestamp_unit (millisecondes par défaut) ;
• datetime.datetime — les valeurs naïves sont interprétées comme étant en UTC, les valeurs avec fuseau horaire sont converties en UTC ;
• datetime.date;
• ISO-8601 str, par exemple "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",
... )

Évolution du schéma entre les fichiers

Lorsque différents fichiers exposent des colonnes différentes — par exemple, si un nouveau champ de capteur est introduit plus tard — le chargeur prend l'union de toutes les colonnes FIELD et remplit les valeurs manquantes par des nulls. Les types numériques FIELD sont promus selon les règles d'élargissement d'IoTDB (INT32 → INT64 → DOUBLE, INT32 → FLOAT → DOUBLE).

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

Gestion des fichiers illisibles

Par défaut, une entrée illisible ou non-TsFile provoque une erreur. Définissez on_bad_files sur "warn" pour journaliser et continuer, ou sur "skip" pour ignorer silencieusement le fichier.

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

Unité de timestamp et fuseau horaire

timestamp_unit (par défaut "ms", conformément à IoTDB) contrôle la résolution de la colonne time et l’interprétation des bornes temporelles entières. timestamp_tz associe un fuseau horaire au type de timestamp Arrow ; None (la valeur par défaut) produit un type sans fuseau horaire.

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

Mémoire et lot

Deux paramètres contrôlent l'utilisation de la mémoire :

• input_batch_size (par défaut 65_536) — nombre maximal de lignes récupérées par lot Arrow depuis TsFileReader.query_table. Limite la mémoire maximale utilisée lors du streaming sur un seul appareil.
• output_batch_size (valeur par défaut 32) — nombre d’appareils regroupés dans chaque lot de records Arrow transmis à l’écriture. Des valeurs plus faibles offrent un suivi de progression plus réactif ; des valeurs plus élevées réduisent le surcoût par lot.

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

La mémoire maximale est limitée par la charge utile d'un seul appareil sur l'ensemble de la partition, et non par la taille de la partition dans son ensemble.

Voir TsFileConfig pour la liste complète des paramètres.