跳到主内容
智客 ZICQ

技能库 智客分类:运维与云 developing-in-lightdash

Developing In Lightdash

当与 Lightdash YAML 文件, Dbt 模式使用 Lightdash 元数据, Lightdash CLI (部署,上传,下载,预览, lint, 仓库- catalog, sql, set-warehouse, apps create/preview/validate) , 或管理图表, 仪表板, 空格和访问, AI代理, 预定内容, 数据应用, 自定义图表类型( Chart Studio, `apps create-chart-type', `chart-type'), 组织 数据 App主题,数据应用外部连接,用户,组,自定义角色,度量衡和维度作为代码

428 安装量

官方网址:skills.sh

技能介绍

先看中文介绍;官方 description 原文单独保留,不改写 SKILL.md。

做什么

当与 Lightdash YAML 文件, Dbt 模式使用 Lightdash 元数据, Lightdash CLI (部署,上传,下载,预览, lint, 仓库- catalog, sql, set-warehouse, apps create/preview/validate) , 或管理图表, 仪表板, 空格和访问, AI代理, 预定内容, 数据应用, 自定义图表类型( Chart Studio, `apps create-chart-type', `chart-type'), 组织 数据 App主题,数据应用外部连接,用户,组,自定义角色,度量衡和维度作为代码

何时用

- 与Lightdash YAML文件(图表、仪表板、模型作为代码)合作

代理如何加载

按 Agent Skills 渐进披露:启动时只加载 name 与 description(约 100 token);任务匹配后才读入整份 SKILL.md 正文;scripts/、references/、assets/ 仅在需要时再读。 本文件正文结构:Developing in Lightdash、When to Use、What You Can Do、Common Mistakes、Before You Start、Check Your Target Project。 其中含规范建议的小节:分步指令。

文件分析

文件分析:这是一份仅含 SKILL.md 的指令型技能,代理激活后整份正文进入上下文。

官方 description(原文)

Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code

Developing in LightdashWhen to UseWhat You Can DoCommon MistakesBefore You StartCheck Your Target ProjectDetect Your Project TypeSyntax ComparisonSetting Up Warehouse ConnectionCore WorkflowsVerify Filter Values Before Using ThemEditing Metrics & Dimensions

来源分类:skills.sh agent-skill

SKILL.md 与 Agent 调用

官方规范 ↗
name
developing-in-lightdash
description
Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code
  1. 发现技能客户端向 Agent 提供名称与描述目录。
  2. 匹配与调用用户指定或任务匹配后,载入 SKILL.md 指令。
  3. 按需加载按步骤读取参考文档、使用脚本与素材。

具体调用语法与可用工具以目标 Agent 客户端为准。 查看调用机制说明 ↗

安装这个技能

Skills CLI ↗

先选择目标 Agent 和安装范围,保留技能包的附属文件,安装后检查客户端能否发现该技能。

交给 Agent 安装

复制安装指令给支持 Agent Skills 的代理,确认其中的目标目录与客户端匹配。

把 Agent Skill「developing-in-lightdash」安装到我的项目:SKILL.md 原文与官方 description 见 https://zicq.com/zh/skills/skl-48d671b9da2ebb77-%E5%9C%A8%E7%81%AF%E5%A1%94%E4%B8%8A%E5%8F%91%E5%B1%95.html
请存为 .cursor/skills/developing-in-lightdash/SKILL.md 或 .claude/skills/developing-in-lightdash/SKILL.md,frontmatter 的 name 与 description 保持原样,不要改写。

GitHub 完整包 ↗

终端安装 · Skills CLI

需要 Node.js 与 npx。先查看仓库技能列表,确认实际名称。

npx skills add 'https://github.com/lightdash/lightdash' --list

npx skills add 'https://github.com/lightdash/lightdash' --skill 'developing-in-lightdash'

CLI 会交互选择目标 Agent,默认安装到项目;用户级安装使用 -g。先通过查看命令核对仓库内容,再用 npx skills list 检查已安装技能。

阅读排版
--- name: developing-in-lightdash description: Use when working with Lightdash YAML files, dbt models with Lightdash metadata, the lightdash CLI (deploy, upload, download, preview, lint, warehouse-catalog, sql, set-warehouse, apps create/preview/validate), or managing charts, dashboards, spaces and access, AI agents, scheduled content, data apps, custom chart types (Chart Studio, `apps create --chart-type`, `--chart-types`), organization Data App themes, data-app external connections, users, groups, custom roles, metrics, and dimensions as code --- # Developing in Lightdash For CLI users and writeback sandboxes working with YAML and dbt files. Build and deploy Lightdash analytics projects. This skill covers the **semantic layer** (metrics, dimensions, joins) and **content** (charts, dashboards). ## 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 - Downloading, uploading, or locally developing data apps (enterprise) - Creating, downloading, editing, or uploading custom chart types built in Chart Studio (enterprise) - Creating, editing, migrating, downloading, or uploading organization Data App themes **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. ## 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](./resources/creating-from-warehouse-catalog.md) | | Discover warehouse tables and fields | `lightdash warehouse-catalog --json` | [CLI Reference](./resources/cli-reference.md) | | Explore data warehouse values | `lightdash sql` to execute raw sql, read .csv results | [CLI Reference](./resources/cli-reference.md) | | Define metrics & dimensions | Edit dbt YAML or Lightdash YAML | [Metrics](./resources/metrics-reference.md), [Dimensions](./resources/dimensions-reference.md) | | Create charts | `lightdash download`, edit YAML, `lightdash upload` | [Chart Types](#chart-types) | | Add period comparisons | Add PoP additional metrics to chart YAML | [Period over Period](./resources/period-over-period-reference.md) | | Build dashboards | `lightdash download`, edit YAML, `lightdash upload` | [Dashboard Reference](./resources/dashboard-reference.md) | | Manage content as code across project and organization resources | `lightdash download`, `lightdash upload` | [Content as Code](./resources/content-as-code-reference.md) | | Manage data apps as code (enterprise) | `lightdash download --apps ` (one app) or `--include-apps` (all), edit bundle, `lightdash upload --apps `; local dev via `lightdash apps create/preview/validate` | [Data Apps](#working-with-data-apps-enterprise), [Content as Code](./resources/content-as-code-reference.md) | | Build or edit a custom chart type (enterprise) | `lightdash apps create "" --chart-type` or `lightdash download --chart-types `, edit `chart-types//src/`, `lightdash upload --chart-types ` | [Custom Chart Types](#working-with-custom-chart-types-enterprise) | | Manage organization Data App themes as code | `lightdash download --organization`, edit `themes//`, `lightdash upload --organization` | [Data App Themes](./resources/data-app-themes-reference.md) | | Manage data-app external connections (enterprise) | `lightdash download --include-external-connections`, edit YAML, `lightdash upload` | [Content as Code](./resources/content-as-code-reference.md) | | Lint yaml files | `lightdash lint` | [CLI Reference](./resources/cli-reference.md) | | Set warehouse connection | `lightdash set-warehouse` from profiles.yml | [CLI Reference](./resources/cli-reference.md) | | Deploy changes | `lightdash deploy` (semantic layer), `lightdash upload` (content) | [CLI Reference](./resources/cli-reference.md) | | Test changes | `lightdash preview` | [Workflows](./resources/workflows-reference.md) | ## 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 | | **Adding `--include-apps` to an `--apps ` selection** | `--include-apps` always requests ALL project apps (capped at 50), so the command downloads every app plus the ref — not just the one app | `--apps ` alone downloads/uploads only that app (by slug, app URL, or UUID). Use `--include-apps` only when you want every app | | **Editing a data app without reading its bundled skills** | App code violates the SDK-only data access and dependency boundaries (direct `fetch`, `pnpm add`, vendored libraries) and the upload rejects or the app breaks when deployed | Every app bundle ships the `developing-data-apps-locally` and `lightdash-data-app` skills — read them before editing files in an app folder (see [Data Apps](#working-with-data-apps-enterprise)) | | **Building a reusable chart as a Vega-Lite `custom` chart** | The visualization lives inside one saved chart and can't be reused or picked from the explorer's chart type picker | For a new reusable visualization, build a custom chart type (see [Custom Chart Types](#working-with-custom-chart-types-enterprise)). Use Vega-Lite only for existing `chartConfig.type: custom` charts or when the project has no custom chart types (enterprise) | | **Editing a chart type without reading its bundled skills** | The component queries or fetches data itself, or its `vizSchema` drifts from what `src/` reads, so the chart type breaks or never appears in the chart type picker | Every chart type folder ships `AGENTS.md` plus the `reusable-visualization` and `developing-chart-types-locally` skills — read all three before editing files in `chart-types//` | | **Inventing a theme-only CLI command or treating a missing folder as deletion** | The command does not exist, or a supposedly deleted remote theme returns on the next download | Use organization download/upload, and read [Data App Themes](./resources/data-app-themes-reference.md) before changing `themes/` | ## Before You Start When a task uses `lightdash download` or `lightdash upload`, especially for bulk edits, spaces and access, scheduled content, AI agents, data apps, custom chart types, organization themes, external connections, users, groups, or custom roles, **read and follow [Content as Code](./resources/content-as-code-reference.md) first**. Project and organization content require separate commands, and a default download is not a complete snapshot. For any task that creates, edits, migrates, downloads, uploads, or tests an organization Data App theme, **always read and follow [Data App Themes](./resources/data-app-themes-reference.md) before touching `themes/`**. Theme packages are strict multi-file resources, organization upload has no theme-only mode, and `lightdash lint` does not validate them. ### 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 ``` ### 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" > ``` ### 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 ``` ## 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 --assume-yes ``` ## Core Workflows ### Verify Filter Values Before Using Them **CRITICAL**: Never guess filter values. Case mismatches (e.g., `'Payment'` vs `'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. ### Editing Metrics & Dimensions 1. **Find the model YAML file** (dbt: `models/*.yml`, pure Lightdash: `lightdash/models/*.yml`) 2. **Edit metrics/dimensions** using the appropriate syntax for your project type 3. **Validate**: `lightdash lint` (pure Lightdash) or `dbt compile` (dbt projects) 4. **Deploy**: `lightdash deploy` See [Metrics Reference](./resources/metrics-reference.md) and [Dimensions Reference](./resources/dimensions-reference.md) for configuration options. ### Creating a Pure Lightdash Project from a Warehouse Catalog 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](./resources/creating-from-warehouse-catalog.md) 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. ### Editing Charts 1. **Download**: `lightdash download --charts chart-slug` 2. **Edit** the YAML file in `lightdash/` directory 3. **Verify filter values**: If you added or changed filters, use `lightdash sql` to check actual column values (see [Common Mistakes](#common-mistakes)) 4. **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](#common-mistakes)) 5. **Lint**: `lightdash lint` to validate before uploading 6. **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 # Dashboard tile — title and chartName must be updated manually when chart changes 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 ``` ### Editing Dashboards 1. **Download**: `lightdash download --dashboards dashboard-slug` 2. **Edit** the YAML file in `lightdash/` directory 3. **Verify filter values**: If you added or changed filters, use `lightdash sql` to check actual column values (see [Common Mistakes](#common-mistakes)) 4. **Lint**: `lightdash lint` to validate before uploading 5. **Upload**: `lightdash upload --dashboards dashboard-slug` ### Working with Data Apps (Enterprise) Data apps are multi-file React bundles under `apps//` with a `lightdash-app.yml` manifest — not single YAML files. Full flag semantics and manifest details: [Content as Code](./resources/content-as-code-reference.md). **Download one app** — `--apps ` alone is the complete command (ref = slug, app URL, or UUID; also finds apps not added to any space): ```bash lightdash download --apps revenue-explorer --path ./lightdash ``` Never add `--include-apps` to "scope" the download — it always requests ALL project apps (see [Common Mistakes](#common-mistakes)). **Download all apps**: `lightdash download --include-apps` (capped at 50; raise with `--apps-limit `). Add `--apps-only` to skip charts, dashboards, and spaces. **Upload**: ```bash lightdash upload --apps revenue-explorer # one app (slug = folder name, URL, or UUID) lightdash upload --include-apps # every app folder on disk ``` - `--app-space ` — space (slug or UUID) for apps this upload **creates**; existing apps keep their space. - `--create-new` — create a fresh app (new slug) instead of updating the app referenced in `lightdash-app.yml`. - `--allow-custom-dependencies` — required for non-interactive uploads of apps that declare custom npm dependencies. **Develop locally** with the `lightdash apps` subcommand group: ```bash lightdash apps create "Revenue Explorer" # scaffold a new app under ./lightdash/apps/ lightdash apps preview # run the app locally against your real Lightdash instance, authenticated as you lightdash apps validate # check source, manifest, dependencies, and semantic-layer references ``` **Every created or downloaded app bundle ships its own skills** inside the app folder: - `developing-data-apps-locally` — the edit → validate → upload loop, local preview, SDK-only data access, and dependency boundaries - `lightdash-data-app` — the `@lightdash/query-sdk` reference for the app's source code When editing files inside an app folder, **read those bundled skills first**. They are version-matched to the app and authoritative for local development — this skill only covers moving apps between disk and Lightdash. ### Working with Custom Chart Types (Enterprise) A custom chart type is a reusable visualization built in Chart Studio: one React component that Lightdash hands query results and settings to, offered in the explorer's chart type picker for every chart in the project. On disk it is a multi-file bundle under `chart-types//` with a `lightdash-app.yml` manifest whose `vizSchema` declares the fields and options the component reads. It is not a data app (it runs no query of its own) and not the legacy Vega-Lite `custom` chart. **Create one locally:** ```bash lightdash apps create "Radial Gauge" --chart-type # scaffolds ./lightdash/chart-types/radial-gauge/ ``` **Download** — `--chart-types ` alone is the complete command (ref = slug, URL, or UUID): ```bash lightdash download --chart-types radial-gauge --path ./lightdash lightdash download --include-chart-types # every chart type in the project (capped at 50; raise with --chart-types-limit ) lightdash download --chart-types-only # chart types only, skipping charts, dashboards, and spaces ``` Downloading a chart that renders with a custom chart type also downloads that chart type. In chart YAML the binding is `chartConfig.type: data_app_viz` with `config.dataAppVizSlug`, `fieldMapping`, and `optionValues`. **Upload:** ```bash lightdash upload --chart-types radial-gauge # one chart type (slug = folder name, URL, or UUID) lightdash upload --include-chart-types # every chart type folder on disk ``` A chart YAML that binds to a chart type by `dataAppVizSlug` fails to upload unless that chart type exists in the target project. Upload the chart type first, or pass `--chart-types ` in the same run (chart types upload before charts). **Edit inside the folder.** Change into `chart-types//` and **read its `AGENTS.md` plus the `reusable-visualization` and `developing-chart-types-locally` skills before touching `src/`**: - `reusable-visualization` — the component contract: `useVizContext()` is the only channel to the host, and the component never queries or fetches anything itself - `developing-chart-types-locally` — keeping `vizSchema` in lockstep with the component, `lightdash apps validate --build`, the fixture preview, and the upload-and-verify loop Those files are version-matched to the chart type and authoritative for editing it. This skill only covers moving chart types between disk and Lightdash. ### Working with Organization Data App Themes Organization Data App themes are multi-file packages under `themes//` and participate automatically in `lightdash download --organization` and `lightdash upload --organization`. They do not have a standalone command group or theme-specific selectors. Before creating, editing, migrating, synchronizing, or testing a theme, **read and follow [Data App Themes](./resources/data-app-themes-reference.md)** for the manifest contract, asset rules, synchronization behavior, and generation boundaries. ### Creating New Content Charts and dashboards are typically created in the UI first, then managed as code: 1. Create in UI 2. `lightdash download` to pull as YAML 3. Edit and version control 4. `lightdash lint` to validate before uploading 5. `lightdash upload` to sync changes ### Testing with Preview For larger changes, test in isolation: ```bash lightdash preview --name "my-feature" # Make changes and iterate lightdash stop-preview --name "my-feature" ``` ## CLI Quick Reference | 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 | | `lightdash apps create ` | Scaffold a new data app locally (enterprise) | | `lightdash apps create --chart-type` | Scaffold a new custom chart type locally (enterprise) | | `lightdash apps preview` | Run a data app locally against your Lightdash instance | | `lightdash apps validate` | Validate data app or chart type source, manifest, and semantic references | | `lightdash download --chart-types ` / `lightdash upload --chart-types ` | Move custom chart types between disk and Lightdash (enterprise) | See [CLI Reference](./resources/cli-reference.md) for full command documentation. ## Semantic Layer The semantic layer defines your data model. See individual references for full configuration: - [Tables Reference](./resources/tables-reference.md) — queryable entities, labels, joins - [Metrics Reference](./resources/metrics-reference.md) — aggregated calculations (`count`, `sum`, `average`, `min`, `max`, `number`, etc.) - [Dimensions Reference](./resources/dimensions-reference.md) — attributes for grouping/filtering (`string`, `number`, `boolean`, `date`, `timestamp`) - [Joins Reference](./resources/joins-reference.md) — cross-table relationships - [User Attributes Reference](./resources/user-attributes-reference.md) — SQL variables, row-level security, access control ## Chart Types All charts share a common base structure: ```yaml chartConfig: config: {} # Type-specific — see individual references 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. ### 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 | | Visualization none of the above cover | Custom chart type | Reusable React component offered in the chart type picker — see [Custom Chart Types](#working-with-custom-chart-types-enterprise) | | Vega-Lite chart | `custom` (legacy) | For charts already saved with `chartConfig.type: custom`, or projects without custom chart types (enterprise) | | Type | Use Case | Reference | |------|----------|-----------| | `cartesian` | Bar, line, area, scatter | [Cartesian](./resources/cartesian-chart-reference.md) | | `pie` | Parts of whole | [Pie](./resources/pie-chart-reference.md) | | `table` | Data tables | [Table](./resources/table-chart-reference.md) | | `big_number` | KPIs | [Big Number](./resources/big-number-chart-reference.md) | | `funnel` | Conversion funnels | [Funnel](./resources/funnel-chart-reference.md) | | `gauge` | Progress indicators | [Gauge](./resources/gauge-chart-reference.md) | | `treemap` | Hierarchical data | [Treemap](./resources/treemap-chart-reference.md) | | `map` | Geographic data | [Map](./resources/map-chart-reference.md) | | `sankey` | Flow diagrams | [Sankey](./resources/sankey-chart-reference.md) | | `custom` | Legacy Vega-Lite custom chart | [Custom Viz](./resources/custom-viz-reference.md) | | `data_app_viz` | Chart rendered by a custom chart type | [Custom Chart Types](#working-with-custom-chart-types-enterprise) | ## Dashboards Dashboards arrange charts and content in a grid layout. See [Dashboard Reference](./resources/dashboard-reference.md) for YAML structure, tile types, tabs, and filters. ## Exploring the Warehouse Use `lightdash sql` to explore data when building models: ```bash # 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 ``` ## 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](./resources/workflows-reference.md) for detailed examples and CI/CD configurations. ## Resources ### Semantic Layer - [Creating from a Warehouse Catalog](./resources/creating-from-warehouse-catalog.md) - [Dimensions Reference](./resources/dimensions-reference.md) - [Metrics Reference](./resources/metrics-reference.md) - [Tables Reference](./resources/tables-reference.md) - [Joins Reference](./resources/joins-reference.md) - [User Attributes Reference](./resources/user-attributes-reference.md) ### Charts - [Cartesian Chart Reference](./resources/cartesian-chart-reference.md) - Bar, line, area, scatter - [Pie Chart Reference](./resources/pie-chart-reference.md) - [Table Chart Reference](./resources/table-chart-reference.md) - [Big Number Reference](./resources/big-number-chart-reference.md) - [Funnel Chart Reference](./resources/funnel-chart-reference.md) - [Gauge Chart Reference](./resources/gauge-chart-reference.md) - [Treemap Chart Reference](./resources/treemap-chart-reference.md) - [Map Chart Reference](./resources/map-chart-reference.md) - [Sankey Chart Reference](./resources/sankey-chart-reference.md) - [Custom Viz Reference](./resources/custom-viz-reference.md) - Legacy Vega-Lite `custom` charts - [Period over Period Reference](./resources/period-over-period-reference.md) - PoP comparisons (YoY, MoM, etc.) ### Dashboards & Workflows - [Dashboard Reference](./resources/dashboard-reference.md) - [Dashboard Best Practices](./resources/dashboard-best-practices.md) - [Data App Themes Reference](./resources/data-app-themes-reference.md) - [Content as Code Reference](./resources/content-as-code-reference.md) - [CLI Reference](./resources/cli-reference.md) - [Workflows Reference](./resources/workflows-reference.md) ### External - [Lightdash Docs](https://docs.lightdash.com)

相关技能

运维与云

Docker Essentials

用于容器管理,图像操作,调试的基本道克命令和工作流程.

运维与云

Find Skills

从开放的代理技能生态系统中发现并安装技能. 使用时:(1)用户问"我如何做X",X可能拥有现有技能,(2)用户说"为X找到技能"或"是否为X有技能",(3)用户问"你能否做X",X是专门能力,(4)用户想扩展代理能力,(5)用户想搜索工具,模板,或工作流程,(6)用户提到他们希望…

运维与云

Microsoft Foundry

构建,部署,评价,优化,微调,管理微软创始代理,模型,资源最终结束. 用法:铸造、azd ai代理、azd 提供/部署、托管代理脚手架/开发/运行/部署/拖放、即时代理创建、创建代理、更新代理、添加代理工具、援引代理、代理.yaml、评估代理、批量活化、连续活化、持续监测、代理C…

运维与云

Azure Deploy

执行已有.azure/部署计划.md和基础设施文件的ALREADY-PREPARED应用程序的Azure部署。 当用户向 CREATE 请求新应用程序时, 请不要使用此技能 。 这种技能运行了 azd上行, azd 部署, trarraform 应用, 和 az 部署命令带有内置…