Metadata-Version: 2.4
Name: madako
Version: 0.1.1
Summary: Madako: a local-first catalog combining dbt metadata with data profiles.
Project-URL: Documentation, https://github.com/kohei0128/madako#readme
Project-URL: Issues, https://github.com/kohei0128/madako/issues
Project-URL: Source, https://github.com/kohei0128/madako
Author: kohei0128
License-Expression: MIT
License-File: LICENSE
Keywords: bigquery,data-catalog,data-profiling,dbt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: duckdb<2,>=1.4.0
Requires-Dist: fastapi<1,>=0.116.0
Requires-Dist: pydantic<3,>=2.11.0
Requires-Dist: uvicorn<1,>=0.35.0
Description-Content-Type: text/markdown

# Madako

[![PyPI](https://img.shields.io/pypi/v/madako)](https://pypi.org/project/madako/)
[![Python](https://img.shields.io/pypi/pyversions/madako)](https://pypi.org/project/madako/)
[![CI](https://github.com/kohei0128/madako/actions/workflows/madako.yml/badge.svg)](https://github.com/kohei0128/madako/actions/workflows/madako.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/kohei0128/madako/blob/main/LICENSE)

**See what your dbt models mean—and what their data actually looks like.**

Madako is a local-first data catalog that brings dbt metadata and profiles from
your warehouse into one browser UI. Browse descriptions, tests, lineage, row
counts, missing values, distinct values, ranges, and changes across dimensions
without issuing warehouse queries from the UI.

![Madako showing dbt metadata and column profiles for a sample events model](https://raw.githubusercontent.com/kohei0128/madako/main/docs/assets/madako-overview.png)

Madako currently supports BigQuery and is experimental software in the 0.1
series.

## Why Madako

- **Meaning and data together:** keep dbt descriptions, tests, and direct
  lineage next to profiles of the underlying data.
- **Changes in context:** compare missing values and type-specific metrics by
  DATE, DATETIME, TIMESTAMP, or low-cardinality STRING dimensions.
- **Explicit query controls:** opt models into profiling and set per-relation
  maximum bytes billed in dbt YAML.
- **Local-first browsing:** save results as local Parquet files and browse them
  without triggering new BigQuery queries.

```text
dbt artifacts + BigQuery -> Madako -> local Parquet storage -> Web UI
```

## Try it in a minute

Madako requires Python 3.11 or later. The bundled sample uses synthetic data,
so this path does not require dbt, BigQuery, or the `bq` CLI.

```bash
uv tool install madako
madako build-sample --output-dir .madako
madako serve --storage-dir .madako
```

Open <http://127.0.0.1:8000>. The local API documentation is available at
<http://127.0.0.1:8000/docs>.

To install into an existing Python environment instead:

```bash
python -m pip install madako
```

## Use it with a dbt project

Profiling real data requires an installed and authenticated Google Cloud SDK
`bq` CLI. Mark the models or sources you want to profile in dbt YAML:

```yaml
models:
  - name: events
    config:
      meta:
        profiling:
          enabled: true
          dimensions: [event_date, service]
          max_bytes_billed: "1 GB"
```

Then generate dbt artifacts, profile the selected relations, and open the
catalog:

```bash
dbt docs generate
madako profile
madako serve
```

See the [English getting started guide](https://github.com/kohei0128/madako/blob/main/docs/en/getting-started.md)
for configuration, query-safety behavior, supported profiles, and the Python
API.

## Documentation

- [English getting started guide](https://github.com/kohei0128/madako/blob/main/docs/en/getting-started.md)
- [Japanese getting started guide](https://github.com/kohei0128/madako/blob/main/docs/ja/getting-started.md)
- [Documentation index](https://github.com/kohei0128/madako/blob/main/docs/README.md)

## Development

```bash
git clone https://github.com/kohei0128/madako.git
cd madako
uv sync
uv run pytest
uv build
```

See the [documentation index](https://github.com/kohei0128/madako/blob/main/docs/README.md)
for Web UI checks, storage contracts, and release procedures.

## License

[MIT License](https://github.com/kohei0128/madako/blob/main/LICENSE)
