domo-data-generator

Domo 示例数据生成器

使用 datagen CLI 为 Domo 生成真实且相互引用的示例数据。

代码仓库： https://github.com/brrink/domo_data_generator

---

概述

该生成器会创建模拟主要业务平台的示例数据，并保证跨数据源的实体一致性，然后将其上传到 Domo。它包括：

• 6 个来源类别（Salesforce、Google Analytics、Financial、Marketing、Health、AdPoint）下的 18 个预置数据集
• 由 YAML 驱动的目录，便于轻松添加数据集
• 共享实体池（公司、人员、产品、销售代表、营销活动）
• 日期滚动，让数据看起来保持最新
• 直接集成 Domo（创建数据集、上传、设置连接器图标）
• 默认输出结构化 JSON（对 AI Agent 友好）
• 可通过 pipx 安装——可在任意目录运行

---

安装配置

# Install globally with pipx (recommended)
pipx install git+https://github.com/brrink/domo_data_generator.git

# Initialize a working directory
mkdir my-domo-data && cd my-domo-data
datagen init

# Edit .env with your Domo credentials

如果 .env.example 缺失，或者你想要一个干净的开始，请在工作目录中创建 .env，内容如下：

cat > .env <<'EOF'
DOMO_CLIENT_ID=your_client_id_here
DOMO_CLIENT_SECRET=your_client_secret_here
DOMO_API_HOST=api.domo.com
DOMO_INSTANCE=your_instance_name
DOMO_SET_CONNECTOR_TYPE=false
EOF

必需的环境变量

变量	用途
DOMO_CLIENT_ID	OAuth 客户端标识符
DOMO_CLIENT_SECRET	OAuth 客户端密钥
DOMO_API_HOST	API 端点主机名
DOMO_INSTANCE	Domo 实例名称
DOMO_SET_CONNECTOR_TYPE	启用连接器图标自定义（可选，默认：false）

认证边界说明： domo_data_generator 使用其自己的 public-API/OAuth 凭证流程，不会通过 community-domo-cli 或 ryuu 会话认证运行。

当前工具边界： 大多数 Product API 自动化应使用 community-domo-cli，但本技能中 datagen 数据集的创建/上传目前依赖 python -m datagen 以及 .env 中的 OAuth 凭证（DOMO_CLIENT_ID / DOMO_CLIENT_SECRET）。

---

CLI 参考

入口点：datagen [OPTIONS] COMMAND [ARGS]

全局选项

选项	描述
--verbose / -v	启用详细日志记录
--output / -o TEXT	输出格式：json（默认）、table、yaml
--yes / -y	跳过确认提示

所有命令默认输出结构化 JSON，便于机器解析。

Init 命令

init —— 初始化工作目录

datagen init                  # Initialize current directory
datagen init /path/to/dir     # Initialize a specific directory

将捆绑的目录 YAML 文件复制到 ./catalog/，创建 .env 模板，并创建 ./data/ 目录。在新的目录中使用 CLI 之前，请先运行一次此命令。

核心命令

generate —— 生成示例数据

datagen generate --all                    # Generate all datasets
datagen generate salesforce_opportunities  # Generate one dataset
datagen generate --all --seed 42          # Reproducible generation
datagen generate --all --dry-run          # Preview without writing

需要先初始化实体池。即使你的 schema 没有显式的 entity_ref 列，也请在 generate 之前运行 python -m datagen pool regenerate。

选项	描述
name	数据集名称（YAML 文件名主体），可选
--all	生成所有数据集
--seed INTEGER	用于可复现性的随机种子
--catalog-dir PATH	覆盖目录路径
--data-dir PATH	覆盖数据目录路径
--dry-run	预览而不写入文件

upload —— 上传数据到 Domo（完全替换）

datagen upload --all
datagen upload salesforce_opportunities

需要 DOMO_CLIENT_ID 和 DOMO_CLIENT_SECRET。

选项	描述
name	数据集名称，可选
--all	上传所有数据集
--catalog-dir PATH	覆盖目录路径
--data-dir PATH	覆盖数据目录路径

create-dataset —— 根据目录在 Domo 中创建数据集

datagen create-dataset --all --skip-existing
datagen create-dataset salesforce_opportunities

需要 DOMO_CLIENT_ID 和 DOMO_CLIENT_SECRET。domo_id 会持久化到本地（如果目录 YAML 可写，则写入其中；否则写入 data/domo_ids.json）。

选项	描述
name	数据集名称，可选
--all	创建所有数据集
--skip-existing	跳过已经有 domo_id 的数据集
--catalog-dir PATH	覆盖目录路径

