Examples

energydb ships a Jupyter notebook demonstrating the core workflow: declare a portfolio, persist its structure, write data through targeted and bulk paths, read across the full hierarchy, round-trip the tree with renames / property edits / deletes, and link nodes with edges.

Before running the examples locally, ensure you have:

Databases: PostgreSQL (asset hierarchy + series catalog) and ClickHouse (time-series values). See Installation for setup instructions.

Environment Variables: Set your database connection strings:

# Bash/Zsh
export TIMEDB_PG_DSN='postgresql://user:password@host:port/database'
export TIMEDB_CH_URL='http://default:devpassword@localhost:8123/default'

# Fish
set -x TIMEDB_PG_DSN postgresql://user:password@host:port/database
set -x TIMEDB_CH_URL http://default:devpassword@localhost:8123/default

Jupyter: Install Jupyter to run the notebooks interactively:
```
pip install jupyter
```

Available Notebooks

Quickstart

Notebook Descriptions

Quickstart: Walks through the full energydb workflow — schema setup with Client.create(), declaring a Portfolio of wind turbines / a PV system / a battery, persisting structure with register_tree, writing data through NodeScope.write, reading across the hierarchy with subtree / type-filter / single-asset scopes, reconstructing the tree as an EnergyDataModel object, surgical edits via scope mutators (rename, update, delete, add) and batched atomically with Client.transaction(), manifest-based bulk reads in both frame and by_path output modes, edges with their own series, and cleanup. The notebook at examples/quickstart.ipynb is the source of truth and is auto-copied into docs/notebooks/ at build time.

The notebook is also runnable in Google Colab — the first cell installs PostgreSQL and ClickHouse inside the Colab VM via examples/colab_setup.py so you can try energydb without a local database.