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

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

AltarDocker Stack Running MongoDB instance with Sacred experiments. Best used with the full AltarDocker stack.
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: With AltarDocker (recommended)

cd AltarDocker
docker compose --profile extractor up -d

Open http://localhost:8050 and connect with host mongo.

2

Option B: Standalone

cd AltarExtractor
python -m venv .venv
.venv\Scripts\activate  # Windows
pip install -r requirements.txt
python app.py

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

3

Connect to MongoDB

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

Environment variables

PORT Port the app listens on (default: 8050)
SACRED_DB_NAME Default database name (default: sacred)

Related tools

AltarDocker

Deploy MongoDB, MinIO, Omniboard, and AltarExtractor with Docker Compose.

Learn more →

AltarSender

Send experiments to Sacred and 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 app.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

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 app.py (see fetch_sacred_experiment_names function).

  • AltarDocker — Deploy MongoDB, MinIO, Omniboard, and AltarExtractor
  • AltarSender — GUI to send experiments to Sacred