roll-dates -- 滚动日期列以保持最新

datagen roll-dates
datagen roll-dates --anchor-date 2026-04-01

选项	描述
--anchor-date TEXT	目标日期（YYYY-MM-DD），默认为今天
--catalog-dir PATH	覆盖 catalog 目录
--data-dir PATH	覆盖 data 目录

信息命令

list -- 列出 catalog 数据集定义

datagen list                    # JSON output (default)
datagen --output table list     # Rich table for humans
datagen list --verbose          # Include column/schema details

status -- 显示所有数据集的生成状态

datagen status

连接器图标命令

需要 DOMO_DEVELOPER_TOKEN 和 DOMO_INSTANCE。

discover-types -- 搜索 Domo 连接器/提供商类型

datagen discover-types salesforce

set-type -- 在 Domo 数据集上设置连接器图标

datagen set-type salesforce_opportunities
datagen set-type salesforce_opportunities --provider-key custom_key

set-type-all -- 在所有带 domo_id 的数据集上设置连接器图标

datagen set-type-all

实体池命令

pool regenerate -- 重新生成共享实体池

datagen pool regenerate
datagen pool regenerate --seed 99
datagen pool regenerate --company-count 500 --person-count 1000

选项	默认值
--seed INTEGER	42
--company-count INTEGER	200
--person-count INTEGER	500
--product-count INTEGER	50
--sales-rep-count INTEGER	20
--campaign-count INTEGER	30

pool show -- 显示实体池摘要

datagen pool show

---

常见工作流

为新 Domo 实例进行完整设置

datagen init
# Edit .env with credentials
datagen pool regenerate
datagen generate --all
datagen create-dataset --all
datagen upload --all
datagen set-type-all

通过 cron 每日刷新

# Crontab entry: roll dates and re-upload daily at 6 AM
0 6 * * * cd /path/to/project && datagen roll-dates && datagen upload --all

端到端生成单个数据集

datagen generate salesforce_opportunities
datagen create-dataset salesforce_opportunities
datagen upload salesforce_opportunities
datagen set-type salesforce_opportunities

---

包含的数据集

类别	数据集名称	键	行数
Salesforce	Salesforce - Accounts	salesforce_accounts	500
Salesforce	Salesforce - Contacts	salesforce_contacts	1,500
Salesforce	Salesforce - Opportunities	salesforce_opportunities	2,500
Google Analytics	Google Analytics - Sessions	ga_sessions	5,000
Google Analytics	Google Analytics - Page Views	ga_pageviews	10,000
Financial	QuickBooks - Invoices	financial_invoices	3,000
Financial	NetSuite - General Ledger	financial_gl_entries	5,000
Marketing	Google Ads - Campaign Performance	marketing_google_ads	3,000
Marketing	Facebook Ads - Campaign Performance	marketing_facebook_ads	2,500
Marketing	HubSpot - Contacts	marketing_hubspot_contacts	2,000
Marketing	Marketing - Market Leads	marketing_market_leads	2,500
Marketing	Marketo - Leads	marketing_marketo_leads	3,000
Health	Health Portal - Demographics	health_demographics	15
Health	Health Portal - Lab Results	health_lab_results	1,470
Health	Health Portal - Vitals	health_vitals	5,250
AdPoint	AdPoint - Orders	adpoint_orders	150
AdPoint	AdPoint - Line Items	adpoint_line_items	500
AdPoint	AdPoint - Flights	adpoint_flights	2,000

---

实体池

共享实体池提供一致的跨数据集引用。实体会生成一次，并在所有数据集中重复使用。

实体类型	默认数量	关键字段
company	200	id, account_id, name, domain, industry, size, city, state, annual_revenue, employee_count
person	500	id, contact_id, first_name, last_name, full_name, email, company_id, company_name, title, phone
product	50	id, name, category, unit_price, sku
sales_rep	20	id, rep_id, first_name, last_name, full_name, email, region
campaign	30	id, name, channel, budget, status

---

添加新的数据集定义

数据集定义以 YAML 文件的形式存放在 catalog/ 目录中。每个 YAML 文件定义元数据、列和生成器配置。

YAML 结构

dataset:
  name: My Custom Dataset
  domo_id: null
  source_type: custom
  description: "Description of the dataset"
  row_count: 1000
  tags:
    - custom
    - demo

