@duckcodeailabs/dql-cli 0.7.0 → 0.8.0

package/dist/assets/templates/ecommerce/semantic-layer/metrics/avg_order_value.yaml

@@ -1,10 +0,0 @@
-name: avg_order_value
-label: Average Order Value
-description: Average revenue per order.
-domain: commerce
-sql: AVG(order_total)
-type: avg
-table: orders
-tags:
-  - revenue
-  - commerce

package/dist/assets/templates/ecommerce/semantic-layer/metrics/gmv.yaml

@@ -1,10 +0,0 @@
-name: gmv
-label: Gross Merchandise Value
-description: Total order value across the commerce sample dataset.
-domain: commerce
-sql: SUM(order_total)
-type: sum
-table: orders
-tags:
-  - revenue
-  - commerce

package/dist/assets/templates/ecommerce/semantic-layer/metrics/gross_margin.yaml

@@ -1,10 +0,0 @@
-name: gross_margin
-label: Gross Margin
-description: Average gross margin percentage across orders.
-domain: commerce
-sql: AVG(gross_margin)
-type: avg
-table: orders
-tags:
-  - profitability
-  - commerce

package/dist/assets/templates/ecommerce/semantic-layer/metrics/order_count.yaml

@@ -1,10 +0,0 @@
-name: order_count
-label: Order Count
-description: Total number of orders.
-domain: commerce
-sql: COUNT(order_id)
-type: count
-table: orders
-tags:
-  - orders
-  - commerce

package/dist/assets/templates/ecommerce/workbooks/.gitkeep

@@ -1 +0,0 @@
-

package/dist/assets/templates/finance-kpi/README.md

@@ -1,31 +0,0 @@
-# Finance KPI
-
-Smallest runnable DQL project — a single KPI block over local CSV data.
-
-## Scaffold
-
-```bash
-dql init my-project --template finance-kpi
-cd my-project
-```
-
-## What it demonstrates
-
-- Reusable `custom` block syntax
-- Local CSV-backed query execution
-- KPI visualization
-- Preview, build, and serve flow
-
-## Run it
-
-```bash
-dql doctor
-dql preview blocks/arr_kpi.dql --open
-```
-
-## Build it
-
-```bash
-dql build blocks/arr_kpi.dql
-dql serve dist/arr_kpi --open
-```

package/dist/assets/templates/finance-kpi/blocks/arr_kpi.dql

@@ -1,21 +0,0 @@
-block "ARR KPI" {
-    domain = "finance"
-    type = "custom"
-    description = "Simple ARR KPI block backed by local CSV sample data"
-    owner = "dql-example"
-    tags = ["finance", "kpi", "local-data"]
-
-    query = """
-        SELECT SUM(amount) AS arr_total
-        FROM read_csv_auto('./data/revenue.csv')
-    """
-
-    visualization {
-        chart = "kpi"
-        y = arr_total
-    }
-
-    tests {
-        assert row_count > 0
-    }
-}

package/dist/assets/templates/finance-kpi/data/revenue.csv

@@ -1,7 +0,0 @@
-month,segment,amount
-2026-01,Enterprise,120000
-2026-01,SMB,48000
-2026-02,Enterprise,132000
-2026-02,SMB,51000
-2026-03,Enterprise,141000
-2026-03,SMB,56000

package/dist/assets/templates/finance-kpi/dql.config.json

@@ -1,18 +0,0 @@
-{
-  "project": "__PROJECT_NAME__",
-  "defaultConnection": {
-    "driver": "file",
-    "filepath": ":memory:"
-  },
-  "dataDir": "./data",
-
-  "semanticLayer": {
-    "provider": "dql"
-  },
-
-  "preview": {
-    "port": 3474,
-    "open": true,
-    "theme": "dark"
-  }
-}

package/dist/assets/templates/finance-kpi/semantic-layer/.gitkeep

@@ -1 +0,0 @@
-

package/dist/assets/templates/saas/README.md

