Schéma de stockage et requêtes directes

Trackio stocke chaque projet dans sa propre base de données SQLite et peut exporter ces données au format parquet pour la synchronisation, les Spaces statiques et l’analyse directe. Cette page documente le schéma SQLite en direct, la structure parquet dérivée et la nouvelle commande trackio query pour exécuter des requêtes SQL en lecture seule.

Où se trouvent les données

• Les bases de données de projets locaux sont stockées dans TRACKIO_DIR, dont la valeur par défaut est ~/.cache/huggingface/trackio.
• Chaque projet est stocké dans un fichier SQLite distinct : {project}.db.
• Les médias et les fichiers téléversés se trouvent sous TRACKIO_DIR/media/.
• Each trace is additionally written as a Hub-renderable agent session file under TRACKIO_DIR/traces/ (on a Space, the bucket’s traces/ prefix). These are a rendering artifact for the Hub’s agent trace viewer; the traces table stays authoritative. See Traces.
• Lors de la synchronisation avec Hugging Face, Trackio exporte les fichiers parquet depuis la base de données SQLite avant le téléversement.

Interroger les données directement

Utilisez l’interface en ligne de commande (CLI) lorsque vous avez besoin d’une requête générique non couverte par trackio list ou trackio get :

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

Ajoutez --json pour une sortie lisible par machine :

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name" --json

La même commande fonctionne sur un Space distant :

trackio query project --project "my-project" --sql "SELECT COUNT(*) AS num_alerts FROM alerts" --space username/my-space --json

trackio query n’accepte que des requêtes en lecture seule SELECT, WITH et des requêtes PRAGMA de schéma sûres, y compris la lecture de PRAGMA user_version.

Schéma SQLite

Le schéma en direct est défini dans trackio/sqlite_storage.py par SQLiteStorage.init_db().

métriques

Index :

• idx_metrics_run_step sur (run_name, step)
• idx_metrics_run_timestamp sur (run_name, timestamp)
• idx_metrics_log_id index partiel unique sur log_id
• Index partiel idx_metrics_pending sur space_id

configs

Index et contraintes :

• UNIQUE(run_name)
• idx_configs_run_name sur (run_name)

system_metrics

Index :

• idx_system_metrics_run_timestamp sur (run_name, timestamp)
• idx_system_metrics_log_id index partiel unique sur log_id
• Index partiel idx_system_metrics_pending sur space_id

traces

Index :

• idx_traces_run_step sur (run_id, step)
• idx_traces_run_timestamp sur (run_id, timestamp)
• idx_traces_search sur search_text

project_metadata

pending_uploads

alertes

Index :

• idx_alerts_run sur (run_name)
• idx_alerts_timestamp sur (timestamp)
• idx_alerts_alert_id index partiel unique sur alert_id

artefacts

Index et contraintes :

• UNIQUE(name)

artifact_versions

Index et contraintes :

• UNIQUE(artifact_id, version)
• UNIQUE(artifact_id, manifest_digest)

artifact_aliases

Index et contraintes :

• PRIMARY KEY (artifact_id, alias)

run_artifact_links

Index et contraintes :

• CHECK(direction IN ('input', 'output'))
• idx_run_artifact_links_run sur (run_id, run_name)
• idx_run_artifact_links_version sur (artifact_version_id)
• idx_run_artifact_links_unique index unique sur (run_id, artifact_version_id, direction)

Tableaux du registre

Les bases de données Registry — des projets nommés registry-<name>, créés par Api.create_registry — contiennent les tables standard ci-dessus ainsi que les quatre tables ci-dessous, définies dans trackio/registry_storage.py par RegistryStorage.init_registry_db(). Les numéros de version des collections proviennent de collections.next_version, qui n'avance que dans un sens : une version de collection n'est jamais réutilisée, même après un unlink. Chaque modification du registre ajoute également une ligne à registry_events dans la même transaction.

collections

collection_links

Contraintes :

• UNIQUE(collection_id, source_project, source_artifact, source_version) — une version source est liée au plus une fois par collection
• UNIQUE(collection_id, collection_version)

collection_aliases

Contraintes :

• PRIMARY KEY (collection_id, alias) — une version par alias et par collection

registry_events

Le journal est la forme autoritaire d'un registre : les tableaux ci-dessus en sont un repli. Un registre adossé à un seau stocke les mêmes événements sous forme d'un objet chacun (voir le guide du Registre) et matérialise localement ces tableaux.

Comment les charges utiles des métriques sont stockées

• Les métriques utilisateur sont stockées sous forme de texte JSON dans metrics.metrics.
• Les métriques système sont stockées au format JSON dans system_metrics.metrics.
• La configuration d'exécution est stockée sous forme de texte JSON dans configs.config.
• Les API de plus haut niveau de Trackio désérialisent ces blobs JSON avant de les retourner.

Motif de requête directe courant :

