Metaxy + ClickHouse¶

Metaxy implements ClickHouseMetadataStore. It uses ClickHouse as metadata storage and versioning engine.

Installation¶

pip install 'metaxy[clickhouse]'

Struct Columns and JSON Storage¶

Metaxy uses struct columns (metaxy_provenance_by_field, metaxy_data_version_by_field) to track field-level versioning. In Python world this corresponds to dict[str, str].

How ClickHouse Handles Structs¶

ClickHouse offers multiple approaches for structured data:

Type	Description	Use Case
`JSON`	Native JSON with typed subcolumns	Improved query performance on JSON paths
`Map(K, V)`	Native key-value map	When schema is `dict[K, V]`, even better performance

Alembic Migrations¶

For Alembic migrations, use clickhouse-connect:

pip install clickhouse-connect

Alternative Community Driver

Alternatively, use the community clickhouse-sqlalchemy driver.

Alembic Integration

See Alembic setup guide for additional instructions on how to use Alembic with Metaxy.