@duckcodeailabs/dql-cli 0.3.0 → 0.5.0

package/dist/assets/dql-notebook/index.html

@@ -7,7 +7,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-_N_gerXe.js"></script>
+    <script type="module" crossorigin src="/assets/index-C7bfa1Fe.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/react-CRB3T2We.js">
     <link rel="modulepreload" crossorigin href="/assets/codemirror-CCrEt63p.js">
   </head>

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

@@ -0,0 +1,154 @@
+{
+  "_comment": "DQL Config Reference — copy sections you need into your dql.config.json",
+
+  "project": "my-project-name",
+
+  "_comment_connections": "=== CONNECTION OPTIONS ===",
+
+  "_option_1_duckdb_memory": {
+    "defaultConnection": {
+      "driver": "file",
+      "filepath": ":memory:"
+    }
+  },
+
+  "_option_2_duckdb_file": {
+    "defaultConnection": {
+      "driver": "duckdb",
+      "filepath": "./data/warehouse.duckdb"
+    }
+  },
+
+  "_option_3_snowflake": {
+    "defaultConnection": {
+      "driver": "snowflake",
+      "account": "your-account.snowflakecomputing.com",
+      "username": "your_user",
+      "password": "${SNOWFLAKE_PASSWORD}",
+      "database": "ANALYTICS",
+      "schema": "PUBLIC",
+      "warehouse": "COMPUTE_WH",
+      "role": "ANALYST"
+    }
+  },
+
+  "_option_4_bigquery": {
+    "defaultConnection": {
+      "driver": "bigquery",
+      "project": "your-gcp-project-id",
+      "dataset": "analytics",
+      "keyFilename": "./service-account.json"
+    }
+  },
+
+  "_option_5_postgres": {
+    "defaultConnection": {
+      "driver": "postgres",
+      "host": "localhost",
+      "port": 5432,
+      "database": "analytics",
+      "username": "your_user",
+      "password": "${POSTGRES_PASSWORD}"
+    }
+  },
+
+  "_option_6_sqlite": {
+    "defaultConnection": {
+      "driver": "sqlite",
+      "database": "./data/analytics.sqlite"
+    }
+  },
+
+  "_comment_semantic": "=== SEMANTIC LAYER OPTIONS ===",
+
+  "_semantic_option_1_dql_native": {
+    "semanticLayer": {
+      "provider": "dql"
+    },
+    "_directory_structure": {
+      "semantic-layer/metrics/":    "one YAML file per metric",
+      "semantic-layer/dimensions/": "one YAML file per dimension",
+      "semantic-layer/hierarchies/":"one YAML file per hierarchy",
+      "semantic-layer/cubes/":      "one YAML file per cube (groups measures + dimensions + joins)"
+    }
+  },
+
+  "_semantic_option_2_dql_custom_path": {
+    "semanticLayer": {
+      "provider": "dql",
+      "path": "./my-definitions"
+    }
+  },
+
+  "_semantic_option_3_dbt": {
+    "semanticLayer": {
+      "provider": "dbt",
+      "projectPath": "/absolute/path/to/your/dbt-project"
+    },
+    "_notes": {
+      "how_it_works": "Reads semantic_models and metrics from your dbt models/**/*.yml files",
+      "requires": "dbt 1.6+ with semantic_models defined in YAML",
+      "relative_path": "You can also use a relative path: ../my-dbt-repo"
+    }
+  },
+
+  "_semantic_option_4_cubejs": {
+    "semanticLayer": {
+      "provider": "cubejs",
+      "projectPath": "/absolute/path/to/your/cube-project"
+    },
+    "_notes": {
+      "how_it_works": "Reads cube definitions from model/ or schema/ directory",
+      "relative_path": "You can also use a relative path: ../my-cube-project"
+    }
+  },
+
+  "_semantic_option_5_dbt_remote_github": {
+    "semanticLayer": {
+      "provider": "dbt",
+      "source": "github",
+      "repoUrl": "https://github.com/your-org/dbt-metrics.git",
+      "branch": "main",
+      "subPath": "models"
+    },
+    "_notes": {
+      "how_it_works": "Clones the remote repo into ~/.dql/cache/repos/ and reads dbt semantic models from it",
+      "auth": "For private repos, set GITHUB_TOKEN environment variable",
+      "cache": "Cached for 10 minutes; use 'dql semantic pull' to force refresh"
+    }
+  },
+
+  "_semantic_option_6_cubejs_remote_gitlab": {
+    "semanticLayer": {
+      "provider": "cubejs",
+      "source": "gitlab",
+      "repoUrl": "https://gitlab.com/your-org/cube-schema.git",
+      "branch": "main",
+      "subPath": ""
+    },
+    "_notes": {
+      "auth": "For private repos, set GITLAB_TOKEN environment variable"
+    }
+  },
+
+  "_semantic_option_7_snowflake": {
+    "semanticLayer": {
+      "provider": "snowflake",
+      "projectPath": "MY_DATABASE"
+    },
+    "_notes": {
+      "how_it_works": "Introspects Snowflake semantic views (SHOW SEMANTIC VIEWS) via the active connection",
+      "requires": "Snowflake account with semantic views (CREATE SEMANTIC VIEW) and a configured Snowflake connection",
+      "projectPath_usage": "Optional: filters semantic views to a specific database"
+    }
+  },
+
+  "_comment_preview": "=== PREVIEW / NOTEBOOK OPTIONS ===",
+
+  "dataDir": "./data",
+  "preview": {
+    "port": 3474,
+    "open": true,
+    "theme": "dark"
+  }
+}

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

