저장 스키마 및 직접 쿼리

Trackio는 각 프로젝트를 자체 SQLite 데이터베이스에 저장하며, 동기화, 정적 Spaces, 직접 분석을 위해 해당 데이터를 parquet로 내보낼 수 있습니다. 이 페이지는 실시간 SQLite 스키마, 파생된 parquet 레이아웃, 읽기 전용 SQL을 실행하는 새로운 trackio query 명령어를 문서화합니다.

데이터가 저장되는 위치

• 로컬 프로젝트 데이터베이스는 TRACKIO_DIR에 저장되며, 기본값은 ~/.cache/huggingface/trackio입니다.
• 각 프로젝트는 별도의 SQLite 파일로 저장됩니다: {project}.db.
• 미디어 및 업로드된 파일은 TRACKIO_DIR/media/ 아래에 저장됩니다.
• 각 trace는 TRACKIO_DIR/traces/ 아래에 Hub에서 렌더링 가능한 에이전트 세션 파일로 추가 기록됩니다(Space의 경우, 버킷의 traces/ 접두사). 이는 Hub의 에이전트 trace 뷰어를 위한 렌더링 산출물이며, traces 테이블이 여전히 권위 있는 출처입니다. Traces를 참조하세요.
• Hugging Face에 동기화할 때, Trackio는 업로드 전에 SQLite 데이터베이스에서 parquet 파일을 내보냅니다.

데이터 직접 쿼리

trackio list 또는 trackio get으로 이미 처리되지 않는 포괄적인 쿼리가 필요할 때 CLI를 사용하세요:

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"

기계 가독성 있는 출력을 위해 --json을 추가합니다:

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

동일한 명령은 원격 Space에도 적용됩니다:

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

trackio query는 읽기 전용 SELECT, WITH 및 안전한 스키마 PRAGMA 쿼리만 허용하며, PRAGMA user_version 읽기도 포함됩니다.

SQLite 스키마

라이브 스키마는 trackio/sqlite_storage.py의 SQLiteStorage.init_db()에서 정의됩니다.

metrics

인덱스:

• (run_name, step)에 대한 idx_metrics_run_step
• (run_name, timestamp)에 대한 idx_metrics_run_timestamp
• log_id에 대한 idx_metrics_log_id 유니크 부분 인덱스
• space_id에 대한 idx_metrics_pending 부분 인덱스

configs

인덱스 및 제약 조건:

• UNIQUE(run_name)
• (run_name)에 대한 idx_configs_run_name

system_metrics

인덱스:

• (run_name, timestamp)에 대한 idx_system_metrics_run_timestamp
• log_id에 대한 idx_system_metrics_log_id 유니크 부분 인덱스
• space_id에 대한 idx_system_metrics_pending 부분 인덱스

트레이스

인덱스:

• (run_id, step)에 대한 idx_traces_run_step
• (run_id, timestamp)에 대한 idx_traces_run_timestamp
• search_text에 대한 idx_traces_search

project_metadata

pending_uploads

알림

인덱스:

• (run_name)에 대한 idx_alerts_run
• (timestamp)에 대한 idx_alerts_timestamp
• alert_id에 대한 idx_alerts_alert_id 고유 부분 인덱스

artifacts

인덱스 및 제약 조건:

• UNIQUE(name)

artifact_versions

인덱스 및 제약 조건:

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

artifact_aliases

인덱스 및 제약 조건:

• PRIMARY KEY (artifact_id, alias)

run_artifact_links

인덱스 및 제약 조건:

• CHECK(direction IN ('input', 'output'))
• (run_id, run_name)에 대한 idx_run_artifact_links_run
• (artifact_version_id)에 대한 idx_run_artifact_links_version
• (run_id, artifact_version_id, direction)에 대한 idx_run_artifact_links_unique 유니크 인덱스

레지스트리 테이블

Registry 데이터베이스 — registry-<name>으로 명명된 프로젝트, Api.create_registry로 생성됨 —에는 위의 표준 테이블 외에 trackio/registry_storage.py의 RegistryStorage.init_registry_db()에서 정의된 아래 네 개의 테이블이 포함됩니다. 컬렉션 버전 번호는 collections.next_version에서 가져오며, 이는 오직 앞으로만 진행됩니다: 컬렉션 버전은 unlink 이후에도 재사용되지 않습니다. 모든 registry 변경 작업은 동일한 트랜잭션에서 registry_events에 행을 추가합니다.

collections

collection_links

제약 조건:

• UNIQUE(collection_id, source_project, source_artifact, source_version) — 소스 버전은 각 컬렉션당 최대 한 번만 연결됩니다
• UNIQUE(collection_id, collection_version)

collection_aliases

제약 조건:

