OMOP Alchemy

OMOP Alchemy provides a canonical, typed, SQLAlchemy-first representation of the OHDSI OMOP Common Data Model (CDM).

It is designed to support research-ready analytics, validation, and exploration of OMOP data using modern Python tooling, without imposing ETL conventions or execution-time side effects.

---

Design goals

OMOP Alchemy is intentionally:

• Declarative
  Defines tables, columns, relationships, and constraints

• SQLAlchemy-native
  Built for SQLAlchemy 2.x ORM usage

• Safe to import anywhere
  No implicit engine creation, no global state, no environment assumptions.

• Typed and inspectable
  Models are fully typed and introspectable for validation, tooling, and IDE support.

• Backend-agnostic
  Designed to work across PostgreSQL, SQLite, and other SQLAlchemy-supported databases.

---

What this package does not do

OMOP Alchemy deliberately avoids:

• Enforcing ETL conventions or data pipelines
• Auto-creating databases or loading vocabularies
• Imposing analytics frameworks or dashboards
• Making assumptions about deployment environments

These concerns are intentionally left to downstream tooling.

---

Core features

• SQLAlchemy ORM models for OMOP CDM tables
• Explicit foreign key and relationship definitions
• Read-only View classes for safe navigation and analytics
• Domain validation helpers for OMOP concept integrity
• CSV loading utilities for controlled ingestion and testing
• Lightweight schema and model validation against CDM specs

---

Example (concept navigation)

from omop_alchemy.model.vocabulary import ConceptView

concept = session.get(ConceptView, 320128)  # Lung cancer
concept.domain.domain_id        # "Condition"
concept.vocabulary.vocabulary_id  # "SNOMED"
concept.is_standard             # True

---

Status

This project is currently beta.

The API is stabilising, but some modules may change as real-world use cases expand. Feedback and issues are welcome.

Some additional background

This work builds on earlier research and tooling presented at the 2023 OHDSI APAC Symposium

see background paper.

---

Configuration

OMOP Alchemy reads all database connection and schema settings from oa-configurator. No .env files or ENGINE environment variables are needed.

Run once after installation:

omop-config init
omop-config configure omop_alchemy

See Configuration for full details.

---

Docker Compose

The included docker-compose.yaml provides a PostgreSQL database and a Python container with the [postgres] extra pre-installed. Default credentials work out of the box:

docker compose up

The python-alchemy service runs omop-config configure at startup and writes ~/.config/omop/config.toml on the host on first start; subsequent starts skip configuration automatically.

To override credentials, copy .env.example to .env and edit before starting:

cp .env.example .env
docker compose up