beast-mode-creation

Beast Mode 生成器

创建 Domo beast mode（计算字段）并输出用于执行它们的 curl 命令。

Beast mode 是使用 MySQL 风格公式从现有数据集列计算得出的虚拟列。它们的作用范围可以限定为单个卡片，也可以在整个数据集的所有卡片之间共享。

何时使用此技能

• 用户请求 schema 中不存在的字段
• 可视化需要派生指标（百分比、拼接、条件判断）
• 用户提到 "beast mode"、"计算字段"、"公式"，或描述某种计算
• 你正在构建卡片，并意识到所需的列必须通过计算得出

核心工作流

1. Identify what to compute and from which columns
2. Build the formula (MySQL syntax, backticks around column names)
3. Fetch the column schema (if not already available)
4. Validate the formula via the Domo API
5. Choose scope: dataset-level (default) or card-level
6. Generate curl command(s)

---

前提条件

这些值通常可从命令行工具上下文中获取：

参数	来源	是否必需
instanceUrl	Domo 实例（例如 domo-gordon-pont.domo.com）	始终必需
devToken	命令行认证 / 开发者令牌	始终必需
dataSourceId	数据集 UUID	始终必需
cardId	卡片 ID	用于附加到卡片
userId	当前用户的 Domo ID	用于数据集级别（owner 字段）

如果有任何一项缺失，请在生成命令前询问用户。

---

第 1 步：构建公式

使用 MySQL 语法编写公式。始终用反引号包裹列名。

SUM(`hourly_cost_rate`)                              -- aggregate
CONCAT(`first_name`, ' ', `last_name`)               -- string
(`revenue` - `cost`) / `revenue` * 100               -- ratio
CASE WHEN `status` = 'active' THEN 1 ELSE 0 END      -- conditional

有关受支持函数和公式模式的完整列表，请阅读 references/formula-examples.md。

快速语法规则：

• 列名必须放在反引号中：column_name
• 字符串字面量使用单引号：'active'
• CASE 需要 WHEN 和 END：CASE WHEN ... THEN ... ELSE ... END
• Domo 遵循较旧的 MySQL 语法 — 大多数标准 MySQL 函数均可使用

在编写公式之前，请检查你引用的每一列是否确实存在于数据集 schema 中。如果你已经拥有 schema（来自上下文或之前的获取），请将用户请求的列与之比对。如果某列不存在，请停下来并告知用户 — 不要生成包含数据中不存在的列的公式。这可以在你甚至到达验证步骤之前就及早发现错误。

---

第 2 步：获取列 schema

如果你还没有数据集的列，请先获取它们。schema 是公式验证所必需的，也用于确认列名是否正确。

curl -X GET "https://{instanceUrl}/api/query/v1/datasources/{dataSourceId}/schema/indexed?includeHidden=true" \
  -H "X-DOMO-Developer-Token: {devToken}"

响应会返回一个列对象数组。每个列对象包含 name、type 及其他元数据。请保存它 — 验证时会用到。

---

第 3 步：验证公式

在生成创建用的 curl 之前，始终先进行验证。这可以在错误到达 API 之前捕获拼写错误、缺失的列和语法错误。

端点： POST /api/query/v1/functions/validateFormulas

curl -X POST "https://{instanceUrl}/api/query/v1/functions/validateFormulas" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "dataSourceId": "{dataSourceId}",
    "columns": [
      {
        "id": "first_name",
        "name": "first_name",
        "label": "first_name",
        "type": "string",
        "isCalculation": false,
        "isVariable": false,
        "isAggregatable": true,
        "columnName": "first_name"
      }
    ],
    "formulas": {
      "{formulaId}": {
        "id": "{formulaId}",
        "name": "{fieldName}",
        "formula": "{formula}",
        "status": "valid",
        "dataType": "{dataType}"
      }
    }
  }'

columns 数组必须包含数据集中的每一列（使用第 2 步的 schema 响应）。formulas 对象以你生成的唯一 ID 为键（例如 calculation_abc123）。

成功响应：

{
  "allValid": true,
  "results": {
    "{formulaId}": {
      "status": "VALID",
      "dataType": "LONG",
      "containsAggregation": true,
      "columnPositions": [{"columnName": "`hourly_cost_rate`", "columnPosition": 4}]
    }
  }
}

如果验证失败，请检查：

• invalidColumns — 列名不存在（拼写错误？检查 schema）
• status: "INVALID" — 公式语法错误
• 向用户展示错误，并在继续之前请他们澄清

使用验证响应来填充创建负载中的字段：

• 来自结果的 dataType（API 会推断正确的返回类型）
• containsAggregation → 映射到创建负载中的 aggregated
• columnPositions → 包含在创建负载中

---

步骤 4：选择作用范围

默认使用数据集级 —— 它可在数据集上的所有卡片中复用，也是更常见的需求。

仅当用户明确表示它是一次性使用，或该公式特定于某个可视化的配置时，才使用卡片级。

除非你确实无法判断，否则不要询问。如果该公式表示业务指标（收入、利润率、计数、状态标志），它几乎肯定属于数据集级。

---

步骤 5：生成 Curl 命令

数据集级（默认）—— 两步

步骤 5a：在数据集上创建 beast mode