schema:
  - name: id
    type: STRING
    generator: uuid4

  - name: company_name
    type: STRING
    generator: entity_ref
    entity: company
    field: name

  - name: amount
    type: DOUBLE
    generator: random_decimal
    min: 100.0
    max: 10000.0
    precision: 2

  - name: created_date
    type: DATE
    generator: date_range
    start_days_ago: 365
    end_days_ahead: 0
    rolling: true

可用的列类型

STRING、LONG、DOUBLE、DECIMAL、DATETIME、DATE

可用生成器

通用： uuid4、random_choice、weighted_choice、random_int、random_decimal、date_range、entity_ref、compound、sequence、constant、derived_from_date、stage_derived、faker

Salesforce： sf_id、sf_opportunity_name、sf_case_subject、sf_lead_rating

Google Analytics： ga_session_id、ga_page_path、ga_source、ga_medium、ga_campaign、ga_browser、ga_device_category、ga_country、ga_bounce_rate、ga_session_duration、ga_pageviews、ga_landing_page

财务： gl_account_code、gl_account_name、invoice_number、payment_terms、payment_method、invoice_status、journal_type、department、fiscal_period、debit_credit

营销/广告： ad_platform、campaign_objective、ad_format、ad_headline、ad_keyword、targeting_type、impressions、clicks_from_impressions、ctr、cost_per_click、ad_spend、conversions_from_clicks、hubspot_lifecycle、hubspot_lead_status、ad_group_id

健康： health_lab_init、health_lab_field、health_vital_init、health_vital_field、health_demographics

生成器列选项

选项	用于	描述
entity	entity_ref	要引用的实体池类型
field	entity_ref	要从实体中提取的字段
choices	random_choice、weighted_choice	可能值的列表
min / max	random_int、random_decimal	值范围
precision	random_decimal	小数位数
template	compound	带有 {field} 占位符的字符串模板
refs	compound	用于模板替换的列引用 — 必须是列名字符串的 YAML 列表（例如 ["sku", "line_id"]），不能是 dict/object。dict 会触发 ValidationError: schema.N.refs — Input should be a valid list。
start_days_ago / end_days_ahead	date_range	相对于今天的日期范围
rolling	date_range	启用日期滚动以保持数据新鲜度
mapping	stage_derived	将源值映射到派生值
source_column	stage_derived、derived_from_date	要从中派生的列
format	derived_from_date	日期格式字符串
faker_method	faker	Faker 库方法名
faker_args	faker	Faker 方法的参数

weighted_choice YAML 格式：

generator: weighted_choice
choices:
  "Tier 1": 0.40
  "Tier 2": 0.35
  "Tier 3": 0.25

compound refs 与格式化的随机字符串： 对于像 PO-12345 这样的值，优先使用带有 bothify 的 faker，而不是滥用 compound / refs：

- name: purchase_order_ref
  type: STRING
  generator: faker
  faker_method: bothify
  faker_args:
    text: "PO-#####"

---

规则

1. 先运行 datagen init -- 在使用任何其他命令之前初始化工作目录。这会复制目录并创建 .env。
2. 始终在生成后上传 -- 在 upload 之前运行 generate（或 generate --all）以确保 CSV 数据文件存在。
3. 在首次上传前创建数据集 -- 对于新数据集，在 upload 之前运行 create-dataset。domo_id 会持久化到本地。
4. 使用 --skip-existing -- 运行 create-dataset --all 时，使用 --skip-existing 避免重复创建已有 domo_id 的数据集。
5. 实体池一致性 -- 重新生成池（pool regenerate）会使之前生成的所有数据失效。之后需要重新生成所有数据集。
6. 日期滚动 -- 在上传前使用 roll-dates 以保持日期列为最新。只有设置了 rolling: true 的列会受影响。
7. 凭据 -- upload 和 create-dataset 需要 DOMO_CLIENT_ID 和 DOMO_CLIENT_SECRET。set-type 和 discover-types 需要 DOMO_DEVELOPER_TOKEN。离线命令不需要凭据。
8. 可复现性 -- 使用 --seed 以便在多次运行中生成可复现的数据。
9. 输出格式 -- 默认输出为 JSON。使用 --output table 获得人类可读的 Rich 表格。

---

检查清单

• 已安装命令行工具（pipx install git+https://github.com/brrink/domo_data_generator.git）
• 已初始化工作目录（datagen init）
• 已使用 Domo 凭据配置 .env
• 已生成实体池（datagen pool regenerate）
• 已生成数据集（datagen generate --all）
• 已在 Domo 中创建数据集（datagen create-dataset --all --skip-existing）
• 已上传数据（datagen upload --all）
• 如需设置连接器图标（datagen set-type-all）
• 如需每日滚动日期和上传，已配置 Cron