Esquema de almacenamiento y consultas directas

Trackio almacena cada proyecto en su propia base de datos SQLite y puede exportar esos datos a parquet para sincronización, Spaces estáticos y análisis directo. Esta página documenta el esquema SQLite en vivo, la estructura parquet derivada y el nuevo comando trackio query para ejecutar SQL de solo lectura.

Dónde se encuentra los datos

• Las bases de datos de proyectos locales se encuentran en TRACKIO_DIR, cuyo valor predeterminado es ~/.cache/huggingface/trackio.
• Cada proyecto se almacena como un archivo SQLite separado: {project}.db.
• Los medios y los archivos subidos se encuentran en TRACKIO_DIR/media/.
• Cada trazas se escribe además como un archivo de sesión de agente renderizable en Hub bajo TRACKIO_DIR/traces/ (en un Space, el prefijo traces/ del bucket). Estos son un artefacto de renderizado para el visor de trazas de agentes de Hub; la tabla traces sigue siendo la fuente de autoridad. Consulte Trazas.
• Al sincronizar con Hugging Face, Trackio exporta archivos parquet desde la base de datos SQLite antes de la carga.

Consultar datos directamente

Utilice la CLI cuando necesite una consulta general que no esté cubierta por trackio list o 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"

Añada --json para una salida legible por máquina:

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

El mismo comando funciona contra un Space remoto:

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

trackio query solo acepta consultas de solo lectura SELECT, WITH y consultas seguras de esquema PRAGMA, incluida la lectura de PRAGMA user_version.

Esquema de SQLite

El esquema en vivo se define en trackio/sqlite_storage.py mediante SQLiteStorage.init_db().

métricas

Índices:

• idx_metrics_run_step en (run_name, step)
• idx_metrics_run_timestamp en (run_name, timestamp)
• Índice parcial único idx_metrics_log_id sobre log_id
• Índice parcial idx_metrics_pending sobre space_id

configs

Índices y restricciones:

• UNIQUE(run_name)
• idx_configs_run_name en (run_name)

system_metrics

Índices:

• idx_system_metrics_run_timestamp en (run_name, timestamp)
• Índice parcial único idx_system_metrics_log_id sobre log_id
• índice parcial idx_system_metrics_pending sobre space_id

trazas

Índices:

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

project_metadata

pending_uploads

alertas

Índices:

• idx_alerts_run en (run_name)
• idx_alerts_timestamp en (timestamp)
• Índice parcial único idx_alerts_alert_id sobre alert_id

artefactos

Índices y restricciones:

• UNIQUE(name)

artifact_versions

Índices y restricciones:

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

artifact_aliases

Índices y restricciones:

• PRIMARY KEY (artifact_id, alias)

run_artifact_links

Índices y restricciones:

• CHECK(direction IN ('input', 'output'))
• idx_run_artifact_links_run en (run_id, run_name)
• idx_run_artifact_links_version en (artifact_version_id)
• Índice único idx_run_artifact_links_unique sobre (run_id, artifact_version_id, direction)

Tablas de registro

Las bases de datos de Registry, los proyectos denominados registry-<name> creados mediante Api.create_registry, contienen las tablas estándar anteriores más las cuatro tablas siguientes, definidas en trackio/registry_storage.py por RegistryStorage.init_registry_db(). Los números de versión de las colecciones provienen de collections.next_version, que solo avanza: una versión de colección nunca se reutiliza, incluso después de un unlink. Cada mutación del registro también añade una fila a registry_events en la misma transacción.

collections

collection_links

Restricciones:

• UNIQUE(collection_id, source_project, source_artifact, source_version) — una versión de origen se vincula como máximo una vez por colección
• UNIQUE(collection_id, collection_version)

collection_aliases

Restricciones:

• PRIMARY KEY (collection_id, alias) — una versión por alias por colección

registry_events