• PRIMARY KEY (collection_id, alias) — 컬렉션당 별칭당 버전 하나

registry_events

로그는 레지스트리의 공식적인 형태이며, 위의 테이블은 이를 집계한 것입니다. 버킷 기반 레지스트리는 동일한 이벤트를 각 이벤트마다 하나의 객체로 저장하며(Registry 가이드 참조), 이러한 테이블을 로컬에 구현합니다.

메트릭 페이로드 저장 방식

• 사용자 메트릭은 metrics.metrics에 JSON 텍스트로 저장됩니다.
• 시스템 메트릭은 system_metrics.metrics에 JSON 텍스트로 저장됩니다.
• 실행 구성은 configs.config에 JSON 텍스트로 저장됩니다.
• Trackio의 고수준 API는 이러한 JSON 블롭을 반환하기 전에 역직렬화합니다.

일반적인 직접 쿼리 패턴:

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

스키마 인스펙션 예시:

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

Parquet 레이아웃

Trackio는 SQLite에서 JSON 컬럼을 일반 컬럼으로 평탄화하여 parquet 파일을 생성합니다.

로컬 parquet 내보내기

SQLiteStorage.export_to_parquet()은 다음을 작성합니다:

• metrics에서 {project}.parquet
• system_metrics에서 {project}_system.parquet
• configs에서 {project}_configs.parquet
• traces에서 {project}_traces.parquet
• 각 아티팩트 테이블(artifacts, artifact_versions, artifact_aliases, run_artifact_links)에 대해 {project}_{table}.parquet

평탄화된 parquet 파일에는 timestamp, run_name, step와 같은 구조적 컬럼이 유지되고, JSON 페이로드에서 발견된 각 키에 대해 하나의 컬럼이 추가됩니다.

Static Space 및 데이터셋 내보내기

SQLiteStorage.export_for_static_space()은 다음을 작성합니다:

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

Static deployment는 미디어 파일을 media/로, 아티팩트 블롭을 artifacts/blobs/sha256/{prefix}/{digest}로 복사하여 이러한 내보내기 파일과 함께 저장하므로, 브라우저 전용 대시보드가 데이터셋 또는 버킷에서 아티팩트 다운로드를 직접 제공할 수 있습니다.

…

유용한 쿼리 예시

테이블 목록:

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

각 실행(run)의 최신 스텝을 찾습니다:

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"

최근 알림 확인:

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

저장된 설정 검사:

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

Schema 버전 및 마이그레이션

각 프로젝트 데이터베이스는 PRAGMA user_version에 스키마 버전을 기록합니다:

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

SQLiteStorage.init_db()은 데이터베이스가 쓰기용으로 열릴 때마다 SCHEMA_VERSION(trackio/sqlite_storage.py에 정의됨)까지 업그레이드하며, Trackio 서버는 시작 시 모든 프로젝트 데이터베이스를 마이그레이션합니다. 버전 관리가 도입되기 전에 작성된 데이터베이스는 버전 0으로 보고되며, init_db()의 추가형 CREATE TABLE IF NOT EXISTS 및 ALTER TABLE ... ADD COLUMN 문장을 통해 버전 1으로 업그레이드됩니다. 버전 2는 Trackio 0.24 이전 버전에서 작성된 데이터베이스의 모든 run 스코프 테이블에 run_id를 부여합니다. 해당 이전 버전에서는 run을 이름만으로 식별했으므로, 각 run 이름은 새로운 id를 가진 하나의 run으로 변환됩니다.

_SCHEMA_MIGRATIONS에 스텝을 추가하고 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]은 데이터베이스를 n - 1 버전에서 n 버전으로 업그레이드합니다. 각 단계는 버전 증가와 함께 자체적인 savepoint에서 실행되므로, 실패한 단계가 발생하면 데이터베이스는 마지막으로 완료된 버전 상태로 유지됩니다. 실행 중인 Trackio가 인식하는 버전보다 새로운 버전의 데이터베이스는 그대로 유지됩니다.

trackio bump은 이 동작에 의존합니다. 로컬 Trackio 버전에서 Space를 재시작한 후, 모든 프로젝트 데이터베이스가 로컬 SCHEMA_VERSION을 보고하는지 확인합니다. tests/e2e-spaces/test_space_bump.py의 e2e 테스트는 Trackio 0.21.0과 0.37.1이 작성한 데이터에 대해 모든 마이그레이션을 실행합니다.

안정성 참고

Trackio는 아직 베타 단계입니다. 스키마는 here에 문서화되어 있어 사람과 에이전트가 직접 쿼리할 수 있지만, 향후 릴리스에서는 스키마가 변경되어 마이그레이션 또는 로컬 데이터베이스 재생성이 필요할 수 있습니다.