AltarExtractor

A Dash web app to browse Sacred experiments, filter by configuration, view metrics, and export datasets as CSV or explore in Pygwalker.

Features View source Build from source

Features

Connect to any MongoDB

Enter credentials or a MongoDB URI. Supports authentication and multiple databases.

Filter by config

Select config keys, filter by boolean, number ranges, or string values.

View metrics

Select metrics to see per-step data. Toggle between rows and columns layout.

Export as CSV

Download filtered experiments or metrics data as CSV files.

Pygwalker integration

Open datasets in Pygwalker for interactive data exploration and visualization.

Save credentials

Store connection settings in browser localStorage for quick reconnection.

What you need

MongoDB with Sacred Data A MongoDB instance containing Sacred experiments. Any deployment works (local, server, or managed).
Incense (for scripts) If you prefer Python scripts over the web UI, use Incense to query experiments programmatically.
PyGWalker Understanding AltarExtractor uses PyGWalker for interactive visualization. Knowing its features enhances your data exploration.

Quick start

1

Option A: From Source (virtual environment)

cd AltarExtractor
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS
pip install -r requirements.txt
python app.py

Open http://localhost:8050 in your browser.

2

Option B: Using Docker

cd AltarExtractor
docker-compose up -d --build

Open http://localhost:8050. Connect with your MongoDB instance.

3

Connect to MongoDB

Enter your MongoDB credentials or paste a full URI. Click Connect to start browsing experiments.

Related tools

AltarViewer

Launch Omniboard and visualize your Sacred experiments in the browser.

Learn more →

AltarSender

Map experiment folders and send runs to MongoDB in a Sacred‑compatible format; optional artifacts to MinIO.

Learn more →

Full Documentation

AltarExtractor — Sacred Experiments Browser

A Dash web app to browse Sacred experiments stored in MongoDB. Features a clean Bootstrap UI, saved credentials, config filtering, metrics visualization, and CSV export.

Features

  • Connect to any MongoDB instance with Sacred data
  • Browse experiments by name
  • Filter runs by configuration keys (boolean, number, string filters)
  • View and select metrics for detailed per-step analysis
  • Export data as CSV
  • Open datasets in Pygwalker for interactive exploration
  • Credentials saved in browser local storage

Requirements

  • Python 3.9+ recommended
  • pip

Setup (Standalone)

  1. Create and activate a virtual environment:

    Windows (PowerShell):

    python -m venv .venv
.\.venv\Scripts\Activate.ps1

    macOS/Linux:

    python3 -m venv .venv
source .venv/bin/activate

  2. Install dependencies:

    pip install -r requirements.txt

Run the app

python main.py

Open your browser to http://127.0.0.1:8050/

Usage

Connecting to MongoDB

You can either:

  • Paste a full MongoDB URI (e.g., mongodb+srv://user:pass@cluster/yourdb?authSource=admin), or
  • Fill in individual fields: host, port, username, password, and auth source

Specify the database name (defaults to sacred) and click Connect.

UI Features

  • Database credentials panel: Toggle visibility with the “Database credentials” button
  • Save credentials: Check to persist connection settings in browser localStorage
  • Config keys selection: Choose which configuration keys to display and filter by
  • Experiments table: View runs with selected config columns, sort and paginate
  • Metrics section: Select metrics to view per-step data
  • Export: Download as CSV or open in Pygwalker

AltarExtractor is integrated into the AltarDocker stack and can be deployed alongside MongoDB and Omniboard.

Start with AltarDocker

cd ../AltarDocker
docker compose --profile extractor up -d

Access at http://localhost:8050

Connect to MongoDB in Docker

When running inside AltarDocker, use these connection settings:

  • Host: mongo (Docker service name)
  • Port: 27017
  • Username: your MONGO_ROOT_USER
  • Password: your MONGO_ROOT_PASSWORD
  • Auth source: admin

See AltarDocker/DEPLOY.md for full deployment instructions.

Docker Deployment (Standalone)

Using Docker Compose

  1. Build and run: 
    docker-compose up -d --build

  2. Access the app at http://localhost:8050

  3. Stop: 
    docker-compose down

⚠️ Docker Networking Note:
If AltarExtractor and MongoDB are running in the same Docker network (e.g., via docker-compose), use the MongoDB container/service name (e.g., mongo) instead of localhost as the host.
localhost inside a container refers to the container itself, not the host machine or other containers.

Using Docker directly

  1. Build the image: 
    docker build -t altar-extractor .
  2. Run the container: 
    docker run -d -p 8050:8050 --name altar-extractor altar-extractor

  3. Access at http://localhost:8050

  4. Stop and remove: 
    docker stop altar-extractor
docker rm altar-extractor

Environment Variables

Variable Description Default
PORT Port the app listens on 8050
SACRED_DB_NAME Default database name sacred

Example:

docker run -d -p 8050:8050 -e SACRED_DB_NAME=my_db altar-extractor

Or in docker-compose.yml:

environment:
  - SACRED_DB_NAME=my_sacred_db

Customization

If your Sacred data uses a different structure than the standard runs collection with experiment.name, update the query logic in altar_extractor/services/mongo.py (see fetch_sacred_experiment_names function).