El registro es la forma autoritativa de un registro: las tablas anteriores son una proyección de este. Un registro respaldado por un bucket almacena los mismos eventos como un objeto cada uno (consulte la guía de Registro) y materializa estas tablas localmente.

Cómo se almacenan las cargas de métricas

• Las métricas de usuario se almacenan como texto JSON en metrics.metrics.
• Las métricas del sistema se almacenan como texto JSON en system_metrics.metrics.
• La configuración de ejecución se almacena como texto JSON en configs.config.
• Las API de nivel superior de Trackio deserializan estos blobs JSON antes de devolverlos.

Patrón de consulta directa común:

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

Ejemplo de introspección de esquema:

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

Distribución de Parquet

Trackio deriva archivos parquet de SQLite aplanando las columnas JSON en columnas regulares.

Exportaciones locales de parquet

SQLiteStorage.export_to_parquet() escribe:

• {project}.parquet de metrics
• {project}_system.parquet de system_metrics
• {project}_configs.parquet de configs
• {project}_traces.parquet de traces
• {project}_{table}.parquet para cada tabla de artefactos (artifacts, artifact_versions, artifact_aliases, run_artifact_links)

Los archivos parquet aplanados conservan las columnas estructurales, como timestamp, run_name y step, y luego añaden una columna por cada clave encontrada en la carga JSON.

Espacio estático y exportaciones de conjuntos de datos

SQLiteStorage.export_for_static_space() escribe:

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

La implementación estática copia los archivos multimedia a media/ y los blobs de artefactos a artifacts/blobs/sha256/{prefix}/{digest} junto a estas exportaciones, de modo que el panel de control solo para navegador pueda servir las descargas de artefactos directamente desde el conjunto de datos o el bucket.

Este es el diseño utilizado para los Spaces estáticos y los conjuntos de datos exportados.

Ejemplos de consultas útiles

Listar tablas:

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

Encuentra el paso más reciente de cada ejecución:

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"

Inspeccionar alertas recientes:

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

Inspeccionar las configuraciones almacenadas:

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

Versiones de esquema y migraciones

Cada base de datos de proyecto registra su versión de esquema en PRAGMA user_version:

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

SQLiteStorage.init_db() actualiza la base de datos hasta la SCHEMA_VERSION (definida en trackio/sqlite_storage.py) cada vez que se abre para escritura, y un servidor de Trackio migra la base de datos de cada proyecto al iniciar. Las bases de datos escritas antes de que existiera el control de versiones informan la versión 0 y se actualizan a la versión 1 mediante las sentencias aditivas CREATE TABLE IF NOT EXISTS y ALTER TABLE ... ADD COLUMN en init_db(). La versión 2 asigna un run_id a cada tabla con ámbito de ejecución en las bases de datos escritas antes de Trackio 0.24: esas versiones identificaban una ejecución solo por su nombre, por lo que cada nombre de ejecución se convierte en una ejecución con un nuevo identificador.

Para cambiar el esquema o reescribir datos existentes de una forma que esas sentencias no pueden expresar, añade un paso a _SCHEMA_MIGRATIONS e incrementa 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] actualiza una base de datos de la versión n - 1 a la n. Cada paso se ejecuta en su propio savepoint junto con su incremento de versión, por lo que un paso fallido deja la base de datos en la última versión completada. Una base de datos con una versión más reciente que la que conoce la instancia de Trackio en ejecución se deja intacta.

trackio bump se basa en esto: tras reiniciar un Space en la versión local de Trackio, comprueba que cada base de datos de proyecto informe de la SCHEMA_VERSION local. La prueba e2e en tests/e2e-spaces/test_space_bump.py ejecuta cada migración contra los datos escritos por Trackio 0.21.0 y 0.37.1.

Notas sobre la estabilidad

Trackio aún está en beta. El esquema está documentado aquí para que las personas y los agentes puedan consultarlo directamente, pero las versiones futuras pueden evolucionar el esquema y requerir migraciones o bases de datos locales regeneradas.