developing-in-lightdash

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Developing in Lightdash

Lightdash开发指南

Build and deploy Lightdash analytics projects. This skill covers the semantic layer (metrics, dimensions, joins) and content (charts, dashboards).

构建并部署Lightdash分析项目。本技能涵盖语义层（指标、维度、关联）和内容层（图表、仪表盘）。

When to Use

适用场景

Working with Lightdash YAML files (charts, dashboards, models as code)

Using the

lightdash

CLI (

deploy

upload

download

preview

lint

warehouse-catalog

sql

)

Defining metrics, dimensions, joins, or tables in dbt or pure Lightdash projects
Creating or editing charts and dashboards as code

Don't use for: Developing the Lightdash application itself (use the codebase CLAUDE.md), general dbt work without Lightdash metadata, or raw SQL unrelated to Lightdash models.

处理Lightdash YAML文件（图表、仪表盘、代码化模型）

使用

lightdash

CLI（

deploy

、

upload

、

download

、

preview

、

lint

、

warehouse-catalog

、

sql

）

在dbt或纯Lightdash项目中定义指标、维度、关联或表
以代码形式创建或编辑图表和仪表盘

不适用场景： 开发Lightdash应用本身（请使用代码库的CLAUDE.md）、无Lightdash元数据的通用dbt工作、或与Lightdash模型无关的原生SQL操作。

What You Can Do

可执行任务

Task	Commands	References
Create a pure Lightdash project from warehouse metadata	Use Lightdash or an already-authenticated warehouse CLI to inspect catalog metadata and aggregate profiles	Creating from a Warehouse Catalog
Discover warehouse tables and fields	`lightdash warehouse-catalog --json`	CLI Reference
Explore data warehouse values	`lightdash sql` to execute raw sql, read .csv results	CLI Reference
Define metrics & dimensions	Edit dbt YAML or Lightdash YAML	Metrics, Dimensions
Create charts	`lightdash download` , edit YAML, `lightdash upload`	Chart Types
Add period comparisons	Add PoP additional metrics to chart YAML	Period over Period
Build dashboards	`lightdash download` , edit YAML, `lightdash upload`	Dashboard Reference
Manage content as code across project and organization resources	`lightdash download` , `lightdash upload`	Content as Code
Lint yaml files	`lightdash lint`	CLI Reference
Set warehouse connection	`lightdash set-warehouse` from profiles.yml	CLI Reference
Deploy changes	`lightdash deploy` (semantic layer), `lightdash upload` (content)	CLI Reference
Test changes	`lightdash preview`	Workflows

任务	命令	参考文档
从数据仓库元数据创建纯Lightdash项目	使用Lightdash或已认证的数据仓库CLI查看目录元数据并聚合配置	Creating from a Warehouse Catalog
发现数据仓库表和字段	`lightdash warehouse-catalog --json`	CLI Reference
探索数据仓库值	`lightdash sql` 执行原生SQL，读取.csv结果	CLI Reference
定义指标与维度	编辑dbt YAML或Lightdash YAML	Metrics, Dimensions
创建图表	`lightdash download` ，编辑YAML， `lightdash upload`	Chart Types
添加周期对比	在图表YAML中添加PoP附加指标	Period over Period
构建仪表盘	`lightdash download` ，编辑YAML， `lightdash upload`	Dashboard Reference
以代码形式管理项目和组织资源中的内容	`lightdash download` , `lightdash upload`	Content as Code
校验YAML文件	`lightdash lint`	CLI Reference
设置数据仓库连接	从profiles.yml执行 `lightdash set-warehouse`	CLI Reference
部署变更	`lightdash deploy` （语义层）、 `lightdash upload` （内容层）	CLI Reference
测试变更	`lightdash preview`	Workflows

Common Mistakes

常见错误