@@ -5,6 +5,11 @@
     "filepath": ":memory:"
   },
   "dataDir": "./data",
+
+  "semanticLayer": {
+    "provider": "dql"
+  },
+
   "preview": {
     "port": 3474,
     "open": true,

package/dist/assets/templates/ecommerce/semantic-layer/cubes/customers_cube.yaml

@@ -0,0 +1,49 @@
+# Customers cube — joinable from the orders cube.
+
+name: customers
+label: Customers Cube
+description: Customer master data.
+table: customers
+domain: commerce
+
+measures:
+  - name: customer_count
+    label: Customer Count
+    sql: COUNT(DISTINCT customer_id)
+    type: count_distinct
+  - name: avg_health_score
+    label: Average Health Score
+    sql: AVG(health_score)
+    type: avg
+
+dimensions:
+  - name: customer_name
+    label: Customer Name
+    sql: customer_name
+    type: string
+  - name: segment
+    label: Segment
+    sql: segment
+    type: string
+  - name: region
+    label: Region
+    sql: region
+    type: string
+  - name: acquisition_channel
+    label: Acquisition Channel
+    sql: acquisition_channel
+    type: string
+
+time_dimensions:
+  - name: first_order_date
+    label: First Order Date
+    sql: first_order_date
+    primary_time: true
+    granularities:
+      - month
+      - quarter
+      - year
+
+tags:
+  - commerce
+  - customers

package/dist/assets/templates/ecommerce/semantic-layer/cubes/orders_cube.yaml

@@ -0,0 +1,70 @@
+# Multi-table cube with joins — demonstrates cross-table semantic queries.
+# This cube joins orders with customers to enable queries like:
+#   "total GMV by customer health_score and region"
+
+name: orders
+label: Orders Cube
+description: E-commerce orders cube with customer join.
+table: orders
+domain: commerce
+
+measures:
+  - name: gmv
+    label: Gross Merchandise Value
+    sql: SUM(order_total)
+    type: sum
+  - name: order_count
+    label: Order Count
+    sql: COUNT(order_id)
+    type: count
+  - name: avg_order_value
+    label: Average Order Value
+    sql: AVG(order_total)
+    type: avg
+  - name: avg_margin
+    label: Average Margin
+    sql: AVG(gross_margin)
+    type: avg
+
+dimensions:
+  - name: segment
+    label: Segment
+    sql: segment
+    type: string
+  - name: channel
+    label: Channel
+    sql: channel
+    type: string
+  - name: region
+    label: Region
+    sql: region
+    type: string
+  - name: payment_method
+    label: Payment Method
+    sql: payment_method
+    type: string
+  - name: is_repeat
+    label: Repeat Customer
+    sql: is_repeat
+    type: boolean
+
+time_dimensions:
+  - name: order_date
+    label: Order Date
+    sql: order_date
+    primary_time: true
+    granularities:
+      - day
+      - week
+      - month
+      - quarter
+      - year
+
+joins:
+  - name: customers
+    type: left
+    sql: "${left}.customer_id = ${right}.customer_id"
+
+tags:
+  - commerce
+  - ecommerce

package/dist/assets/templates/ecommerce/semantic-layer/dimensions/channel.yaml

@@ -1,4 +1,8 @@
 name: channel
 label: Channel
-domain: commerce
 description: Order acquisition channel.
+sql: channel
+type: string
+table: orders
+tags:
+  - commerce

package/dist/assets/templates/ecommerce/semantic-layer/dimensions/order_date.yaml

@@ -0,0 +1,9 @@
+name: order_date
+label: Order Date
+description: Date the order was placed.
+sql: order_date
+type: date
+table: orders
+tags:
+  - commerce
+  - time

package/dist/assets/templates/ecommerce/semantic-layer/dimensions/region.yaml

@@ -0,0 +1,9 @@
+name: region
+label: Region
+description: Geographic region of the order.
+sql: region
+type: string
+table: orders
+tags:
+  - commerce
+  - geo

package/dist/assets/templates/ecommerce/semantic-layer/dimensions/segment.yaml

@@ -0,0 +1,8 @@
+name: segment
+label: Customer Segment
+description: Customer segment (Enterprise, Mid-Market, SMB).
+sql: segment
+type: string
+table: orders
+tags:
+  - commerce

package/dist/assets/templates/ecommerce/semantic-layer/hierarchies/customer_geo.yaml

@@ -0,0 +1,18 @@
+name: customer_geo
+label: Customer Geography
+description: Drill from region down to customer segment.
+domain: commerce
+levels:
+  - name: region
+    label: Region
+    dimension: region
+    order: 1
+  - name: segment
+    label: Segment
+    dimension: segment
+    order: 2
+  - name: channel
+    label: Channel
+    dimension: channel
+    order: 3
+defaultRollup: sum

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

@@ -0,0 +1,10 @@
+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,4 +1,10 @@
 name: gmv
 label: Gross Merchandise Value
-domain: commerce
 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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,10 @@
+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/saas/dql.config.json

@@ -5,6 +5,11 @@
     "filepath": ":memory:"
   },
   "dataDir": "./data",
