SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场wren-dlt-connector

wren-dlt-connector

数据与分析

查看项目

更新于 10-15 10:24

技能介绍

用途

wren-dlt-connector 用于把 SaaS 数据（如 HubSpot、Stripe、Salesforce、GitHub、Slack 等）接入 Wren Engine，以便进行 SQL 分析。它覆盖从零到可验证、可查询项目的完整流程，目标是在一次对话中完成搭建。

该技能面向懂 SQL 和部分 Python、但可能未使用过 dlt 或 Wren 的数据分析师。对首次出现的概念会做简要解释，但不会过度解释 SQL 使用者已知的内容。

主要能力

技能围绕四个阶段展开：

  1. Extract（抽取）：使用 dlt（data load tool）从 SaaS API 拉取数据到本地 DuckDB 文件。
  2. Model（建模）：内省 DuckDB 模式，自动生成 Wren 语义项目（YAML 模型、关系、profile）。
  3. Build & Verify（构建与验证）：构建项目并运行实际 SQL 查询，确认端到端可用。
  4. Handoff（交接）：向用户展示数据与后续步骤。

用户可能从任意阶段进入，技能会先询问起始阶段——例如用户可能已有 .duckdb 文件，只需阶段 2–4。

使用方式

阶段 1：抽取——dlt 管道设置

  • 询问用户要连接哪个 SaaS 服务。可参考 references/dlt_sources.md 中列出的热门已验证源及其认证要求；若未列出，可检查 dlt 是否有对应已验证源。
  • 安装 dlt：
pip install "dlt[duckdb]" --break-system-packages
  • 编写管道脚本，导入所选 SaaS 的 dlt 源函数，配置 destination='duckdb' 与本地文件路径，并运行 pipeline.run(source)。通用模式如下（需按源调整）：
import dlt

pipeline = dlt.pipeline(
    pipeline_name="<source>_pipeline",
    destination="duckdb",
    dataset_name="<source>_data",
)

# Source-specific: check references/dlt_sources.md for auth patterns
source = <source_function>(api_key=dlt.secrets.value)

info = pipeline.run(source)
print(info)
  • 设置凭据：dlt 从环境变量或 .dlt/secrets.toml 读取凭据。一次性运行最简单的方式是设置环境变量，具体变量名取决于源。提醒用户不要将凭据提交到 git；重复使用可创建 .dlt/secrets.toml。
  • 运行管道：python <pipeline_script>.py。运行后确认无错误、生成了 .duckdb 文件，并打印发现的表及列数。

阶段 2：建模——生成 Wren 项目

运行内省脚本，从 DuckDB 文件自动生成完整 Wren 项目：

python <path-to-this-skill>/scripts/introspect_dlt.py \
    --duckdb-path <path-to-duckdb-file> \
    --output-dir <project-directory> \
    --project-name <name>

该脚本会：以只读方式连接 DuckDB；将 table_reference.catalog 设为 DuckDB 文件名主干（匹配 wren engine 的 ATTACH 行为）；通过 information_schema 发现所有表和列；过滤 dlt 内部表（_dlt_loads、_dlt_pipeline_state 等）；从模型定义中过滤 dlt 元数据列（_dlt_id、_dlt_load_id、_dlt_list_idx）；从 _dlt_parent_id 列和表命名约定检测父子关系；使用 wren.type_mapping.parse_type()（基于 sqlglot）规范化列类型；生成完整的 v2 YAML 项目（wren_project.yml、models/、relationships.yml、instructions.md）。

生成后需抽查一个模型，确认 table_reference.catalog 与 DuckDB 文件名一致、schema 匹配（通常为 main）、无 dlt* 列、列类型合理。

随后创建 Wren profile，使用户无需每次指定连接信息。url 必须指向包含 .duckdb 文件的目录（而非文件本身）：

import yaml
from pathlib import Path

wren_home = Path.home() / ".wren"
wren_home.mkdir(exist_ok=True)
profiles_file = wren_home / "profiles.yml"

existing = (yaml.safe_load(profiles_file.read_text()) or {}) if profiles_file.exists() else {}
existing.setdefault("profiles", {})

profile_name = "<source>_dlt"
existing["profiles"][profile_name] = {
    "datasource": "duckdb",
    "url": str(Path("<duckdb-path>").resolve().parent),
    "format": "duckdb",
}
existing["active"] = profile_name

profiles_file.write_text(yaml.dump(existing, default_flow_style=False, sort_keys=False))

阶段 3：构建与验证——项目必须真正可用

此阶段不可省略。仅生成 YAML 但查询失败的项目不算成功。

  • 构建 MDL：
cd <project-directory>
wren context build

这会编译 YAML 模型到 target/mdl.json。若失败，需先修复。

  • 用真实查询验证：对每个生成的模型至少运行一次查询，确认项目可用：
wren --sql 'SELECT COUNT(*) as total FROM "<table_name>"'

若查询失败，需调试并修复模型。常见问题包括：table_reference 中 catalog 错误导致“table not found”；类型不匹配需在 metadata.yml 中修正列类型；缺少 profile 需检查 wren profile list。

  • 运行更有意思的查询：基础查询通过后，再运行 2–3 个查询向用户展示数据样貌，例如预览数据、验证父子模型均可查询。

  • 确认成功：仅在查询返回真实数据后，才告知用户设置完成，并总结创建了多少模型、检测到哪些关系、哪个 profile 处于活动状态、以及可尝试的示例查询。

关键注意事项

  • DuckDB catalog 命名：wren engine 连接 DuckDB 文件时，使用文件名（不含 .duckdb 扩展名）作为 catalog 别名，例如 ATTACH DATABASE 'stripe_data.duckdb' AS "stripe_data" (READ_ONLY)。因此每个模型的 table_reference.catalog 必须等于 DuckDB 文件名主干。若文件为 hubspot.duckdb，catalog 就是 hubspot。弄错会导致查询时“table not found”。introspect_dlt.py 脚本会自动处理。
  • 类型规范化：列类型必须使用 wren SDK 的 type_mapping.parse_type() 函数规范化，它使用 sqlglot 将数据库特定类型（如 DuckDB 的 HUGEINT、TIMESTAMP WITH TIME ZONE）转换为 wren-core 理解的规范 SQL 类型。不要硬编码类型映射，始终委托给 parse_type(raw_type, "duckdb")。introspect_dlt.py 在安装 wren SDK 后会自动执行。
  • dlt 的 _dlt_parent_id / _dlt_id 列保留在实际 DuckDB 表中，但从 Wren 模型定义中隐藏，仅用于关系条件。
  • DuckDB 有单写入者限制。查询时不要运行 dlt 同步。如需并发访问，dlt 应写入单独文件并原子交换。
  • 生成的模型使用 table_reference（而非 ref_sql），因为它们直接映射到 dlt 创建的 DuckDB 表。
  • 列类型使用 wren SDK 的 parse_type() 配合 sqlglot 的 DuckDB 方言规范化。若类型看起来不对，用户可直接编辑模型的 metadata.yml。

适用场景

适合需要将 SaaS 数据快速接入 Wren Engine 进行 SQL 分析的数据分析师，尤其是已熟悉 SQL 和部分 Python、希望以对话方式完成从抽取到验证全流程的用户。

限制

  • 需要用户提供 SaaS API 密钥或令牌。
  • 依赖 dlt 是否支持目标 SaaS 源。
  • DuckDB 单写入者限制，查询与同步不能并发。
  • 项目必须通过实际查询验证，仅生成文件不算成功。
  • 关于收费、价格、平台支持范围等具体信息，资料中暂未提供。