@@ -1,32 +0,0 @@
-# __PROJECT_NAME__
-
-This template packages a SaaS KPI sandbox focused on MRR, retention, and expansion. It covers recurring revenue tracking, churn pressure analysis, cohort retention, and semantic metrics for subscription businesses.
-
-## Included assets
-
-- `blocks/revenue_by_segment.dql` — MRR by plan tier
-- `blocks/churn_pressure.dql` — at-risk and churned revenue view
-- `dashboards/growth_scorecard.dql` — executive SaaS KPI dashboard
-- `data/subscriptions.csv` — recurring revenue and expansion sample data
-- `data/cohorts.csv` — cohort retention snapshot
-- `notebooks/welcome.dqlnb` — browser notebook walkthrough
-
-## Quick start
-
-```bash
-dql doctor
-dql notebook
-dql preview blocks/revenue_by_segment.dql --open
-```
-
-## What to explore
-
-- Track MRR growth and expansion by plan tier
-- Identify at-risk accounts by churn pressure signals
-- Analyze cohort retention curves over rolling periods
-
-## Next Steps
-
-- [Authoring Blocks](https://github.com/duckcodeailabs/dql/blob/main/docs/authoring-blocks.md) — promote your notebook queries into certified, reusable `.dql` blocks
-- [Semantic Layer Guide](https://github.com/duckcodeailabs/dql/blob/main/docs/semantic-layer-guide.md) — extend the included semantic layer with MRR and churn metrics
-- [Getting Started](https://github.com/duckcodeailabs/dql/blob/main/docs/getting-started.md) — connect to a cloud database or add DQL to an existing repo

package/dist/assets/templates/saas/blocks/churn_pressure.dql

@@ -1,25 +0,0 @@
-block "Churn Pressure by Segment" {
-    domain = "saas"
-    type = "custom"
-    description = "MRR currently flagged as at risk or churned"
-    tags = ["saas", "churn"]
-    owner = "template"
-
-    query = """
-        SELECT risk_bucket, ROUND(SUM(mrr), 2) AS at_risk_mrr
-        FROM read_csv_auto('./data/subscriptions.csv')
-        WHERE status != 'active' OR risk_bucket IN ('high', 'critical')
-        GROUP BY risk_bucket
-        ORDER BY at_risk_mrr DESC
-    """
-
-    visualization {
-        chart = "bar"
-        x = risk_bucket
-        y = at_risk_mrr
-    }
-
-    tests {
-        assert row_count > 0
-    }
-}

package/dist/assets/templates/saas/blocks/revenue_by_segment.dql

@@ -1,25 +0,0 @@
-block "MRR by Plan Tier" {
-    domain = "saas"
-    type = "custom"
-    description = "Monthly recurring revenue by plan tier"
-    tags = ["saas", "mrr"]
-    owner = "template"
-
-    query = """
-        SELECT plan_tier, ROUND(SUM(mrr), 2) AS revenue
-        FROM read_csv_auto('./data/subscriptions.csv')
-        WHERE status = 'active'
-        GROUP BY plan_tier
-        ORDER BY revenue DESC
-    """
-
-    visualization {
-        chart = "bar"
-        x = plan_tier
-        y = revenue
-    }
-
-    tests {
-        assert row_count > 0
-    }
-}

package/dist/assets/templates/saas/dashboards/growth_scorecard.dql

@@ -1,25 +0,0 @@
-dashboard "Growth Scorecard" {
-  chart.kpi(
-    SELECT ROUND(SUM(mrr), 2) AS active_mrr
-    FROM read_csv_auto('./data/subscriptions.csv')
-    WHERE status = 'active',
-    metrics = ["active_mrr"],
-    title = "Active MRR"
-  )
-
-  chart.line(
-    SELECT cohort_month, retained_accounts
-    FROM read_csv_auto('./data/cohorts.csv')
-    ORDER BY cohort_month,
-    x = cohort_month,
-    y = retained_accounts,
-    title = "Retained Accounts by Cohort"
-  )
-
-  chart.table(
-    SELECT account_name, owner_segment, plan_tier, status, mrr, expansion_mrr, risk_bucket
-    FROM read_csv_auto('./data/subscriptions.csv')
-    ORDER BY mrr DESC,
-    title = "Account Revenue Snapshot"
-  )
-}

package/dist/assets/templates/saas/data/cohorts.csv

@@ -1,7 +0,0 @@
-cohort_month,starting_accounts,retained_accounts,retention_rate
-2024-07,24,22,0.92
-2024-08,31,27,0.87
-2024-09,28,24,0.86
-2024-10,34,28,0.82
-2024-11,29,23,0.79
-2024-12,37,28,0.76

package/dist/assets/templates/saas/data/subscriptions.csv

@@ -1,13 +0,0 @@
-account_id,account_name,owner_segment,plan_tier,status,mrr,expansion_mrr,risk_bucket,renewal_month
-A-100,Acme Cloud,Enterprise,Enterprise,active,48000,6200,low,2025-06
-A-101,North Ridge,Mid-Market,Growth,active,18400,2400,medium,2025-05
-A-102,Blue Orbit,SMB,Starter,active,3400,200,low,2025-04
-A-103,Helio Systems,Enterprise,Enterprise,at_risk,52100,0,high,2025-03
-A-104,Vector Health,Mid-Market,Growth,active,19600,1800,medium,2025-08
-A-105,Studio Works,SMB,Starter,churned,2200,0,critical,2025-02
-A-106,SignalWare,Enterprise,Enterprise,active,43500,4100,low,2025-07
-A-107,Maple Commerce,Mid-Market,Growth,active,17100,1200,medium,2025-04
-A-108,Linea Labs,SMB,Starter,active,2800,0,medium,2025-06
-A-109,Quartz Energy,Enterprise,Enterprise,active,50300,7300,low,2025-09
-A-110,Summit Bio,Mid-Market,Growth,at_risk,15800,0,high,2025-03
-A-111,Glider Ops,SMB,Starter,active,2600,150,low,2025-05

package/dist/assets/templates/saas/dql.config.json

@@ -1,18 +0,0 @@
-{
-  "project": "__PROJECT_NAME__",
-  "defaultConnection": {
-    "driver": "file",
-    "filepath": ":memory:"
-  },
-  "dataDir": "./data",
-
-  "semanticLayer": {
-    "provider": "dql"
-  },
-
-  "preview": {
-    "port": 3474,
-    "open": true,
-    "theme": "dark"
-  }
-}

package/dist/assets/templates/saas/semantic-layer/dimensions/owner_segment.yaml

@@ -1,8 +0,0 @@
-name: owner_segment
-label: Owner Segment
-description: Account owner segment (Enterprise, Mid-Market, SMB).
-sql: owner_segment
-type: string
-table: subscriptions
-tags:
-  - saas

package/dist/assets/templates/saas/semantic-layer/dimensions/plan_tier.yaml

@@ -1,8 +0,0 @@
-name: plan_tier
-label: Plan Tier
-description: Subscription plan tier (Starter, Growth, Enterprise).
-sql: plan_tier
-type: string
-table: subscriptions
-tags:
-  - saas

package/dist/assets/templates/saas/semantic-layer/dimensions/risk_bucket.yaml

@@ -1,9 +0,0 @@
-name: risk_bucket
-label: Risk Bucket
-description: Account risk level (low, medium, high).
-sql: risk_bucket
-type: string
-table: subscriptions
-tags:
-  - saas
-  - risk

package/dist/assets/templates/saas/semantic-layer/dimensions/status.yaml

@@ -1,8 +0,0 @@
-name: status
-label: Account Status
-description: Subscription status (active, at_risk, churned).
-sql: status
-type: string
-table: subscriptions
-tags:
-  - saas

package/dist/assets/templates/saas/semantic-layer/hierarchies/account_segments.yaml

@@ -1,18 +0,0 @@
-name: account_segments
-label: Account Segments
-description: Drill from owner segment to plan tier to risk bucket.
-domain: saas
-levels:
-  - name: owner_segment
-    label: Owner Segment
-    dimension: owner_segment
-    order: 1
-  - name: plan_tier
-    label: Plan Tier
-    dimension: plan_tier
-    order: 2
-  - name: risk_bucket
-    label: Risk Bucket
-    dimension: risk_bucket
-    order: 3
-defaultRollup: sum

package/dist/assets/templates/saas/semantic-layer/metrics/account_count.yaml

@@ -1,10 +0,0 @@
-name: account_count
-label: Account Count
-description: Total number of accounts.
-domain: saas
-sql: COUNT(DISTINCT account_id)
-type: count_distinct
-table: subscriptions
-tags:
-  - accounts
-  - saas

package/dist/assets/templates/saas/semantic-layer/metrics/expansion_mrr.yaml

@@ -1,11 +0,0 @@
-name: expansion_mrr
-label: Expansion MRR
-description: Additional MRR from upsells and expansions.
-domain: saas
-sql: SUM(expansion_mrr)
-type: sum
-table: subscriptions
-tags:
-  - revenue
-  - saas
-  - growth

package/dist/assets/templates/saas/semantic-layer/metrics/mrr.yaml

@@ -1,10 +0,0 @@
-name: mrr
-label: Monthly Recurring Revenue
-description: Monthly recurring revenue across active subscriptions.
-domain: saas
-sql: SUM(mrr)
-type: sum
-table: subscriptions
-tags:
-  - revenue
-  - saas

package/dist/assets/templates/saas/workbooks/.gitkeep

@@ -1 +0,0 @@
-

package/dist/assets/templates/starter/README.md

@@ -1,48 +0,0 @@
-# __PROJECT_NAME__
-
-This starter gives you a local-first DQL project that is ready for parsing,
-previewing, notebook exploration, and experimentation.
-
-```text
-blocks/
-data/
-dql.config.json
-notebooks/
-semantic-layer/
-  metrics/
-  dimensions/
-  hierarchies/
-```
-
-## Quick Start
-
-```bash
-dql doctor
-dql notebook
-dql new block "Pipeline Health"
-dql parse blocks/pipeline_health.dql
-dql preview blocks/pipeline_health.dql --open
-dql build blocks/pipeline_health.dql
-dql serve dist/pipeline_health
-```
-
-## What's Included
-
-- `blocks/` — example charted and query-only DQL blocks
-- `data/` — sample revenue CSV for local DuckDB/file preview flows
-- `dql.config.json` — starter project configuration
-- `notebooks/welcome.dqlnb` — guided notebook walkthrough for the browser notebook
-- `semantic-layer/` — example metrics, dimensions, hierarchies, and companion metadata
-
-## Adopt the Starter Safely
-
-- start in local file mode first
-- keep sample datasets under `data/`
-- run `dql doctor` before previewing if setup feels off
-- add tests to every reusable block
-
-## Next Steps
-
-- [Getting Started](https://github.com/duckcodeailabs/dql/blob/main/docs/getting-started.md) — full install options, tutorials, and your first block
-- [Authoring Blocks](https://github.com/duckcodeailabs/dql/blob/main/docs/authoring-blocks.md) — create, validate, certify, and commit custom and semantic blocks
-- [Semantic Layer Guide](https://github.com/duckcodeailabs/dql/blob/main/docs/semantic-layer-guide.md) — define metrics, dimensions, and cubes in YAML

package/dist/assets/templates/starter/blocks/revenue_by_segment.dql

@@ -1,29 +0,0 @@
-block "Revenue by Segment" {
-    domain = "revenue"
-    type = "custom"
-    description = "Starter block for segment revenue analysis using local CSV sample data"
-    tags = ["starter", "revenue"]
-    owner = "template"
-
-    params {
-        period = "current_quarter"
-    }
-
-    query = """
-        SELECT segment_tier AS segment, SUM(amount) AS revenue
-        FROM read_csv_auto('./data/revenue.csv')
-        WHERE fiscal_period = ${period}
-        GROUP BY segment_tier
-        ORDER BY revenue DESC
-    """
-
-    visualization {
-        chart = "bar"
-        x = segment
-        y = revenue
-    }
-
-    tests {
-        assert row_count > 0
-    }
-}

package/dist/assets/templates/starter/blocks/revenue_trend_query_only.dql

@@ -1,20 +0,0 @@
-block "Revenue Trend Query" {
-    domain = "revenue"
-    type = "custom"
-    description = "Starter query-only block for monthly revenue trends using local CSV sample data"
-    tags = ["starter", "revenue", "query-only"]
-    owner = "template"
-
-    query = """
-        SELECT
-            DATE_TRUNC('month', CAST(recognized_at AS DATE)) AS revenue_month,
-            SUM(amount) AS total_revenue
-        FROM read_csv_auto('./data/revenue.csv')
-        GROUP BY 1
-        ORDER BY 1
-    """
-
-    tests {
-        assert row_count > 0
-    }
-}

package/dist/assets/templates/starter/dashboards/.gitkeep

@@ -1 +0,0 @@
-

package/dist/assets/templates/starter/data/revenue.csv

@@ -1,13 +0,0 @@
-recognized_at,segment_tier,amount,fiscal_period,fiscal_year,fiscal_quarter
-2025-01-03,Enterprise,185000,current_quarter,2025,Q1
-2025-01-14,Mid-Market,92000,current_quarter,2025,Q1
-2025-01-25,SMB,28000,current_quarter,2025,Q1
-2025-02-05,Enterprise,210000,current_quarter,2025,Q1
-2025-02-09,Mid-Market,101000,current_quarter,2025,Q1
-2025-02-18,SMB,31000,current_quarter,2025,Q1
-2025-03-02,Enterprise,223000,current_quarter,2025,Q1
-2025-03-11,Mid-Market,108000,current_quarter,2025,Q1
-2025-03-19,SMB,34000,current_quarter,2025,Q1
-2025-04-07,Enterprise,205000,next_quarter,2025,Q2
-2025-04-16,Mid-Market,99000,next_quarter,2025,Q2
-2025-04-23,SMB,29000,next_quarter,2025,Q2

package/dist/assets/templates/starter/dql.config.json

@@ -1,18 +0,0 @@
-{
-  "project": "__PROJECT_NAME__",
-  "defaultConnection": {
-    "driver": "file",
-    "filepath": ":memory:"
-  },
-  "dataDir": "./data",
-
-  "semanticLayer": {
-    "provider": "dql"
-  },
-
-  "preview": {
-    "port": 3474,
-    "open": true,
-    "theme": "dark"
-  }
-}

package/dist/assets/templates/starter/notebooks/semantic_layer_tutorial.dqlnb

@@ -1,60 +0,0 @@
-{
-  "version": 1,
-  "title": "Semantic Layer Tutorial",
-  "cells": [
-    {
-      "id": "intro_1",
-      "type": "markdown",
-      "content": "# Semantic Layer Tutorial\n\nThis notebook walks you through setting up and using the DQL semantic layer.\n\nThe semantic layer lets you define **reusable metrics, dimensions, and hierarchies** in YAML files. Once defined, they appear in the sidebar panel and can be queried via the API.\n\n---\n\n## Prerequisites\n\nMake sure your `dql.config.json` has:\n\n```json\n\"semanticLayer\": {\n  \"provider\": \"dql\"\n}\n```\n\nAnd you have YAML files in `semantic-layer/metrics/`, `semantic-layer/dimensions/`, etc."
-    },
-    {
-      "id": "check_1",
-      "type": "markdown",
-      "content": "## Step 1: Verify your data\n\nFirst, let's make sure you have data to work with. The starter template includes `data/revenue.csv`."
-    },
-    {
-      "id": "query_1",
-      "type": "sql",
-      "name": "preview_data",
-      "content": "SELECT * FROM read_csv_auto('./data/revenue.csv') LIMIT 10"
-    },
-    {
-      "id": "step2_md",
-      "type": "markdown",
-      "content": "## Step 2: Understand the YAML definitions\n\nYour `semantic-layer/` directory should contain:\n\n```\nsemantic-layer/\n├── metrics/\n│   └── revenue.yaml          # SUM(amount) as total_revenue\n├── dimensions/\n│   └── segment_tier.yaml      # segment_tier column\n├── hierarchies/\n│   └── revenue_time.yaml      # fiscal_year → fiscal_quarter drill path\n└── cubes/\n    └── revenue_cube.yaml      # groups everything into one model\n```\n\n### Metric YAML format\n```yaml\nname: total_revenue\nlabel: Total Revenue\ndescription: Sum of recognized revenue\nsql: SUM(amount)          # the SQL aggregate expression\ntype: sum                 # sum|count|count_distinct|avg|min|max\ntable: fct_revenue        # which table this metric belongs to\ntags: [revenue, kpi]\n```\n\n### Dimension YAML format\n```yaml\nname: segment_tier\nlabel: Segment Tier\nsql: segment_tier          # the column expression\ntype: string               # string|number|date|boolean\ntable: fct_revenue\n```"
-    },
-    {
-      "id": "step3_md",
-      "type": "markdown",
-      "content": "## Step 3: Query using semantic layer concepts\n\nYou can write SQL queries that use the same columns and aggregates defined in your semantic layer. The metric `total_revenue` is defined as `SUM(amount)` and the dimension `segment_tier` maps to the `segment_tier` column."
-    },
-    {
-      "id": "query_2",
-      "type": "sql",
-      "name": "revenue_by_segment",
-      "content": "-- This query mirrors the semantic layer definitions:\n-- metric: total_revenue = SUM(amount)\n-- dimension: segment_tier\nSELECT\n  segment_tier,\n  SUM(amount) AS total_revenue,\n  COUNT(*) AS deal_count,\n  AVG(amount) AS avg_deal_size\nFROM read_csv_auto('./data/revenue.csv')\nGROUP BY segment_tier\nORDER BY total_revenue DESC"
-    },
-    {
-      "id": "step4_md",
-      "type": "markdown",
-      "content": "## Step 4: Use hierarchies for drill-down\n\nThe `revenue_time` hierarchy defines a drill path: **fiscal_year → fiscal_quarter**.\n\nStart at the top level (year), then drill into quarters."
-    },
-    {
-      "id": "query_3",
-      "type": "sql",
-      "name": "revenue_by_year",
-      "content": "-- Hierarchy level 1: fiscal_year\nSELECT\n  fiscal_year,\n  SUM(amount) AS total_revenue\nFROM read_csv_auto('./data/revenue.csv')\nGROUP BY fiscal_year\nORDER BY fiscal_year"
-    },
-    {
-      "id": "query_4",
-      "type": "sql",
-      "name": "revenue_by_quarter",
-      "content": "-- Hierarchy level 2: drill into fiscal_quarter\nSELECT\n  fiscal_year,\n  fiscal_quarter,\n  SUM(amount) AS total_revenue\nFROM read_csv_auto('./data/revenue.csv')\nGROUP BY fiscal_year, fiscal_quarter\nORDER BY fiscal_year, fiscal_quarter"
-    },
-    {
-      "id": "step5_md",
-      "type": "markdown",
-      "content": "## Step 5: Explore in the sidebar\n\nClick the **Semantic Layer icon** (3rd icon in the left activity bar) to see:\n\n- **Metrics** — your defined aggregations with type badges (sum, count, avg...)\n- **Dimensions** — grouping columns with type indicators\n- **Hierarchies** — expandable drill paths\n\nYou can search and click any item to see its details.\n\n---\n\n## What's next?\n\n### Connect to dbt\nIf you have a dbt project with `semantic_models`, update `dql.config.json`:\n```json\n\"semanticLayer\": {\n  \"provider\": \"dbt\",\n  \"projectPath\": \"/path/to/your/dbt-project\"\n}\n```\n\n### Connect to Cube.js\n```json\n\"semanticLayer\": {\n  \"provider\": \"cubejs\",\n  \"projectPath\": \"/path/to/your/cube-project\"\n}\n```\n\n### Use cubes for multi-table models\nCreate `semantic-layer/cubes/my_cube.yaml` to define measures, dimensions, time dimensions, and joins all in one file. See the Reference panel (Help icon) for the full YAML format.\n\n### Full reference\nClick the **Help icon** (bottom of sidebar) → **Semantic Layer** and **Semantic Layer Providers** sections for complete YAML formats and config examples."
-    }
-  ]
-}

package/dist/assets/templates/starter/semantic-layer/blocks/revenue_by_segment.yaml

@@ -1,11 +0,0 @@
-name: revenue_by_segment
-block: revenue_by_segment
-domain: revenue
-description: Optional companion metadata for the starter block
-tags:
-  - revenue
-  - starter
-semanticMappings:
-  segment: segment_tier
-  revenue: total_revenue
-reviewStatus: draft