Esquema de Armazenamento e Consultas Diretas

O Trackio armazena cada projeto em seu próprio banco de dados SQLite e pode exportar esses dados para parquet para sincronização, Spaces estáticos e análise direta. Esta página documenta o esquema SQLite ao vivo, o layout parquet derivado e o novo comando trackio query para executar SQL somente leitura.

Onde os dados ficam

• Os bancos de dados de projetos locais ficam em TRACKIO_DIR, que por padrão é ~/.cache/huggingface/trackio.
• Cada projeto é armazenado como um arquivo SQLite separado: {project}.db.
• Mídia e arquivos enviados ficam em TRACKIO_DIR/media/.
• Cada trilha é adicionalmente gravada como um arquivo de sessão de agente renderizável no Hub, localizado em TRACKIO_DIR/traces/ (em um Space, no prefixo traces/ do bucket). Esses arquivos são um artefato de renderização para o visualizador de trilhas de agentes do Hub; a tabela traces permanece como a fonte de verdade. Consulte Trilhas.
• Ao sincronizar com o Hugging Face, o Trackio exporta arquivos parquet do banco de dados SQLite antes do upload.

Consultando Dados Diretamente

Use a CLI quando precisar de uma consulta geral que ainda não esteja coberta por 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"

Adicione --json para uma saída legível por máquina:

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

O mesmo comando funciona contra um Space remoto:

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

trackio query aceita apenas consultas somente leitura SELECT, WITH e consultas seguras de esquema PRAGMA, incluindo a leitura de PRAGMA user_version.

Esquema do SQLite

O esquema ao vivo é definido em trackio/sqlite_storage.py por SQLiteStorage.init_db().

métricas

Índices:

• idx_metrics_run_step em (run_name, step)
• idx_metrics_run_timestamp em (run_name, timestamp)
• idx_metrics_log_id índice parcial único em log_id
• índice parcial idx_metrics_pending em space_id

configs

Índices e restrições:

• UNIQUE(run_name)
• idx_configs_run_name em (run_name)

system_metrics

Índices:

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

traces

Índices:

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

project_metadata

pending_uploads

alertas

Índices:

• idx_alerts_run em (run_name)
• idx_alerts_timestamp em (timestamp)
• idx_alerts_alert_id índice parcial único em alert_id

artefatos

Índices e restrições:

• UNIQUE(name)

artifact_versions

Índices e restrições:

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

artifact_aliases

Índices e restrições:

• PRIMARY KEY (artifact_id, alias)

run_artifact_links

Índices e restrições:

• CHECK(direction IN ('input', 'output'))
• idx_run_artifact_links_run em (run_id, run_name)
• idx_run_artifact_links_version em (artifact_version_id)
• idx_run_artifact_links_unique índice único em (run_id, artifact_version_id, direction)

Tabelas de registro

Bancos de dados de Registry — projetos nomeados registry-<name>, criados por Api.create_registry — contêm as tabelas padrão acima, além das quatro tabelas abaixo, definidas em trackio/registry_storage.py por RegistryStorage.init_registry_db(). Os números de versão das coleções vêm de collections.next_version, que só avança: uma versão de coleção nunca é reutilizada, mesmo após um unlink. Toda mutação no registry também adiciona uma linha a registry_events na mesma transação.

collections

collection_links

Restrições:

• UNIQUE(collection_id, source_project, source_artifact, source_version) — uma versão de origem é vinculada no máximo uma vez por coleção
• UNIQUE(collection_id, collection_version)

collection_aliases

Restrições:

• PRIMARY KEY (collection_id, alias) — uma versão por alias por coleção

registry_events

O log é a forma autoritativa de um registro: as tabelas acima são uma agregação dele. Um registro baseado em bucket armazena os mesmos eventos como um objeto cada (veja o guia de Registro) e materializa essas tabelas localmente.

Como os Cargas de Métricas São Armazenadas

• As métricas do usuário são armazenadas como texto JSON em metrics.metrics.
• As métricas do sistema são armazenadas como texto JSON em system_metrics.metrics.
• A configuração de execução é armazenada como texto JSON em configs.config.
• As APIs de nível superior do Trackio desserializam esses blobs JSON antes de retorná-los.

Padrão comum de consulta direta:

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

Exemplo de introspecção de esquema:

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

Layout Parquet

O Trackio deriva arquivos parquet do SQLite ao aplanar colunas JSON em colunas regulares.

Exportações locais em parquet

SQLiteStorage.export_to_parquet() grava:

• {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 tabela de artefatos (artifacts, artifact_versions, artifact_aliases, run_artifact_links)

Os arquivos parquet achatados mantêm as colunas estruturais, como timestamp, run_name e step, e em seguida adicionam uma coluna para cada chave encontrada no payload JSON.

Espaço Estático e exportações de dataset

SQLiteStorage.export_for_static_space() escreve:

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

A implantação estática copia os arquivos de mídia para media/ e os blobs de artefatos para artifacts/blobs/sha256/{prefix}/{digest} junto a essas exportações, para que o dashboard exclusivo para navegador possa servir os downloads de artefatos diretamente do dataset ou do bucket.

Este é o layout usado para Spaces estáticos e conjuntos de dados exportados.

Exemplos Úteis de Consultas

Listar tabelas:

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

Encontre o passo mais recente para cada execução:

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"

Inspecionar alertas recentes:

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

Inspecionar configurações armazenadas:

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

Versões de Esquema e Migrações

Cada banco de dados de projeto registra sua versão de esquema em PRAGMA user_version:

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

SQLiteStorage.init_db() atualiza um banco de dados para a versão SCHEMA_VERSION (definida em trackio/sqlite_storage.py) sempre que ele é aberto para escrita, e um servidor Trackio migra o banco de dados de cada projeto ao iniciar. Bancos de dados gravados antes da existência da versionamento relatam a versão 0 e são atualizados para a versão 1 pelas instruções aditivas CREATE TABLE IF NOT EXISTS e ALTER TABLE ... ADD COLUMN em init_db(). A versão 2 fornece um run_id para cada tabela com escopo de execução em bancos de dados gravados antes do Trackio 0.24: nessas versões, uma execução era identificada apenas pelo seu nome, de modo que cada nome de execução se torna uma execução com um novo id.

Para alterar o esquema ou reescrever dados existentes de uma forma que essas declarações não possam expressar, adicione uma etapa a _SCHEMA_MIGRATIONS e incremente 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] atualiza um banco de dados da versão n - 1 para a n. Cada etapa é executada em seu próprio savepoint junto com o aumento de sua versão, de modo que uma etapa falha deixa o banco de dados na última versão concluída. Um banco de dados em uma versão mais recente do que a conhecida pelo Trackio em execução permanece inalterado.

trackio bump depende disso: após reiniciar um Space na versão local do Trackio, ele verifica se todos os bancos de dados de projeto relatam a SCHEMA_VERSION local. O teste e2e em tests/e2e-spaces/test_space_bump.py executa todas as migrações contra dados gravados pelo Trackio 0.21.0 e 0.37.1.

Notas de Estabilidade

O Trackio ainda está em beta. O esquema está documentado aqui para que humanos e agentes possam consultá-lo diretamente, mas as próximas versões podem evoluir o esquema e exigir migrações ou a regeneração dos bancos de dados locais.