Metadata-Version: 2.4
Name: dbt-superset-sync
Version: 0.1.1
Summary: Sync dbt column descriptions ↔ Apache Superset 6.x datasets
Project-URL: Homepage, https://github.com/plinxore/dbt-superset-sync
Project-URL: Repository, https://github.com/plinxore/dbt-superset-sync
Project-URL: Issues, https://github.com/plinxore/dbt-superset-sync/issues
Project-URL: Changelog, https://github.com/plinxore/dbt-superset-sync/blob/main/CHANGELOG.md
License: MIT
License-File: LICENSE
Keywords: analytics,data,dbt,metadata,superset,sync
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# dbt-superset-sync

[![PyPI version](https://img.shields.io/pypi/v/dbt-superset-sync.svg)](https://pypi.org/project/dbt-superset-sync/)
[![CI](https://github.com/plinxore/dbt-superset-sync/actions/workflows/ci.yml/badge.svg)](https://github.com/plinxore/dbt-superset-sync/actions/workflows/ci.yml)
[![Python](https://img.shields.io/pypi/pyversions/dbt-superset-sync.svg)](https://pypi.org/project/dbt-superset-sync/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

Sync dbt column descriptions, metrics, and labels ↔ Apache Superset 6.x datasets.

Built as a drop-in replacement for [dbt-superset-lineage](https://github.com/slidoapp/dbt-superset-lineage), with full Superset 6.x compatibility and MetricFlow support.

## Features

- **Push** dbt model/column descriptions, `verbose_name` labels, and metrics → Superset datasets
- **Pull** published Superset dashboards → dbt `exposures` YAML
- **Create** missing Superset datasets directly from dbt models (`--create-missing`)
- **Certify** datasets with a certification badge in Superset (`--certify`)
- **MetricFlow** support (dbt 1.6+ semantic layer) alongside the legacy `calculation_method` format
- Column order from dbt YAML is preserved in Superset
- `--no-overwrite` to protect manually edited fields in Superset
- `--tags`, `--schemas`, `--models` filters for fine-grained control
- `init` command to auto-detect all settings and write `.env`

## Installation

```bash
pip install dbt-superset-sync
```

## Quick start

```bash
# 1. Auto-detect everything and write .env
dbt-superset-sync init

# 2. Preview what would change
dbt-superset-sync push --dry-run

# 3. Push descriptions + create missing datasets
dbt-superset-sync push --create-missing

# 4. Discover dashboards and their dbt links
dbt-superset-sync pull --list

# 5. Export selected dashboards as dbt exposures
dbt-superset-sync pull
```

## Configuration

All options can be set via environment variables or a `.env` file:

```env
SUPERSET_URL=http://localhost:8088
SUPERSET_USERNAME=admin
SUPERSET_PASSWORD=your_password

DBT_MANIFEST=/path/to/target/manifest.json
DBT_EXPOSURES_OUTPUT=/path/to/models/marts/_exposures.yml

# Auto-detected by `init`
SUPERSET_DATABASE_ID=1
SUPERSET_SYNC_SCHEMAS=gold
SUPERSET_SYNC_MODELS=dim_post,fct_account_daily
SUPERSET_SYNC_DASHBOARDS=Sales Overview,Marketing KPIs

# Owner e-mail used when creating new Superset datasets (defaults to <username>@example.com)
SUPERSET_OWNER_EMAIL=you@example.com
```

Copy `.env.example` to get started:

```bash
cp .env.example .env
```

## Push options

| Flag | Description |
|---|---|
| `--dry-run` | Preview changes without writing |
| `--create-missing` | Create Superset datasets for dbt models with no matching dataset |
| `--no-overwrite` | Skip fields already filled in Superset |
| `--certify` | Mark datasets as certified |
| `--certified-by` | Certification author (default: `dbt`) |
| `--certification-details` | Certification details text |
| `--continue-on-error` | Continue on per-model errors instead of aborting |
| `--schemas` | Filter by dbt schema (e.g. `gold`) |
| `--models` | Filter by model name (e.g. `dim_post,fct_account_daily`) |
| `--tags` | Filter by dbt tag (e.g. `marketing`) |
| `--database-id` | Superset database ID for dataset creation |

## Column labels (`verbose_name`)

Add a `meta.verbose_name` to any dbt column — it will appear as the column **label** in Superset:

```yaml
columns:
  - name: followers_count
    description: "Point-in-time follower count snapshot."
    meta:
      verbose_name: "Followers"
```

## Metrics

dbt metrics (both legacy `calculation_method` and MetricFlow `type/type_params`) are pushed as Superset dataset metrics.

Supported aggregations: `sum`, `count`, `average`, `count_distinct`, `ratio`, `derived`.

## Compatibility

| Superset | dbt | Status |
|---|---|---|
| 6.x | 1.4 – 1.5 (legacy metrics) | ✅ |
| 6.x | 1.6+ (MetricFlow) | ✅ |
| < 4.x | any | ❌ (use dbt-superset-lineage) |

## Development

```bash
git clone https://github.com/plinxore/dbt-superset-sync.git
cd dbt-superset-sync
pip install -e ".[dev]"
pytest
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for pull request guidelines.

## License

MIT
