深度解析 Lightdash Playground Bundle基于 DuckDB 与 dbt 的教学仓库构建流水线【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash导读scripts/playground-bundle是 Lightdash 仓库内一套独立的构建子系统负责把示例项目examples/full-jaffle-shop-demo/dbt打包成可随产品分发的轻量教学数据包Playground bundle。它通过duckdb/node-api加载 CSV seed、以 dbt-duckdb 物化模型再借 Lightdash 后端的项目适配器编译 Explore最终产出 DuckDB 数据库与预编译的explores.json、content.json。读完本文你将掌握这套源码 → 编译 → 校验 → 校验和发布的完整链路知道如何在content.ts/teachingContent.ts中维护教学样例以及如何用pnpm test:playground-content在不重建仓库的情况下保证源定义与已发布产物的一致性。Playground Bundle 是什么Lightdash 的 Playground试用/演示项目在用户初始化时会用到一套预置的 Jaffle Shop 教学数据集。为了让 Playground 项目启动即用、无需现场执行昂贵的 dbt 编译仓库维护了一套版本化的预编译产物一个 Jaffle Shop 的 DuckDB 数据仓库文件预编译的 Lightdash Explore 列表预置的图表、仪表盘等教学内容定义。scripts/playground-bundle/目录就是这套产物的构建源头。按照 scripts/playground-bundle/README.md 的说明构建过程会用duckdb/node-api将每个 CSV seed 加载为物理表用 dbt-duckdb 物化 dbt 模型通过 Lightdash 后端的项目适配器DbtLocalProjectAdapter编译 Explore。产物的消费端位于packages/backend/assets/playground/包含 4 个提交进仓库的文件文件内容jaffle_shop.duckdb物化后的 DuckDB 数据仓库含jaffleschemaexplores.json预编译的 Explore 定义单行 JSONcontent.json教学内容的版本化定义图表、仪表盘等单行 JSONSHA256SUMS上述三个产物的 SHA-256 校验和清单为什么产物要小而确定临时副本 view 物化构建时不会直接修改仓库中已检入的示例项目。build.ts会在系统临时目录创建两份隔离资源一份 dbt 项目副本通过cp复制examples/full-jaffle-shop-demo/dbt并排除target目录一份临时的 dbt-duckdb profile。为了让最终二进制文件足够小副本中所有模型默认物化方式由table改写为view。这一改写逻辑独立在 scripts/playground-bundle/projectYaml.ts 中export const replaceTableMaterializations (projectYaml: string): string { const tableMaterialization materialized: table; if (!projectYaml.includes(tableMaterialization)) { throw new Error( Playground dbt project must define a table materialization, ); } return projectYaml.replaceAll( tableMaterialization, materialized: view, ); };如果示例项目未来不再声明任何 table 物化构建会直接抛错防止静默失效。CSV seed 确定性截断CSV seed 保持为物理表但被确定性地截断——每个 seed 最多 5000 行build.ts中的const maxSeedRows 5_000避免高数据量演示 seed 撑大捆绑产物。加载时先创建jaffleschema再对排序后的每个 CSV 执行CREATE TABLE jaffle.table AS SELECT * FROM read_csv_auto(seed路径, header true) LIMIT 5000同样在build.ts中DuckDB 数据类型到 LightdashDimensionType的映射也有明确规则typeFromDuckDbBOOL→ 布尔TIMESTAMP/TIME→ 时间戳DATE→ 日期INT/DECIMAL/NUMERIC/DOUBLE/FLOAT/REAL→ 数值其余 → 字符串。一次性环境搭建按 README 的 Setup 章节首次构建前需要创建隔离且被 gitignore 的 Python 环境仅需一次python3 -m venv scripts/playground-bundle/.venv scripts/playground-bundle/.venv/bin/pip install \ dbt-core1.10.0 dbt-duckdb1.10.0 ln -sf dbt scripts/playground-bundle/.venv/bin/dbt1.10关键点在于版本被精确锁定dbt-core 与 dbt-duckdb 都固定为1.10.0与build.ts中传给DbtLocalProjectAdapter的dbtVersion: SupportedDbtVersions.V1_10保持一致。锁版本直接服务于确定性产物目标——只有输入不变SHA256SUMS中的校验和才能保持稳定、可复现。执行构建在仓库根目录运行pnpm build:playground-bundle查看 package.json该命令实际展开为pnpm formula:build pnpm common-build pnpm warehouses-build \ LIGHTDASH_MODEdevelopment LIGHTDASH_SECRETplayground-bundle-build-only \ S3_ENDPOINThttp://localhost S3_BUCKETplayground-build S3_REGIONlocal \ tsx scripts/playground-bundle/build.ts几个值得注意的环境细节前置构建formula、common、warehouses三个包为后续 TypeScript 导入lightdash/common类型、lightdash/warehouses的 DuckDB 客户端做准备LIGHTDASH_MODEdevelopment、LIGHTDASH_SECRETplayground-bundle-build-only是构建期占位值明文提示这是仅供构建的临时 secretS3_*环境变量同样为构建期占位避免真实外部依赖。构建成功后build.ts末尾会输出一行摘要Built playground bundle: ${seedCount} seeds, ${explores.length} explores可直接核对 seed 与 Explore 数量。构建流水线的源码级拆解scripts/playground-bundle/build.ts共 307 行是整条流水线的实现主体可划分为 6 个阶段1. 加载 DuckDB 依赖loadDuckDb通过createRequire从packages/warehouses/package.json解析duckdb/node-api再以import(pathToFileURL(...))方式动态加载DuckDBInstance创建数据库时显式指定default_block_size: 16384。连接与关闭通过withDatabase辅助函数统一管理finally中保证closeSync。2. 加载 seedloadSeeds先删除旧数据库文件然后递归读取示例项目data/目录下全部 CSV排序保证顺序确定性逐一创建表并截断到 5000 行。3. 准备临时 dbt 环境mkdtemp生成两个临时目录profiles目录写入一份临时profiles.ymltype 为duckdb、指向输出数据库路径、schema 为jaffle、threads 为 4项目目录复制自examples/full-jaffle-shop-demo/dbt随后执行replaceTableMaterializations改写物化方式通过修改process.env.PATH将.venv/bin置于最前使execFile能直接找到 dbt 可执行文件构造DbtLocalProjectAdapter传入DuckdbWarehouseClient与上述临时目录dbt 版本固定为 V1_10。4. 执行 dbt run以execFile方式调用.venv/bin/dbt run显式传入--profiles-dir、--project-dir、--target。异常时会把子进程的stdout/stderr转发到当前进程后重新抛出便于排查 SQL 或配置错误。5. 编译 Explore 与校验getCatalog从information_schema.columns查询jaffleschema 下所有表与列组装成 Lightdash 需要的仓库 catalog注入adapter.cachedWarehouse.warehouseCatalog随后调用adapter.compileAllExplores()得到全部 Explore含可能出现的ExploreError。这一步正是 README 所说通过 Lightdash 后端项目适配器编译 Explore的具体实现。6. 输出与清理三个产物分别以单行 JSON末尾带换行或二进制形式写入并用createHash(sha256)计算校验和生成SHA256SUMS。finally块负责还原PATH、销毁 adapter、删除两个临时目录——构建不留任何临时痕迹。教学内容定义content.ts 与 teachingContent.ts教学内容由两份 TypeScript 源文件驱动最终合并进content.json其类型契约定义在 packages/backend/src/ee/services/ProjectService/playgroundContentTypes.ts 的PlaygroundContent中字段说明version内容 schema 版本当前为1space教学空间的名字与路径charts预置图表定义keyslug 指标查询 图表配置dashboard预置仪表盘tabs、tiles 布局pinned主页置顶项按 chart key / dashboard slugcomments图表上的教学评论categories指标目录分类可选yamlReference有则与指标按引用匹配无则是在应用内手工创建的分类metricsTrees预置的指标树节点含表名、指标名与坐标dataApps预构建的数据应用内置files与source两套文件agent项目的 AI Agent供 Ask AI 走查使用deepResearch一次已完成深度研究的结果问题、线程标题、报告 Markdown预置图表示例scripts/playground-bundle/content.ts 中定义了 3 张图表与 1 个仪表盘orders-over-time按月订单量折线图dimension 为orders_order_date_monthmetric 为orders_unique_order_countrevenue-by-payment-method按支付方式的收入条形图flipAxes: truetop-customers客户收入排名表ChartType.TABLE列顺序含customers_first_name、customers_last_name、payments_total_revenue。仪表盘jaffle-shop-overview定义了 3 个 tabOrders trend / Revenue split / Top customers每个 tab 内是HEADING标题块 SAVED_CHART图表块SAVED_CHART通过properties.chartKey而非 savedChartUuid引用上述图表 key——这是 Playground 内容独有的解耦方式见PlaygroundDashboardChartTile类型。大学教学样例teachingContent.tsscripts/playground-bundle/teachingContent.ts 通过...teachingContent展开合并进content.json包含 README 提到的全部University 额外样例pinned置顶仪表盘jaffle-shop-overviewcomments一条挂在orders-over-time图上的教学评论提示检查 2025 年初促销尖峰是否为首次订单categoriesSales、Revenue growth、Core、Experimental、Weekly review 等 5 个分类含颜色dataApps预构建的jaffle-pulse单页应用——files下内联了完整的index.html构建产物运行时直接伺服source下内联了src/App.tsx源码打包为源码归档供 CLI 下载因此播种时无需触发任何沙箱构建agentJaffle analyst带完整instruction提示词deepResearch一份春季退货为何上升的完整研究报告resultMarkdown含#标题、##发现与##结论并记录了durationMs: 412000与warehouseQueryCount: 9作为走查参考数据。对应的类型注释playgroundContentTypes.ts 中PlaygroundDataAppDefinition、PlaygroundDeepResearchDefinition等明确解释了设计意图预构建应用是为了避免播种时运行构建预置 deep research 是为了让学习者无需真正发起一次运行就能阅读报告。构建期的强校验build.ts的validatePlaygroundContent在写入产物前执行三类检查图表 key 唯一性重复 key 直接抛错Explore 可用性每个图表的metricQuery.exploreName必须在刚编译出的 Explore 中存在且不是ExploreError即编译失败不可见字段可用性对图表的 dimensions、metrics 以及排序字段逐一用findFieldByIdInExplore验证若字段带有requiredAttributes/anyAttributes/tablesRequiredAttributes受限属性字段也会抛错防止教学图表引用普通用户无权限访问的字段。此外仪表盘每个saved_charttile 的chartKey必须能命中图表集合。因此任何引用了不存在 Explore、字段或图表的教学内容都会在构建阶段失败而不是等到 Playground 运行时才暴露。内容一致性回归测试不重建数据仓库、不改动任何产物文件也能完整校验源定义 已发布产物pnpm test:playground-content该命令package.json等价于tsx scripts/playground-bundle/content.test.ts。scripts/playground-bundle/content.test.ts 做的事情非常直接读取packages/backend/assets/playground/content.json并解析assert.deepEqual对比playgroundContent对象与产物内容——覆盖每一个字段包括预构建应用的 built/source 文件和完整的研究 Markdown进一步断言JSON.stringify(playgroundContent) \n与产物文件的字节级一致确保序列化字节也完全不变。这套测试保证即使某次重建遗漏了教学样例CI 或本地运行pnpm test:playground-content也会立即报错杜绝重建悄悄丢掉教学样本的风险。校验和验证与日常维护产物重建后可用标准工具核验sha256sum --check packages/backend/assets/playground/SHA256SUMS在 dbt 版本锁定1.10.0且输入不变的前提下已提交的校验和应保持稳定一旦示例项目数据或教学内容变更校验和会随之变化此时需要将源文件与产物一并更新并提交README 明确要求Update the source and shipped bundle together。日常维护的教学内容改动应遵循以下分层图表、仪表盘、指标树编辑 scripts/playground-bundle/content.ts置顶、评论、分类、预构建应用、Agent、深度研究报告编辑 scripts/playground-bundle/teachingContent.ts两类源都会进入同一次构建合并后写入content.json修改后同时运行pnpm test:playground-content与pnpm build:playground-bundle并更新SHA256SUMS。小结Playground bundle 是 Lightdash以代码速度交付分析理念在教学场景下的工程化落地用临时 dbt 副本 view 物化 seed 截断控制产物体积用锁定版本的 dbt 与确定性输入保证可复现用编译期强校验和字节级 parity 测试守住内容一致性最终让 Playground 项目一启动就拥有一套完整、可编辑、可走查的 Jaffle Shop 教学环境。【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