+
+  "semanticLayer": {
+    "provider": "dql"
+  },
+
   "preview": {
     "port": 3474,
     "open": true,

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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,8 @@
+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

@@ -0,0 +1,18 @@
+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

@@ -0,0 +1,10 @@
+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

@@ -0,0 +1,11 @@
+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,4 +1,10 @@
 name: mrr
 label: Monthly Recurring Revenue
-domain: saas
 description: Monthly recurring revenue across active subscriptions.
+domain: saas
+sql: SUM(mrr)
+type: sum
+table: subscriptions
+tags:
+  - revenue
+  - saas

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

@@ -5,6 +5,11 @@
     "filepath": ":memory:"
   },
   "dataDir": "./data",
+
+  "semanticLayer": {
+    "provider": "dql"
+  },
+
   "preview": {
     "port": 3474,
     "open": true,

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

@@ -0,0 +1,60 @@
+{
+  "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/cubes/revenue_cube.yaml

@@ -0,0 +1,77 @@
+# Cube Definition — groups measures, dimensions, time dimensions, and joins
+# into a single semantic model. This is the recommended way to define
+# complex, multi-table semantic layers.
+#
+# The DQL notebook will automatically discover this cube and display
+# its measures and dimensions in the Semantic Layer sidebar panel.
+
+name: revenue
+label: Revenue Cube
+description: Core revenue analysis cube built on the starter revenue data.
+table: read_csv_auto('./data/revenue.csv')
+domain: revenue
+owner: analytics-team
+
+# Measures — aggregate calculations shown as "Metrics" in the UI
+measures:
+  - name: total_revenue
+    label: Total Revenue
+    description: Sum of all recognized revenue.
+    sql: SUM(amount)
+    type: sum
+    tags:
+      - revenue
+      - kpi
+
+  - name: deal_count
+    label: Deal Count
+    description: Number of revenue deals.
+    sql: COUNT(*)
+    type: count
+
+  - name: avg_deal_size
+    label: Average Deal Size
+    description: Average revenue per deal.
+    sql: AVG(amount)
+    type: avg
+    tags:
+      - revenue
+
+# Dimensions — grouping columns shown as "Dimensions" in the UI
+dimensions:
+  - name: segment_tier
+    label: Segment Tier
+    description: Customer segment (Enterprise, Mid-Market, SMB).
+    sql: segment_tier
+    type: string
+
+  - name: fiscal_period
+    label: Fiscal Period
+    description: Fiscal period classification.
+    sql: fiscal_period
+    type: string
+
+# Time Dimensions — date columns with granularity support (day/week/month/quarter/year)
+time_dimensions:
+  - name: recognized_at
+    label: Recognition Date
+    description: Date revenue was recognized.
+    sql: recognized_at
+    primary_time: true
+    granularities:
+      - day
+      - week
+      - month
+      - quarter
+      - year
+
+# Joins — connect this cube to other cubes for cross-table queries
+# Example (uncomment if you have a customers cube):
+# joins:
+#   - name: customers
+#     type: left
+#     sql: "${left}.customer_id = ${right}.id"
+
+tags:
+  - revenue
+  - starter

package/dist/assets/templates/starter/semantic-layer/dimensions/segment_tier.yaml

@@ -3,4 +3,4 @@ label: Segment Tier
 description: Customer segment tier
 sql: segment_tier
 type: string
-table: fct_revenue
+table: read_csv_auto('./data/revenue.csv')