ra-data-export

name

RA:data-export

description

Controlled Tableau, DuckDB, MySQL, and ClickHouse data export for RealAnalyst/Codex. Use when an analysis task needs to fetch formal CSV data from a registered source in the unified SQLite registry, including Tableau view/domain exports with vf/vp filters and SQL table/view exports with field whitelist, filters, aggregation, and audited job metadata updates. Triggers: tableau export, duckdb export, mysql export, clickhouse export, 受控取数, 数据导出, 补数, 追加分析, export_summary, duckdb_export_summary, data_export_summary.

Data Export Skill

统一处理 RealAnalyst 的正式取数：Tableau、DuckDB、MySQL 与 ClickHouse 都必须从已注册的 runtime registry 中选择 source，导出到 jobs/{SESSION_ID}/data/*.csv，并更新 job 审计元数据与 job_manifest.json。原始导出默认是内部证据，不是用户附件；只有显式登记为 user_attachment 的汇总表/工作簿才进入用户可见清单。

本 skill 是 RA:analysis-run 的流程内受控取数阶段，不作为普通用户第一层入口。用户想做完整分析时优先进入 RA:analysis-run；数据源未注册时先进入 RA:metadata。

如果用户只要求“导出结果字段名转中文 / CSV 表头中文化 / 展示名调整”，仍属于 export/display layer：通过 --select、输出 CSV header、manifest 或后处理映射解决，不修改 metadata/datasets/*.yaml 的 fields[].name。fields[].name 是稳定语义 ID，中文展示名写在 display_name，物理源字段写在 physical_name / source_field。

本 skill 是原 tableau-export 与 duckdb-export 的合并版。原脚本保留在后端子目录中：

• Tableau: skills/data-export/scripts/tableau/
• DuckDB: skills/data-export/scripts/duckdb/
• MySQL: skills/data-export/scripts/mysql/
• ClickHouse: skills/data-export/scripts/clickhouse/

通用硬规则

0. 正式导出前先复用 RA:getting-started doctor 输出的 python_command、skill_base_dir 和 registry_path；不要在本 skill 内自由发现 Python、DuckDB CLI 或 registry 位置。
1. 先用 runtime/tableau/query_registry.py 搜索、锁定并确认 source，不要自由拼接连接信息。
2. 只允许导出 registry/spec 中已注册、status=active 的 source。
3. 正式输出必须写入 jobs/{SESSION_ID}/，不要把正式 CSV 写到临时目录后再口头引用。
4. 连续分析中继续使用同一个 SESSION_ID；补同一 source 的数据可以直接执行，但要写明原因。
5. 引入新 source 前必须获得用户确认，并在 acquisition log 中标记 --is-new-source --confirmed。
6. 导出后优先使用 wrapper 脚本，因为 wrapper 会同步更新 .meta/acquisition_log.jsonl、.meta/artifact_index.json 与 job_manifest.json。

Step 1：查询 registry

./scripts/py runtime/tableau/query_registry.py --search <keyword>
./scripts/py runtime/tableau/query_registry.py --source <source_id> --with-context
./scripts/py runtime/tableau/query_registry.py --filter <source_id>
./scripts/py runtime/tableau/query_registry.py --fields <source_id>

读取 source_backend 后再进入对应后端流程。

Tableau 后端

推荐入口

./scripts/py skills/data-export/scripts/tableau/tableau_export_with_meta.py \
  --source-id <tableau_source_id> \
  --session-id $SESSION_ID \
  --vf "<filter_field>=<value>" \
  --vp "<parameter_field>=<value>" \
  --reason "<why this export is needed>"

直接导出入口（仅排障）

./scripts/py skills/data-export/scripts/tableau/export_source.py \
  --source-id <tableau_source_id> \
  --session-id $SESSION_ID \
  --vf "<filter_field>=<value>" \
  --vp "<parameter_field>=<value>"

Tableau 参数规则

• filters: 中定义的项用 --vf。
• parameters: 中定义的项用 --vp。
• type: view：只传 --source-id。
• type: domain：传 --source-id <domain_source_id> --views <view_id,...>。
• 枚举型筛选字段支持多选时，可在单次 --vf 中用逗号传多个值。

详细说明按需读取：

• references/tableau/export-modes.md
• references/tableau/filter-usage.md
• references/tableau/filters-fallback.md
• references/tableau/budget-and-recovery.md

DuckDB 后端

推荐入口

./scripts/py skills/data-export/scripts/duckdb/duckdb_export_with_meta.py \
  --source-id <duckdb_source_id> \
  --session-id $SESSION_ID \
  --output-name <name>.csv \
  --select "field_a,field_b" \
  --filter "region=East" \
  --reason "<why this export is needed>"

聚合示例

./scripts/py skills/data-export/scripts/duckdb/duckdb_export_with_meta.py \
  --source-id <duckdb_source_id> \
  --session-id $SESSION_ID \
  --output-name revenue_by_region.csv \
  --group-by "region" \
  --aggregate "revenue:sum:total_revenue" \
  --order-by "total_revenue:desc"

直接导出入口（仅排障）

./scripts/py skills/data-export/scripts/duckdb/export_duckdb_source.py \
  --source-id <duckdb_source_id> \
  --session-id $SESSION_ID \
  --output-name <name>.csv \
  --select "field_a,field_b"

DuckDB 安全边界

• 只能使用注册字段做 --select、--filter、--date-range、--group-by、--aggregate、--order-by。
• 过滤语法仅支持 field=value、field!=value、field~keyword。
• 聚合函数仅支持 sum、avg、min、max、count。
• 禁止导出 TEMP_、ToDrop_ 等临时/废弃对象。

完整输出契约见 references/duckdb/output-contract.md。

MySQL / ClickHouse 后端

MySQL 和 ClickHouse 使用与 DuckDB 相同的字段白名单、filter、date range、group-by、aggregate、order-by 参数模型，但连接信息只来自 runtime registry 中的 connection_ref / credential_ref / dsn_env 环境变量名。

推荐入口

./scripts/py skills/data-export/scripts/mysql/mysql_export_with_meta.py \
  --source-id <mysql_source_id> \
  --session-id $SESSION_ID \
  --output-name <name>.csv \
  --select "field_a,field_b" \
  --filter "region=East" \
  --reason "<why this export is needed>"

./scripts/py skills/data-export/scripts/clickhouse/clickhouse_export_with_meta.py \
  --source-id <clickhouse_source_id> \
  --session-id $SESSION_ID \
  --output-name <name>.csv \
  --select "field_a,field_b" \
  --filter "region=East" \
  --reason "<why this export is needed>"

安全边界

• 只能使用注册字段做 --select、--filter、--date-range、--group-by、--aggregate、--order-by。
• 过滤语法仅支持 field=value、field!=value、field~keyword。
• 聚合函数仅支持 sum、avg、min、max、count。
• 不提供任意 SQL 输入入口。
• 不把密码、token、DSN 明文写入 metadata YAML、summary、报告或 git-tracked example。

输出契约

Tableau wrapper 成功后通常产生：

• jobs/{SESSION_ID}/data/交叉_<source_or_view>.csv
• jobs/{SESSION_ID}/export_summary.json
• jobs/{SESSION_ID}/source_context.json
• jobs/{SESSION_ID}/context_injection.md
• jobs/{SESSION_ID}/.meta/acquisition_log.jsonl
• jobs/{SESSION_ID}/.meta/artifact_index.json
• jobs/{SESSION_ID}/job_manifest.json（raw export / summary 默认登记为内部材料）

DuckDB wrapper 成功后通常产生：

• jobs/{SESSION_ID}/data/<output-name>.csv
• jobs/{SESSION_ID}/duckdb_export_summary_<output-name>_<timestamp>.json
• jobs/{SESSION_ID}/duckdb_export_summary.json（latest pointer，便于兼容旧流程）
• jobs/{SESSION_ID}/.meta/acquisition_log.jsonl
• jobs/{SESSION_ID}/.meta/artifact_index.json
• jobs/{SESSION_ID}/context_injection.md（若 metadata/osi/<dataset_id>/context.md 存在则自动复制）
• jobs/{SESSION_ID}/job_manifest.json（raw export / summary 默认登记为内部材料）

MySQL / ClickHouse wrapper 成功后通常产生：

• jobs/{SESSION_ID}/data/<output-name>.csv
• jobs/{SESSION_ID}/mysql_export_summary_<output-name>_<timestamp>.json 或 clickhouse_export_summary_<output-name>_<timestamp>.json
• jobs/{SESSION_ID}/mysql_export_summary.json 或 clickhouse_export_summary.json
• jobs/{SESSION_ID}/data_export_summary.json（connector-neutral latest pointer）
• jobs/{SESSION_ID}/.meta/acquisition_log.jsonl
• jobs/{SESSION_ID}/.meta/artifact_index.json
• jobs/{SESSION_ID}/job_manifest.json（raw export / summary 默认登记为内部材料）

wrapper 输出的 context_injection.available 字段标明是否成功复制。若 context_injection.available=false，下游分析应直接读取 metadata/osi/<dataset_id>/context.md 作为等效语义上下文。

验证

./scripts/py skills/data-export/scripts/tableau/export_source.py --help
./scripts/py skills/data-export/scripts/tableau/tableau_export_with_meta.py --help
./scripts/py skills/data-export/scripts/duckdb/export_duckdb_source.py --help
./scripts/py skills/data-export/scripts/duckdb/duckdb_export_with_meta.py --help
./scripts/py skills/data-export/scripts/mysql/export_mysql_source.py --help
./scripts/py skills/data-export/scripts/mysql/mysql_export_with_meta.py --help
./scripts/py skills/data-export/scripts/clickhouse/export_clickhouse_source.py --help
./scripts/py skills/data-export/scripts/clickhouse/clickhouse_export_with_meta.py --help
./scripts/py skills/data-export/scripts/duckdb/run_tests.py

run_tests.py 需要先安装 duckdb 并准备 demo DuckDB registry/data。若未准备 DuckDB 文件，帮助命令仍应能跑通，但正式导出会失败。

Completion Summary

导出完成后，用下面结构向用户汇报，并按本次结果动态裁剪：

完成情况：
- 已完成取数：<面向用户的业务数据名称、行数、列数>
- 已使用后端和筛选条件：<Tableau / DuckDB / MySQL / ClickHouse，filters / date range / fields>
- 已完成内部登记：<导出摘要、采集记录、job manifest，按实际保留>

下一步建议：
- 最推荐下一步：/skill RA:data-profile ...（对正式 CSV 生成画像，通常由 RA:analysis-run 继续编排）
- 可选下一步：/skill RA:artifact-fusion ...（仅在 source group 多源导出需要合并时）
- 可选下一步：/skill RA:analysis-run ...（回到正式分析 job 后续 Phase）

边界提醒：
- 本 skill 是流程内取数阶段，没有生成业务结论或报告。
- 本 skill 只从 runtime registry 中已注册 source 取数；缺 source 或字段时回到 /skill RA:metadata。
- 本 skill 只更新 CSV 和 job 审计产物；CSV/header/display name 问题在导出层解决，不修改 metadata YAML。
- 默认不要向普通用户展示原始 CSV 路径、summary JSON、artifact index、job manifest 或内部 source key；用户明确要求技术复核时再补路径。