Mistake	Consequence	Prevention
Guessing filter values	Case mismatches ( `'Payment'` vs `'payment'` ) cause charts to silently return no data	Always run `lightdash sql "SELECT DISTINCT column FROM table LIMIT 50" -o values.csv` and use exact values
Not updating dashboard tiles after renaming a chart	Dashboard tile still shows old title — `title` and `chartName` are independent overrides that do NOT auto-update	Download the dashboard, find tiles with matching `chartSlug` , update `title` and `chartName` to match
Including unused dimensions in metricQuery	"Results may be incorrect" warning — extra dimensions change SQL grouping and produce wrong numbers	Every dimension in `metricQuery.dimensions` must appear in the chart config. For cartesian: `layout.xField` , `layout.yField` , or `pivotConfig.columns`
Unsorted YAML keys	`lightdash upload` warns "unsorted YAML keys" and diffs become noisy	Always sort keys alphabetically at every nesting level — the CLI writes with `sortKeys: true`
Deploying to wrong project	Overwrites production content	Always run `lightdash config get-project` before deploying
Missing `contentType` field	Content type can't be determined without relying on directory structure	Always include `contentType: chart` , `contentType: dashboard` , or `contentType: sql_chart` at the top level

错误	后果	预防措施
猜测过滤值	大小写不匹配（如 `'Payment'` vs `'payment'` ）导致图表无数据返回	始终执行 `lightdash sql "SELECT DISTINCT column FROM table LIMIT 50" -o values.csv` 并使用精确值
重命名图表后未更新仪表盘组件	仪表盘组件仍显示旧标题—— `title` 和 `chartName` 是独立的覆盖项，不会自动更新	下载仪表盘，找到匹配 `chartSlug` 的组件，更新 `title` 和 `chartName` 使其与图表一致
在metricQuery中包含未使用的维度	出现“结果可能不正确”警告——多余维度会改变SQL分组逻辑，导致数据错误	`metricQuery.dimensions` 中的每个维度必须出现在图表配置中。对于笛卡尔图表： `layout.xField` 、 `layout.yField` 或 `pivotConfig.columns`
YAML键未排序	`lightdash upload` 提示“未排序的YAML键”，差异对比变得混乱	始终在每个嵌套层级按字母顺序排序键——CLI写入时默认 `sortKeys: true`
部署到错误项目	覆盖生产环境内容	部署前始终执行 `lightdash config get-project`
缺少 `contentType` 字段	无法依赖目录结构确定内容类型	始终在顶层包含 `contentType: chart` 、 `contentType: dashboard` 或 `contentType: sql_chart`

Before You Start

准备工作

When a task uses

lightdash download

lightdash upload

, especially for bulk edits, spaces and access, scheduled content, AI agents, users, groups, or custom roles, read and follow Content as Code first. Project and organization content require separate commands, and a default download is not a complete snapshot.

当任务涉及

lightdash download

或

lightdash upload

，尤其是批量编辑、空间与权限、定时内容、AI Agent、用户、用户组或自定义角色时，请先阅读并遵循Content as Code。项目和组织内容需要单独的命令，默认下载的内容并非完整快照。

Check Your Target Project

检查目标项目

Always verify which project you're deploying to. Deploying to the wrong project can overwrite production content.

bash

lightdash config get-project        # Show current project
lightdash config list-projects      # List available projects
lightdash config set-project --name "My Project"  # Switch project

始终验证你要部署的项目。部署到错误项目会覆盖生产环境内容。

bash

lightdash config get-project        # 显示当前项目
lightdash config list-projects      # 列出可用项目
lightdash config set-project --name "My Project"  # 切换项目

Detect Your Project Type

检测项目类型

The YAML syntax differs significantly between project types.

Type	Detection	Key Difference
dbt Project	Has `dbt_project.yml`	Metadata nested under `meta:`
dbt Fusion / dbt 1.10+	Has `dbt_project.yml` , uses dbt Fusion or dbt >= 1.10	Metadata nested under `config: meta:`
Pure Lightdash	Has `lightdash.config.yml` , no dbt	Top-level properties

bash

ls dbt_project.yml 2>/dev/null && echo "dbt project" || echo "Not dbt"
ls lightdash.config.yml 2>/dev/null && echo "Pure Lightdash" || echo "Not pure Lightdash"

dbt Fusion / dbt 1.10+: Lightdash metadata must be nested under
config: meta:
instead of
meta:
. The properties are identical — only the nesting changes. Example:
yaml
models:
  - name: orders
    config:
      meta:
        metrics:
          total_revenue:
            type: sum
            sql: "${TABLE}.amount"

不同项目类型的YAML语法差异很大。

