qraft-utils

Standard macro library for Qraft SQL projects.

Provides reusable SQL macros that work across DuckDB, PostgreSQL, MySQL, and Trino. Macros are plain Python functions that generate SQL strings — they are expanded at compile time by Qraft's macro system.

Installation

pip install qraft-utils
# or with uv
uv add qraft-utils

For local development from the Qraft repository:

uv pip install ./python/qraft-utils

Usage

1. Add qraft-utils to your environment (pip install or local install).
2. Reference it in your model's front-matter:

---
materialization: table
macros: [qraft_utils]
---
SELECT
    surrogate_key(customer_id, order_date) AS sk_order,
    safe_divide(revenue, order_count)      AS avg_order_value,
    cents_to_dollars(amount_cents)         AS amount_usd
FROM ref('stg_orders')

Qraft automatically injects vars["engine"] at compile time, so macros adapt their SQL output to the target database.

Available Macros

Scalar Transforms (scalar.py)

Conditions (conditions.py)

Structural (structural.py)

Date Utilities (date.py)

Engine Adaptation

Many macros produce different SQL depending on the target database. The engine is detected from vars["engine"] (injected automatically by Qraft at compile time). Supported engines:

• duckdb — DuckDB
• postgres — PostgreSQL
• mysql — MySQL / MariaDB
• trino — Trino

If the engine is not recognized, macros fall back to PostgreSQL syntax.

Local Development Without PyPI

If you are developing locally and qraft-utils is not yet on PyPI, you have two options:

Option 1: Install from the local path

uv pip install ./python/qraft-utils

Option 2: Copy the qraft_utils/ directory into your project's macros/

my_project/
  macros/
    qraft_utils/       # Copy from python/qraft-utils/qraft_utils/
      __init__.py
      scalar.py
      conditions.py
      structural.py
      date.py
      engine.py
  models/
    ...

Then reference it in your model: macros: [qraft_utils].

License

MIT