glyf

Build visualizations the way you build pipelines.

An open source, code-first build step for charts and dashboards from your dbt models.
Define charts in SQL, compose dashboards in YAML, publish anywhere.

Install · Quickstart · How it works · CLI · Examples · Docs

  ┌──────────────────────┐   ┌──────────────────────┐   ┌──────────────────────┐
  │     dbt project      │   │     glyf sources     │   │      glyf build      │
  ├──────────────────────┤   ├──────────────────────┤   ├──────────────────────┤
  │ models/*.sql         │   │ charts     *.ggsql   │   │ resolve  ref()       │
  │ target/manifest.json │──▶│ dashboards *.yml     │──▶│ execute  SQL         │
  │ warehouse relations  │   │ macros     *.py      │   │ render   Altair      │
  └──────────────────────┘   └──────────────────────┘   └───────────┬──────────┘
                                                                    │
      ┌─────────────────────────┬───────────────────────┬───────────┘
      ▼                         ▼                       ▼
      site/index.html           charts/*.png *.svg      export --zip
      static dashboard          chart artifacts         zip for CI

The last mile

Every stage of the modern data stack has declarative, version-controlled, testable artifacts. Every stage except visualization.

Your models are versioned. Your jobs are automated. Your data quality is tested. Visualization is still the last artifact outside the pipeline.

• Dashboards live outside the workflow. Your dbt models are in Git. Your charts are usually configured in a browser, stored elsewhere, and maintained by whoever last touched the UI.
• Columns rename, charts break silently. When dbt models change, dashboard failures show up late. glyf moves chart definitions into a build step that validates earlier.
• Publishing should not require a vendor. For internal portals and product dashboards, rendered HTML and chart assets are usually enough.

glyf is artifact-driven, not dbt-runtime-driven: run dbt first, then run glyf against the resulting artifacts and relations.

Install

glyf is published on PyPI as glyf-core. The package installs the glyf command and the glyf Python module; only the distribution name differs.

uv tool install glyf-core
glyf --version

curl -fsSL https://raw.githubusercontent.com/glyf-data/glyf/main/install.sh | sh

brew tap glyf-data/glyf
brew trust --tap glyf-data/glyf
brew install glyf

pipx install glyf-core
python -m pip install glyf-core

sha256sum --check --ignore-missing checksums.txt
uv tool install ./glyf_core-<version>-cp311-abi3-<platform>.whl

Prebuilt wheels cover Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), and Windows (x86_64). They target Python 3.11+ through the stable ABI, so one wheel per platform covers every supported Python version and no Rust toolchain is needed. Upgrade with uv tool upgrade glyf-core.

Quickstart

In an existing dbt project:

glyf init      # scaffold glyf.yml, visualisations/, dashboards/
dbt build      # produce the dbt artifacts glyf reads
glyf doctor    # check artifacts, charts, and SQL execution
glyf build     # compile, render, and export the site
glyf serve     # preview it locally

doctor reports whether the dbt artifacts, chart files, and SQL execution are ready before your first build, so the first failure is a readable message rather than a stack trace.

How it works

01. Write charts in GGSQL

SQL you already know, extended with a visualization grammar. Use ref() to reference dbt models directly, exactly as a dbt model would:

SELECT month, revenue
FROM {{ ref('fct_orders') }}

VISUALISE month AS x, revenue AS y
DRAW line
LABEL title => 'Monthly Revenue'
LABEL subtitle => 'Revenue trend from dbt model'
CONFIG width => 900

glyf resolves each reference to its schema path from target/manifest.json and validates the query before it renders anything.

02. Compose dashboards in YAML

Lay charts out into sections. Use Python macros for labels, thresholds, and reusable components, so a dashboard change is a one-line diff in review:

name: executive
title: Executive Dashboard

summary:
  - "{{ ui.label_value('Owner', 'Analytics Engineering') }}"
  - "{{ ui.label_value('Generated', time.now('%Y-%m-%d %H:%M')) }}"

layout:
  columns: 3

sections:
  - title: Revenue overview
    columns: 3
    items:
      - metric:
          label: Sample revenue
          value: "$7.6k"
      - chart: revenue
        title: Monthly revenue
        width: 2

03. Build once, publish anywhere

One command resolves dbt artifacts, validates chart specs, executes chart SQL against your warehouse, renders charts with Altair, and emits files you can publish:

target/glyf/
├── compiled/     resolved chart SQL
├── charts/       rendered PNG / SVG, and chart metadata
├── data/         chart rows and Vega specs, internal and never published
├── dashboards/   generated dashboard pages
├── assets/       CSS and fonts
├── index.html    landing page
├── bundle.json   manifest of everything built
└── site/         self-contained static site  ← publish this

No BI server to maintain. Drop site/ into S3, GitHub Pages, a docs site, or a CI artifact. Publish site/ rather than target/glyf/: the rest is working output, and data/ holds the raw rows.

A published site carries the data behind its charts unless you ask otherwise. See what a published site exposes.

CLI

Point any command at another project with --project-dir:

glyf build --project-dir examples/sales_dashboard

Examples

Four runnable projects live in examples/: simple_dbt, sales_dashboard, product_analytics, and finance_metrics.

uv sync
cd examples/simple_dbt
uv run dbt seed --profiles-dir . --full-refresh --no-partial-parse
uv run dbt run --profiles-dir .
uv run dbt compile --profiles-dir .
uv run glyf build
uv run glyf serve

Then open examples/simple_dbt/target/glyf/site/index.html.

Who it's for

Status

See ROADMAP.md for the longer view.

Documentation

The full docs site is built from docs-site/ and published at glyf.pages.dev. These guides are also readable directly in the repository:

Contributing

uv sync

make ci                      # the full pipeline
make ci PYTHON_VERSION=3.12  # against a specific Python

cd docs-site
npm install
npm start

Issues and pull requests are welcome. Paths in glyf.yml and dashboard YAML use forward slashes on every platform.

License

Apache 2.0