Core Concepts

DSDL and Reports

DSDL is the declarative format DbFace uses to define reports and dashboards. It describes widgets, query sources, parameters, layout, and render behavior in one place.

What DSDL is

You can think of DSDL as a structured DSL for internal analytics pages. It is parsed into a unified internal model, then executed by the renderer and query engine. In practice, DSDL lets a team move from raw SQL to a shareable report or dashboard without switching tools.

The current product supports three main execution paths:

Regular SQL blocks
source: python blocks
type: cloud_code widgets

Report vs Dashboard

Type	Best for	Structure
Report	A single KPI card, chart, pivot, or table	Usually one frontmatter block plus one SQL or Python body
Dashboard	Multiple widgets combined into one analytics page	Currently uses multi-block syntax with shared inputs and per-widget configuration

The current dashboard syntax in DbFace is still multi-block based. It does not yet use top-level kind: dashboard as the official production syntax.

Core syntax forms

The simplest DSDL

Pure SQL can be used directly. DbFace will treat it as a table-style report by default.

SELECT id, customer_name, amount
FROM orders
ORDER BY created_at DESC

Single-widget report

---
type: metric
title: Total Sales
format: currency
---
SELECT SUM(amount) AS total_sales
FROM orders

Current dashboard syntax

---
type: metric
title: Total Sales
span: 4
inputs:
  - name: date_range
    type: daterange
    label: Date Range
---
SELECT SUM(amount) AS total_sales
FROM orders
WHERE created_at BETWEEN :date_range_start AND :date_range_end
---
type: linechart
title: Sales Trend
x: day
y: sales
span: 8
---
SELECT DATE(created_at) AS day, SUM(amount) AS sales
FROM orders
WHERE created_at BETWEEN :date_range_start AND :date_range_end
GROUP BY DATE(created_at)
ORDER BY day

Inputs and parameter binding

Inputs define user-facing filters and parameter entry points. The current frontend supports text, number, date, select, and daterange.

inputs:
  - name: date_range
    type: daterange
    label: Date Range
    default: last_30_days
  - name: region
    type: select
    label: Region
    options:
      - value: ""
        label: All

In dashboards, inputs are currently extracted from the first block only. They are then shared across all widget queries.

Inputs become execution params. The SQL executor binds them safely into queries. A daterange input is automatically expanded into :name_start and :name_end.

Parameterized SQL

---
type: table
title: Orders
inputs:
  - name: status
    type: select
    options:
      - label: All
        value: ""
      - label: Paid
        value: paid
---
SELECT *
FROM orders
WHERE (:status = '' OR status = :status)

DbFace also injects system variables into execution:

:USER_ID
:USER_EMAIL
:USER_NAME
:ORG_ID

Widget types

Metric

Single KPI widgets with support for field, format, prefix, suffix, compare_sql, and trend_sql.

Chart

Supports line, bar, area, horizontal bar, pie, donut, funnel, scatter, heatmap, treemap, radar, and waterfall.

Table

Supports auto columns, custom labels, tag rendering, row actions, cell click actions, export, and conditional formatting.

Advanced widgets

pivot, progress, multi_metric, text, divider, list, and cloud_code are all supported.

Advanced capabilities

Pivot

---
type: pivot
title: Regional Monthly Sales
row: region
col: month
value: sales
agg: sum
---
SELECT region, month, sales
FROM monthly_region_sales

Progress

---
type: progress
title: Monthly Goal Progress
field: current_sales
target_field: target_sales
format: currency
---
SELECT 820000 AS current_sales, 1000000 AS target_sales

Multi metric

---
type: multi_metric
title: Monthly Overview
metrics:
  - field: revenue
    label: Revenue
    format: currency
  - field: orders
    label: Orders
    format: number
---
SELECT SUM(amount) AS revenue, COUNT(*) AS orders
FROM orders

Text and divider

---
type: text
title: Notes
content: |
  ### Notes
  - Data refreshes daily
  - Currency is CNY
---

---
type: divider
title: Detail Section
style: solid
---

Cloud Code

---
type: cloud_code
title: Customer Console
code_name: customer_console
span: 12
---

Cloud Code widgets resolve a saved component by code_name. They do not execute the current block as SQL. Query and mutate behavior is handled inside the Cloud Code sandbox.

Execution rules and current boundaries

Regular DSDL SQL is read-only. Dangerous statements such as DROP, DELETE, UPDATE, INSERT, and ALTER are blocked.
source: python blocks are supported for data returned from Python code.
text and divider are no-SQL widgets.
cloud_code widgets are resolved by name, not by SQL body.
Per-widget datasource and cache_ttl are supported.
The current frontend does not yet provide visible controls for schema-only input types such as textarea and checkbox.

Best practices

Define shared filters as dashboard-level inputs in the first block instead of repeating them across widgets.
Validate complex SQL in SQL Workshop before moving it into DSDL.
Keep widget responsibility narrow. One widget should express one primary view.
Use dashboards to combine multiple views and reports to focus on a single outcome.
Declare x and y explicitly for charts even though auto-inference exists.
Use Cloud Code when the page needs custom interaction or write operations.