类型	检测方式	核心差异
dbt项目	存在 `dbt_project.yml`	元数据嵌套在 `meta:` 下
dbt Fusion / dbt 1.10+	存在 `dbt_project.yml` ，使用dbt Fusion或dbt >= 1.10	元数据嵌套在 `config: meta:` 下
纯Lightdash项目	存在 `lightdash.config.yml` ，无dbt	属性位于顶层

bash

ls dbt_project.yml 2>/dev/null && echo "dbt project" || echo "Not dbt"
ls lightdash.config.yml 2>/dev/null && echo "Pure Lightdash" || echo "Not pure Lightdash"

dbt Fusion / dbt 1.10+： Lightdash元数据必须嵌套在
config: meta:
下，而非
meta:
。属性内容完全相同，仅嵌套层级不同。示例：
yaml
models:
  - name: orders
    config:
      meta:
        metrics:
          total_revenue:
            type: sum
            sql: "${TABLE}.amount"

Syntax Comparison

语法对比

dbt YAML (metadata under

meta:

yaml

models:
  - name: orders
    meta:
      metrics:
        total_revenue:
          type: sum
          sql: "${TABLE}.amount"
    columns:
      - name: status
        meta:
          dimension:
            type: string

Pure Lightdash YAML (top-level):

yaml

type: model
name: orders
sql_from: 'DB.SCHEMA.ORDERS'

metrics:
  total_revenue:
    type: sum
    sql: ${TABLE}.amount

dimensions:
  - name: status
    sql: ${TABLE}.STATUS
    type: string

dbt YAML（元数据在

meta:

下）：

yaml

models:
  - name: orders
    meta:
      metrics:
        total_revenue:
          type: sum
          sql: "${TABLE}.amount"
    columns:
      - name: status
        meta:
          dimension:
            type: string

纯Lightdash YAML（顶层属性）：

yaml

type: model
name: orders
sql_from: 'DB.SCHEMA.ORDERS'

metrics:
  total_revenue:
    type: sum
    sql: ${TABLE}.amount

dimensions:
  - name: status
    sql: ${TABLE}.STATUS
    type: string

Setting Up Warehouse Connection

设置数据仓库连接

If the project needs a different warehouse connection (e.g., switching from Postgres to BigQuery), update it from your profiles.yml:

bash

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --assume-yes

This reads credentials from profiles.yml, updates the warehouse connection on the currently selected project, and triggers a recompile. Run this before

lightdash deploy

To target a specific project:

bash

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --project <uuid> --assume-yes

如果项目需要切换数据仓库连接（例如从Postgres切换到BigQuery），请从profiles.yml更新：

bash

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --assume-yes

该命令从profiles.yml读取凭证，更新当前选中项目的数据仓库连接，并触发重新编译。请在

lightdash deploy

前执行此命令。

要指定目标项目：

bash

lightdash set-warehouse --project-dir ./dbt --profiles-dir ./profiles --project <uuid> --assume-yes

Core Workflows

核心工作流

Verify Filter Values Before Using Them

使用前验证过滤值

CRITICAL: Never guess filter values. Case mismatches (e.g.,

'Payment'

'payment'

) cause charts to silently return no data.

Filters are case-sensitive by default. The

case_sensitive

key can override this in order of priority:

Dimension metadata
Model/explore metadata

lightdash.config.yml

defaults.case_sensitive

Before writing any string filter, query actual values from the warehouse:

bash

lightdash sql "SELECT DISTINCT category FROM payments LIMIT 50" -o category_values.csv

Read the CSV and use the exact values in your filter YAML. This applies to all

equals

notEquals

filters with string values — in charts and dashboards.

关键提示：永远不要猜测过滤值。大小写不匹配（如

'Payment'

'payment'

）会导致图表无数据返回。

过滤默认区分大小写。

case_sensitive

键可按以下优先级覆盖此设置：

维度元数据
模型/探索元数据

lightdash.config.yml

中的

defaults.case_sensitive

在编写任何字符串过滤前，从数据仓库查询实际值：

bash

lightdash sql "SELECT DISTINCT category FROM payments LIMIT 50" -o category_values.csv

读取CSV文件，并在过滤YAML中使用精确值。这适用于图表和仪表盘中所有带字符串值的

equals

notEquals

过滤。

Editing Metrics & Dimensions

编辑指标与维度

Find the model YAML file (dbt:
```
models/*.yml
```
, pure Lightdash:
```
lightdash/models/*.yml
```
)
Edit metrics/dimensions using the appropriate syntax for your project type
Validate:
```
lightdash lint
```
(pure Lightdash) or
```
dbt compile
```
(dbt projects)
Deploy:
```
lightdash deploy
```

See Metrics Reference and Dimensions Reference for configuration options.

找到模型YAML文件（dbt项目：
```
models/*.yml
```
，纯Lightdash项目：
```
lightdash/models/*.yml
```
）
编辑指标/维度，使用对应项目类型的语法
验证：纯Lightdash项目执行
```
lightdash lint
```
，dbt项目执行
```
dbt compile
```
部署：
```
lightdash deploy
```

配置选项请参考Metrics Reference和Dimensions Reference。

Creating a Pure Lightdash Project from a Warehouse Catalog

从数据仓库目录创建纯Lightdash项目

When the prepared project has no usable dbt project and the task is to bootstrap a semantic layer from warehouse metadata, always read and follow Creating from a Warehouse Catalog before inspecting data or writing YAML. This applies whether warehouse access comes from the selected Lightdash project or an already-authenticated warehouse CLI such as Snowflake CLI or

bq

. Do not use that workflow when an existing dbt semantic layer can be extended.

当现有项目无可用dbt项目，且任务是从数据仓库元数据引导语义层时，在检查数据或编写YAML前，请务必阅读并遵循Creating from a Warehouse Catalog。无论数据仓库访问来自选中的Lightdash项目还是已认证的仓库CLI（如Snowflake CLI或

bq

），此规则均适用。若现有dbt语义层可扩展，则不要使用此工作流。

Editing Charts

编辑图表

Download:
```
lightdash download --charts chart-slug
```
Edit the YAML file in
```
lightdash/
```
directory
Verify filter values: If you added or changed filters, use
```
lightdash sql
```
to check actual column values (see Common Mistakes)
Update dashboard tiles: If you changed the chart's name or purpose, download any dashboards that reference it and update their tile
```
title
```
and
```
chartName
```
properties to match (see Common Mistakes)
Lint:
```
lightdash lint
```
to validate before uploading
Upload:
```
lightdash upload --charts chart-slug
```
(and any modified dashboards)

Dashboard tiles have their own titles. A

saved_chart

tile's

title

and

chartName

properties are independent overrides — they do NOT auto-update when you rename the chart. If you change a chart from "Total Revenue" to "Gross Profit" but don't update the dashboard tile, the dashboard will still display "Total Revenue". Always download the dashboard, find tiles with matching

chartSlug

, and update their

title

and

chartName

to match.

yaml

undefined

下载：
```
lightdash download --charts chart-slug
```
编辑
```
lightdash/
```
目录下的YAML文件
验证过滤值：若添加或修改了过滤，请使用
```
lightdash sql
```
检查实际列值（参考常见错误）
更新仪表盘组件：若修改了图表名称或用途，请下载所有引用该图表的仪表盘，并更新组件的
```
title
```
和
```
chartName
```
属性（参考常见错误）
校验：
```
lightdash lint
```
验证后再上传
上传：
```
lightdash upload --charts chart-slug
```
（以及所有修改过的仪表盘）

仪表盘组件有独立标题。

saved_chart

组件的

title

和

chartName

属性是独立的覆盖项——重命名图表时它们不会自动更新。若你将图表从“总营收”改为“毛利润”但未更新仪表盘组件，仪表盘仍会显示“总营收”。请始终下载仪表盘，找到匹配

chartSlug

的组件，并更新

title

和

chartName

使其与图表一致。

yaml

undefined

Dashboard tile — title and chartName must be updated manually when chart changes

仪表盘组件——图表变更时需手动更新title和chartName

tiles:

type: saved_chart properties: chartSlug: total-revenue-kpi title: "Gross Profit" # ← Update this when chart name/purpose changes chartName: "Gross Profit" # ← Update this too

undefined

tiles:

type: saved_chart properties: chartSlug: total-revenue-kpi title: "毛利润" # ← 图表名称/用途变更时更新此处 chartName: "毛利润" # ← 同时更新此处

undefined

Editing Dashboards

编辑仪表盘

Download:

lightdash download --dashboards dashboard-slug

Edit the YAML file in
```
lightdash/
```
directory
Verify filter values: If you added or changed filters, use
```
lightdash sql
```
to check actual column values (see Common Mistakes)
Lint:
```
lightdash lint
```
to validate before uploading

Upload:

lightdash upload --dashboards dashboard-slug

下载：

lightdash download --dashboards dashboard-slug

编辑
```
lightdash/
```
目录下的YAML文件
验证过滤值：若添加或修改了过滤，请使用
```
lightdash sql
```
检查实际列值（参考常见错误）
校验：
```
lightdash lint
```
验证后再上传

上传：

lightdash upload --dashboards dashboard-slug

Creating New Content

创建新内容

Charts and dashboards are typically created in the UI first, then managed as code:

Create in UI
```
lightdash download
```
to pull as YAML
Edit and version control
```
lightdash lint
```
to validate before uploading
```
lightdash upload
```
to sync changes

图表和仪表盘通常先在UI中创建，再以代码形式管理：

在UI中创建
```
lightdash download
```
将其拉取为YAML文件
编辑并进行版本控制
```
lightdash lint
```
验证后再上传
```
lightdash upload
```
同步变更

Testing with Preview

使用Preview测试

For larger changes, test in isolation:

bash

lightdash preview --name "my-feature"

对于较大变更，请在隔离环境中测试：

bash

lightdash preview --name "my-feature"

Make changes and iterate

进行变更并迭代

lightdash stop-preview --name "my-feature"

undefined

lightdash stop-preview --name "my-feature"

undefined

CLI Quick Reference

CLI快速参考

Command	Purpose
`lightdash deploy`	Sync semantic layer (metrics, dimensions)
`lightdash upload`	Upload charts/dashboards
`lightdash download`	Download charts/dashboards as YAML
`lightdash lint`	Validate YAML locally
`lightdash preview`	Create temporary test project
`lightdash warehouse-catalog --json`	Discover raw warehouse tables
`lightdash sql "..." -o file.csv`	Run SQL queries against warehouse
`lightdash run-chart -p chart.yml`	Execute chart YAML query against warehouse

See CLI Reference for full command documentation.

命令	用途
`lightdash deploy`	同步语义层（指标、维度）
`lightdash upload`	上传图表/仪表盘
`lightdash download`	将图表/仪表盘下载为YAML
`lightdash lint`	本地校验YAML
`lightdash preview`	创建临时测试项目
`lightdash warehouse-catalog --json`	发现原始数据仓库表
`lightdash sql "..." -o file.csv`	针对数据仓库执行SQL查询
`lightdash run-chart -p chart.yml`	针对数据仓库执行图表YAML查询

完整命令文档请参考CLI Reference。

Semantic Layer

语义层

The semantic layer defines your data model. See individual references for full configuration:

Tables Reference — queryable entities, labels, joins
Metrics Reference — aggregated calculations (
```
count
```
,
```
sum
```
,
```
average
```
,
```
min
```
,
```
max
```
,
```
number
```
, etc.)
Dimensions Reference — attributes for grouping/filtering (
```
string
```
,
```
number
```
,
```
boolean
```
,
```
date
```
,
```
timestamp
```
)
Joins Reference — cross-table relationships
User Attributes Reference — SQL variables, row-level security, access control

语义层定义数据模型。完整配置请参考各独立文档：

Tables Reference — 可查询实体、标签、关联
Metrics Reference — 聚合计算（
```
count
```
、
```
sum
```
、
```
average
```
、
```
min
```
、
```
max
```
、
```
number
```
等）
Dimensions Reference — 用于分组/过滤的属性（
```
string
```
、
```
number
```
、
```
boolean
```
、
```
date
```
、
```
timestamp
```
）
Joins Reference — 跨表关系
User Attributes Reference — SQL变量、行级安全、权限控制

Chart Types

图表类型

All charts share a common base structure:

yaml

chartConfig:
  config: {}        # Type-specific — see individual references
  type: <type>
contentType: chart              # Required: chart, dashboard, or sql_chart
dashboardSlug: my-dashboard  # Optional: scopes chart to dashboard (won't appear in space)
metricQuery:
  dimensions:
    - my_explore_category
  exploreName: my_explore     # Required: which explore to query
  filters: {}
  limit: 500
  metrics:
    - my_explore_total_sales
  sorts: []
name: "Chart Name"
slug: unique-chart-slug
spaceSlug: target-space
tableConfig:
  columnOrder: []
tableName: my_explore           # Required: top-level explore/table name
version: 1

Key ordering: All YAML keys must be sorted alphabetically at every nesting level. The CLI writes files with

sortKeys: true

and warns on upload if keys are unsorted. When writing or editing YAML by hand, keep keys in alphabetical order to avoid warnings and noisy diffs.

Chart scoping: Use

spaceSlug

only for shared charts. Add

dashboardSlug

to scope a chart to a specific dashboard (it won't appear in the space).

Nested spaces: Spaces can be nested. In YAML,

spaceSlug

uses

parent/child

syntax to address a sub-space — the

denotes hierarchy. Examples:

yaml

spaceSlug: sales              # Top-level space "sales"
spaceSlug: sales/maps         # Sub-space "maps" inside "sales"
spaceSlug: sales/eu/forecasts # Deeper nesting works the same way

Each path segment must be the slug of an existing (or to-be-created) space at that level. A bare slug like

sales-maps

is a flat top-level space, NOT a sub-space — the slash is the only thing that creates the hierarchy.

所有图表共享通用基础结构：

yaml

chartConfig:
  config: {}        # 类型专属配置——参考各独立文档
  type: <type>
contentType: chart              # 必填：chart、dashboard或sql_chart
dashboardSlug: my-dashboard  # 可选：将图表限定在指定仪表盘内（不会出现在空间中）
metricQuery:
  dimensions:
    - my_explore_category
  exploreName: my_explore     # 必填：要查询的探索
  filters: {}
  limit: 500
  metrics:
    - my_explore_total_sales
  sorts: []
name: "Chart Name"
slug: unique-chart-slug
spaceSlug: target-space
tableConfig:
  columnOrder: []
tableName: my_explore           # 必填：顶层探索/表名称
version: 1

键排序规则：所有YAML键必须在每个嵌套层级按字母顺序排序。CLI写入文件时默认

sortKeys: true

，上传时若键未排序会发出警告。手动编写或编辑YAML时，请保持键按字母顺序排列，以避免警告和混乱的差异对比。

图表范围：仅对共享图表使用

spaceSlug

。添加

dashboardSlug

可将图表限定在指定仪表盘内（不会出现在空间中）。

嵌套空间：空间可以嵌套。在YAML中，

spaceSlug

使用

parent/child

语法表示子空间——

表示层级关系。示例：

yaml

spaceSlug: sales              # 顶层空间"sales"
spaceSlug: sales/maps         # "sales"下的子空间"maps"
spaceSlug: sales/eu/forecasts # 更深层级的嵌套

每个路径段必须是对应层级已存在（或即将创建）的空间的slug。类似

sales-maps

的纯slug是扁平的顶层空间，而非子空间——只有斜杠才能创建层级关系。

Choosing the Right Chart Type

选择合适的图表类型

Data Pattern	Recommended Chart	Why
Trends over time	Line or area ( `cartesian` )	Shows continuous change with time on X-axis
Category comparisons	Bar ( `cartesian` )	Easy visual comparison between discrete categories
Part-of-whole relationships	`pie` or `treemap`	Shows proportions summing to 100%
Single KPI metric	`big_number`	Focuses attention on one important value
Conversion stages	`funnel`	Visualizes drop-off between sequential steps
Progress toward target	`gauge`	Shows current value relative to goal
Geographic data	`map`	Plots data points or regions on a map
Flow between categories	`sankey`	Shows how values move from source to target nodes
Detailed records	`table`	Displays raw data with sorting and formatting
Advanced custom needs	`custom`	Full Vega-Lite spec for custom visualizations

Type	Use Case	Reference
`cartesian`	Bar, line, area, scatter	Cartesian
`pie`	Parts of whole	Pie
`table`	Data tables	Table
`big_number`	KPIs	Big Number
`funnel`	Conversion funnels	Funnel
`gauge`	Progress indicators	Gauge
`treemap`	Hierarchical data	Treemap
`map`	Geographic data	Map
`sankey`	Flow diagrams	Sankey
`custom`	Vega-Lite	Custom Viz

数据模式	推荐图表	原因
时间趋势	折线图或面积图（ `cartesian` ）	展示随时间变化的连续趋势，时间轴在X轴
类别对比	柱状图（ `cartesian` ）	便于直观对比离散类别间的数据
占比关系	`pie` 或 `treemap`	展示各部分占整体的比例，总和为100%
单一KPI指标	`big_number`	聚焦展示单个重要数值
转化流程	`funnel`	可视化连续步骤间的用户流失情况
目标进度	`gauge`	展示当前值与目标值的相对关系
地理数据	`map`	在地图上绘制数据点或区域
类别间流转	`sankey`	展示数值在源节点到目标节点间的流动情况
详细记录	`table`	展示原始数据，支持排序和格式化
高级自定义需求	`custom`	使用完整Vega-Lite规范创建自定义可视化

类型	适用场景	参考文档
`cartesian`	柱状图、折线图、面积图、散点图	Cartesian
`pie`	占比分析	Pie
`table`	数据表格	Table
`big_number`	KPI展示	Big Number
`funnel`	转化漏斗	Funnel
`gauge`	进度指标	Gauge
`treemap`	层级数据	Treemap
`map`	地理数据	Map
`sankey`	流转图	Sankey
`custom`	Vega-Lite自定义可视化	Custom Viz

Dashboards

仪表盘

Dashboards arrange charts and content in a grid layout. See Dashboard Reference for YAML structure, tile types, tabs, and filters.

仪表盘以网格布局排列图表和内容。YAML结构、组件类型、标签页和过滤配置请参考Dashboard Reference。

Exploring the Warehouse

探索数据仓库

Use

lightdash sql

to explore data when building models:

bash

undefined

构建模型时，使用

lightdash sql

探索数据：

bash

undefined

Preview table structure

预览表结构

lightdash sql "SELECT * FROM orders LIMIT 5" -o preview.csv

Check distinct values for a dimension

检查维度的唯一值

lightdash sql "SELECT DISTINCT status FROM orders" -o statuses.csv

Test metric calculations

测试指标计算

lightdash sql "SELECT SUM(amount) FROM orders" -o test.csv

undefined

lightdash sql "SELECT SUM(amount) FROM orders" -o test.csv

undefined

Workflow Patterns

工作流模式

Pattern	When to Use
Direct ( `deploy` + `upload` )	Solo dev, rapid iteration
Preview-First	Team, complex changes
CI/CD	Automated on merge

See Workflows Reference for detailed examples and CI/CD configurations.

模式	适用场景
直接模式（ `deploy` + `upload` ）	单人开发、快速迭代
预览优先模式	团队协作、复杂变更
CI/CD模式	合并时自动部署

详细示例和CI/CD配置请参考Workflows Reference。

Resources

资源

Semantic Layer

语义层

Creating from a Warehouse Catalog
Dimensions Reference
Metrics Reference
Tables Reference
Joins Reference
User Attributes Reference

Creating from a Warehouse Catalog
Dimensions Reference
Metrics Reference
Tables Reference
Joins Reference
User Attributes Reference

Charts

图表

Cartesian Chart Reference - Bar, line, area, scatter
Pie Chart Reference
Table Chart Reference
Big Number Reference
Funnel Chart Reference
Gauge Chart Reference
Treemap Chart Reference
Map Chart Reference
Sankey Chart Reference
Custom Viz Reference
Period over Period Reference - PoP comparisons (YoY, MoM, etc.)

Cartesian Chart Reference - 柱状图、折线图、面积图、散点图
Pie Chart Reference
Table Chart Reference
Big Number Reference
Funnel Chart Reference
Gauge Chart Reference
Treemap Chart Reference
Map Chart Reference
Sankey Chart Reference
Custom Viz Reference
Period over Period Reference - 周期对比（同比、环比等）

Dashboards & Workflows

仪表盘与工作流

Dashboard Reference
Dashboard Best Practices
Content as Code Reference
CLI Reference
Workflows Reference

Dashboard Reference
Dashboard Best Practices
Content as Code Reference
CLI Reference
Workflows Reference

External

外部资源

Lightdash Docs

Lightdash Docs