File formats

.dql — the core format

Canonical, git-friendly, version-headered.

// dql-format: 1

block "Revenue by Segment" {
  domain = "finance"
  type = "custom"
  status = "draft"
  description = "Revenue by customer segment."
  owner = "analytics@company.com"
  tags = ["revenue"]

  query = """
SELECT segment, SUM(amount) AS revenue
FROM analytics.orders
GROUP BY 1
"""

  visualization {
    chart = "bar"
    x = segment
    y = revenue
  }
}

• Version header — // dql-format: N on line 1. Older files without a header are still parsed; dql fmt adds the header on next save.
• Canonical whitespace — dql fmt enforces it. CI should run dql fmt --check .
• Forward compatibility — unknown top-level keys are preserved verbatim

.dqlnb — notebook

JSON document holding a sequence of cells (markdown, sql, dql, chart). Written in a stable key-order so git diffs stay readable.

{
  "version": 1,
  "metadata": { "name": "Welcome", "createdAt": "2026-04-17T00:00:00Z" },
  "cells": [
    { "id": "c1", "type": "markdown", "source": "# Welcome" },
    { "id": "c2", "type": "sql", "source": "select 1" }
  ]
}

.run.json — run snapshots

Sibling file next to a notebook holding the last execution's results:

{
  "version": 1,
  "notebookPath": "notebooks/overview.dql",
  "capturedAt": "2026-04-15T12:34:56Z",
  "cells": [
    {
      "cellId": "abc123",
      "status": "success",
      "executionCount": 4,
      "result": { "columns": [...], "rows": [...], "rowCount": 42 }
    }
  ]
}

• Git-ignored by default — DQL auto-appends *.run.json to .gitignore on first write
• Used for rehydration — re-opening a notebook loads results without re-running queries
• Save trigger — debounced 600ms after a cell's execution count / row count changes

.dqld — App dashboard page

JSON document for one dashboard page inside an App. It stores grid layout, block refs, text tiles, per-tile visualization options, filters, and page metadata.

{
  "version": 1,
  "id": "daily-ops",
  "title": "Daily Ops",
  "layout": {
    "type": "grid",
    "columns": 12
  },
  "tiles": [
    {
      "id": "approval-rate",
      "type": "block",
      "blockRef": "card_approval_rate",
      "title": "Approval Rate",
      "layout": { "x": 0, "y": 0, "w": 4, "h": 3 },
      "viz": { "type": "kpi", "options": { "valueField": "approval_rate" } }
    }
  ]
}

Dashboard pages are committed under apps/<app-id>/dashboards/*.dqld. Private layout overrides and saved views stay local under .dql/local/.

dql.app.json — App manifest

JSON document for a local-first App package.

{
  "version": 1,
  "id": "cards-ops",
  "title": "Cards Operations",
  "domain": "cards",
  "subdomain": "fraud",
  "groups": ["daily-ops"],
  "visibility": "shared",
  "lifecycle": "draft",
  "dashboards": [
    { "id": "daily-ops", "path": "dashboards/daily-ops.dqld", "title": "Daily Ops" }
  ],
  "notebooks": [
    {
      "path": "notebooks/investigation.dqlnb",
      "title": "Investigation Notebook",
      "role": "analysis",
      "visibility": "shared"
    }
  ]
}

In OSS, visibility, domain, subdomain, groups, audience, and lifecycle are organization metadata and trust labels. They are not hosted permissions or RBAC enforcement.

dql.config.json — project config

Lives at the project root. Written by dql init and create-dql-app.

{
  "project": "jaffle-analytics",
  "connections": {
    "default": { "driver": "duckdb", "filepath": ":memory:" }
  },
  "semanticLayer": { "provider": "dql", "path": "semantic-layer" },
  "dbt": {
    "projectDir": "../dbt",
    "manifestPath": "target/manifest.json"
  },
  "governance": {
    "required_fields": ["domain", "owner", "description"]
  }
}

Fields:

• project — human-readable project name
• connections — named database connections. default is used unless a block overrides it
• semanticLayer — { provider, path, projectPath }. Providers: dql (local YAML), dbt, cubejs, snowflake
• dbt — { projectDir, manifestPath } for in-place or sibling dbt projects. dql compile and dql sync dbt read from here
• governance — required fields every block must declare to pass dql certify

dql-manifest.json — build output

Generated by dql compile. Declares every block/notebook/dashboard in the project plus their lineage edges. Consumed by OpenLineage export and third-party lineage tools.