trackio query project --project "my-project" --sql "SELECT timestamp, step, metrics FROM metrics WHERE run_name = 'run-1' ORDER BY step DESC LIMIT 5"

Exemple d'introspection de schéma :

trackio query project --project "my-project" --sql "PRAGMA table_info(metrics)"

Disposition Parquet

Trackio dérive des fichiers parquet à partir de SQLite en aplatissant les colonnes JSON en colonnes régulières.

Exports parquet locaux

SQLiteStorage.export_to_parquet() écrit :

• {project}.parquet à partir de metrics
• {project}_system.parquet à partir de system_metrics
• {project}_configs.parquet à partir de configs
• {project}_traces.parquet à partir de traces
• {project}_{table}.parquet pour chaque table d'artefacts (artifacts, artifact_versions, artifact_aliases, run_artifact_links)

Les fichiers parquet aplatis conservent les colonnes structurelles telles que timestamp, run_name et step, puis ajoutent une colonne pour chaque clé trouvée dans la charge utile JSON.

Espaces statiques et exports de jeux de données

SQLiteStorage.export_for_static_space() écrit :

• metrics.parquet
• aux/system_metrics.parquet
• aux/configs.parquet
• aux/traces.parquet
• aux/artifacts.parquet, aux/artifact_versions.parquet, aux/artifact_aliases.parquet et aux/run_artifact_links.parquet
• runs.json
• settings.json

Le déploiement statique copie les fichiers multimédias dans media/ et les blobs d’artefacts dans artifacts/blobs/sha256/{prefix}/{digest} aux côtés de ces exports, afin que le tableau de bord uniquement navigateur puisse servir les téléchargements d’artefacts directement depuis le jeu de données ou le bucket.

Ceci est la structure utilisée pour les Spaces statiques et les jeux de données exportés.

Exemples de requêtes utiles

Liste des tables :

trackio query project --project "my-project" --sql "SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name"

Trouver la dernière étape pour chaque exécution :

trackio query project --project "my-project" --sql "SELECT run_name, MAX(step) AS last_step FROM metrics GROUP BY run_name ORDER BY last_step DESC"

Inspecter les alertes récentes :

trackio query project --project "my-project" --sql "SELECT timestamp, run_name, level, title, step FROM alerts ORDER BY timestamp DESC LIMIT 20"

Inspecter les configurations stockées :

trackio query project --project "my-project" --sql "SELECT run_name, created_at, config FROM configs ORDER BY created_at DESC"

Versions de schéma et migrations

Chaque base de données de projet enregistre sa version de schéma dans PRAGMA user_version :

trackio query project --project "my-project" --sql "PRAGMA user_version"

SQLiteStorage.init_db() met à jour une base de données jusqu’à la version SCHEMA_VERSION (définie dans trackio/sqlite_storage.py) à chaque ouverture en écriture, et un serveur Trackio migre la base de données de chaque projet au démarrage. Les bases de données écrites avant l’introduction de la gestion des versions signalent la version 0 et sont portées à la version 1 par les instructions additives CREATE TABLE IF NOT EXISTS et ALTER TABLE ... ADD COLUMN présentes dans init_db(). La version 2 attribue un run_id à chaque table de portée « run » des bases de données écrites avant Trackio 0.24 : ces versions identifiaient un run uniquement par son nom, de sorte que chaque nom de run devient un run distinct doté d’un nouvel identifiant.

Pour modifier le schéma ou réécrire des données existantes d'une manière que ces déclarations ne peuvent pas exprimer, ajoutez une étape à _SCHEMA_MIGRATIONS et incrémentez SCHEMA_VERSION :

def _split_loss_column(cursor):
    cursor.execute("ALTER TABLE metrics ADD COLUMN loss REAL")
    cursor.execute("UPDATE metrics SET loss = json_extract(metrics, '$.loss')")


SCHEMA_VERSION = 3
_SCHEMA_MIGRATIONS = {2: _migrate_add_run_ids, 3: _split_loss_column}

_SCHEMA_MIGRATIONS[n] met à jour une base de données de la version n - 1 à la version n. Chaque étape s’exécute dans son propre savepoint, accompagnée de l’augmentation de sa version, de sorte qu’une étape échouée laisse la base de données à la dernière version complétée. Une base de données dont la version est plus récente que celle connue par l’instance Trackio en cours d’exécution est laissée intacte.

trackio bump s’appuie sur ce mécanisme : après le redémarrage d’un Space sur la version locale de Trackio, il vérifie que chaque base de données de projet signale la version locale de SCHEMA_VERSION. Le test e2e situé dans tests/e2e-spaces/test_space_bump.py exécute chaque migration sur des données écrites par Trackio 0.21.0 et 0.37.1.

Notes sur la stabilité

Trackio est encore en version bêta. Le schéma est documenté ici afin que les humains et les agents puissent l’interroger directement, mais les futures versions peuvent faire évoluer le schéma et nécessiter des migrations ou la régénération des bases de données locales.