Query a boring_semantic_layer DuckDB based semantic model directly from Excel.

DuckDB file
    └── semantic_config.py (your model definitions)
            └── FastAPI server (main.py)
                    └── Excel task pane (Office Add-in)

• Python 3.11+
• uv (pip install uv or winget install astral-sh.uv)
• Microsoft Excel (Desktop)

git clone https://github.com/radders1981/bsl-excel
cd bsl-excel
uv sync

uv run python scripts/generate_demo_db.py

This creates data/tpch.duckdb with TPC-H sample data (~12 MB).

uv run python main.py

The server starts at http://localhost:8000. Verify it's running:

curl http://localhost:8000/health
# {"status":"ok"}

1. Create a folder in a location that can be shared. Eg "C:\Users<UserName>\add_ins"
2. Copy the manifest.xml file to this folder.
3. Share the folder
4. Open Excel. File -> Options -> Trust Centre -> Trust Center Settings
5. Under "Trusted Add In Catalogs", Add the share location created above. This will be in the format //ComputerName/Users//add_ins". The file path starting with a a drive letter will not be accepted. Confirm, exit hte menu back to excel.
6. Select the Developer tab (may need to enable it in options), select "Add Ins". Not "Excel Add Ins"
7. There should be a "shared folder" option containing the BSL_Excel add in. Double Click, a new option will be added to the Home ribbon.

1. Open the BSL Excel task pane
2. Enter http://localhost:8000 as the server URL and click Connect
3. Select a model (e.g. orders)
4. Check the dimensions and measures you want
5. Optionally add a filter
6. Click a cell in your sheet, then click Run Query → Sheet

Edit semantic_config.py. You need two things:

1. An ibis DuckDB connection pointing at your .duckdb file
2. One or more SemanticModel objects collected into a MODELS dict

import ibis
from boring_semantic_layer import SemanticModel

conn = ibis.duckdb.connect("data/my_data.duckdb")

sales = SemanticModel(
    table=conn.table("sales"),
    dimensions={
        "region":    lambda t: t.region,
        "category":  lambda t: t.product_category,
        "sale_date": lambda t: t.sale_date,
    },
    measures={
        "revenue":       lambda t: t.amount.sum(),
        "order_count":   lambda t: t.count(),
        "avg_order":     lambda t: t.amount.mean(),
    },
)

MODELS = {"sales": sales}

Restart the server after editing (Ctrl+C then uv run python main.py).

{
  "model": "orders",
  "dimensions": ["order_date", "status"],
  "measures": ["total_price", "order_count"],
  "filters": [
    { "dimension": "status", "op": "eq", "value": "O" }
  ],
  "limit": 1000
}

Filter operators: eq neq gt gte lt lte contains

Interactive API docs available at http://localhost:8000/docs when the server is running.

bsl-excel/
├── main.py                 # Start the API server
├── semantic_config.py      # Your semantic model definitions (edit this)
├── manifest.xml            # Excel add-in manifest (sideload into Excel)
├── pyproject.toml          # Python dependencies (managed by uv)
├── .python-version         # Python version pin
│
├── app/
│   ├── api.py              # FastAPI routes
│   └── loader.py           # Loads semantic_config.py dynamically
│
├── data/
│   └── tpch.duckdb         # Demo DuckDB database
│
├── docs/                  # Static Excel task pane (GitHub Pages)
│   ├── index.html
│   ├── taskpane.js
│   └── taskpane.css
│
└── scripts/
    └── generate_demo_db.py # One-time demo data generation

• boring-semantic-layer >= 0.3.2
• fastapi >= 0.115
• uvicorn[standard] >= 0.30
• ibis-framework[duckdb] >= 9.0

All managed automatically by uv sync.

MIT