curl -X POST "https://{instanceUrl}/api/query/v1/functions/template?strict=false" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "{fieldName}",
    "owner": {userId},
    "locked": false,
    "global": false,
    "expression": "{formula}",
    "links": [
      {
        "resource": {"type": "DATA_SOURCE", "id": "{dataSourceId}"},
        "visible": true,
        "active": false,
        "valid": "VALID"
      }
    ],
    "aggregated": {true|false},
    "analytic": false,
    "nonAggregatedColumns": [],
    "dataType": "{dataType}",
    "status": "VALID",
    "cacheWindow": "non_dynamic",
    "columnPositions": [{from validation response}],
    "functions": [],
    "functionTemplateDependencies": [],
    "archived": false,
    "hidden": false,
    "variable": false
  }'

响应 —— 保存 id 和 legacyId：

{
  "id": "calculation_549b9c1f-71cc-4227-bb9c-3ae5064be416",
  "legacyId": "calculation_549b9c1f-71cc-4227-bb9c-3ae5064be416",
  "templateId": 1161,
  ...
}

步骤 5b：读取现有卡片，合并并更新

卡片更新端点（PUT /content/v3/cards/kpi/{cardId}）会替换完整定义。你必须先读取卡片，将 beast mode 添加到 formulas.dsUpdated，然后把整个内容 PUT 回去。

读取卡片：

curl -X PUT "https://{instanceUrl}/api/content/v3/cards/kpi/definition" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{
    "dynamicText": true,
    "variables": true,
    "urn": "{cardId}"
  }'

将 beast mode 合并到响应中，方法是添加到 definition.formulas.dsUpdated：

{
  "name": "{fieldName}",
  "id": "{legacyId from Step 5a response}",
  "persistedOnDataSource": true,
  "initialPersistedOnDataSource": false,
  "label": "{fieldName}",
  "type": "{dataType}",
  "formula": "{formula}",
  "value": "{formula}",
  "isVariable": false,
  "isCalculation": true,
  "isAggregatable": false,
  "status": "VALID",
  "dataType": "{dataType}",
  "templateId": {templateId from Step 5a response},
  "owner": {userId},
  "locked": false,
  "saved": false,
  "query": "{formula}",
  "containsAggregation": {true|false},
  "containsAnalytic": false,
  "cacheWindow": "non_dynamic",
  "columnPositions": [{from validation response}],
  "formulaId": "{id from Step 5a response}",
  "formulaDependencies": [],
  "legacyId": "{legacyId from Step 5a response}",
  "isControlled": false
}

将合并后的卡片 PUT 回去：

curl -X PUT "https://{instanceUrl}/api/content/v3/cards/kpi/{cardId}" \
  -H "X-DOMO-Developer-Token: {devToken}" \
  -H "Content-Type: application/json" \
  -d '{merged card body}'

---

卡片级 —— 单步

先读取现有卡片（同上），然后改为添加到 definition.formulas.card[]：

{
  "id": "{generate a UUID like calculation_<uuid>}",
  "name": "{fieldName}",
  "formula": "{formula}",
  "status": "VALID",
  "dataType": "{dataType}",
  "persistedOnDataSource": false,
  "isAggregatable": false,
  "bignumber": false,
  "nonAggregatedColumns": [],
  "templateId": -1,
  "legacyId": "{same as id}",
  "variable": false,
  "isCalculation": true,
  "initialPersistedOnDataSource": false,
  "saved": false,
  "query": "{formula}",
  "cacheWindow": "non_dynamic",
  "containsAggregation": {true|false},
  "containsAnalytic": false,
  "invalidColumns": [],
  "nonAggregatedExpressions": [],
  "formulaTemplateDependencies": [],
  "columnPositions": [{from validation response}],
  "formulaId": "{generate another UUID}",
  "formulaDependencies": [],
  "isControlled": false
}

然后 PUT 完整的合并后卡片正文。

---

关键差异：卡片级 vs 数据集级

方面	卡片级	数据集级
在负载中的位置	formulas.card[]	formulas.dsUpdated[]
persistedOnDataSource	false	true
templateId	-1	服务器分配的整数
owner	不包含	必需（用户 ID）
可见性	仅此卡片	此数据集上的所有卡片
API 调用	1（读取 + 合并 + PUT）	2（POST 创建，然后读取 + 合并 + PUT）
可复用	否	是

---

数据类型

尽可能使用验证端点返回的类型。常见值：

类型	用于
LONG	整数、计数、布尔标志（0/1）
DECIMAL	货币、百分比、比率
DOUBLE	高精度小数
STRING	文本结果（CONCAT、返回字符串的 CASE）
DATE	日期计算

---

故障排除

问题	原因	修复
验证返回 invalidColumns	列名拼写错误或缺少反引号	检查 schema，用反引号包裹
验证返回 INVALID 状态	公式语法错误	检查括号、CASE/WHEN/END
PUT 卡片返回 400	卡片正文不完整	确保先读取卡片，并 PUT 完整的合并后正文
beast mode 在 UI 中不可见	persistedOnDataSource 值错误	false = 卡片级，true = 数据集级
PUT 后卡片丢失其图表/列	PUT 只包含了公式，而非完整正文	始终先读取卡片定义，合并，然后 PUT

---

输出格式

为用户生成 curl 命令时，请提供：

1. 功能说明 — 用一句话解释这个野兽模式
2. 公式 — 以便用户验证逻辑
3. 带编号的 curl 命令 — 按执行顺序排列，可直接复制粘贴
4. 每条响应的处理方式 — 尤其是保存 Step 5a 中的 legacyId
5. 验证 — 告诉用户运行后在 Domo 中检查卡片