beast-mode-creation（野兽模式创建）

Beast Mode Generator

Create Domo beast modes (calculated fields) and output curl commands to execute them.

Beast modes are virtual columns computed from existing dataset columns using MySQL-style formulas. They can be scoped to a single card or shared across all cards on a dataset.

When to Use This Skill

• User asks for a field that doesn't exist in the schema
• A visualization needs a derived metric (percentages, concatenations, conditionals)
• User mentions "beast mode", "calculated field", "formula", or describes a computation
• You're building a card and realize the needed column must be computed

Core Workflow

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)

Prerequisites

These values are typically available from the CLI tool context:

If any are missing, ask the user before generating commands.

Step 1: Build the Formula

Write formulas using MySQL syntax. Always wrap column names in backticks.

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

For a comprehensive list of supported functions and formula patterns, read references/formula-examples.md.

Quick syntax rules:

• Column names must be in backticks: column_name
• String literals use single quotes: 'active'
• CASE requires WHEN and END: CASE WHEN... THEN... ELSE... END
• Domo follows older MySQL syntax — most standard MySQL functions work

Before writing the formula, check that every column you reference actually exists in the dataset schema. If you already have the schema (from context or a prior fetch), compare the user's requested columns against it. If a column doesn't exist, stop and tell the user — don't generate a formula with columns that aren't in the data. This catches errors early, before you even reach the validation step.

Step 2: Fetch the Column Schema

If you don't already have the dataset's columns, fetch them first. The schema is needed for formula validation and to confirm column names are correct.

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

The response returns an array of column objects. Each has name, type, and other metadata. Save this — you'll need it for validation.

Step 3: Validate the Formula

Always validate before generating the creation curl. This catches typos, missing columns, and syntax errors before they hit the API.

Endpoint: 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}"
      }
    }
  }'

The columns array must include every column in the dataset (use the schema response from Step 2). The formulas object is keyed by a unique ID you generate (e.g., calculation_abc123).

Success response:

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

If validation fails, check:

• invalidColumns — column name doesn't exist (typo? check schema)
• status: "INVALID" — formula syntax error
• Show the user the error and ask them to clarify before proceeding

Use the validation response to populate fields in the creation payload:

• dataType from the result (the API infers the correct return type)
• containsAggregation → maps to aggregated in the creation payload
• columnPositions → include in the creation payload

Step 4: Choose Scope

Default to dataset-level — it's reusable across all cards on the dataset and is the more common need.

Use card-level only when the user explicitly says it's single-use, or the formula is specific to one visualization's configuration.

Don't ask unless you genuinely can't tell. If the formula represents a business metric (revenue, margin, count, status flag), it almost certainly belongs on the dataset.

Step 5: Generate Curl Commands

Dataset-Level (Default) — Two Steps

Step 5a: Create the beast mode on the dataset

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
  }'

Response — save the id and legacyId:

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

Step 5b: Read the existing card, merge, and update

The card update endpoint (PUT /content/v3/cards/kpi/{cardId}) replaces the full definition. You must read the card first, add the beast mode to formulas.dsUpdated, and PUT the whole thing back.

Read the card:

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}"
  }'

Merge the beast mode into the response by adding to 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 the merged card back:

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}'

Card-Level — Single Step

Read the existing card first (same as above), then add to definition.formulas.card[] instead:

{
  "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
}

Then PUT the full merged card body.

Key Differences: Card-Level vs Dataset-Level

Data Types

Use the type returned by the validation endpoint when possible. Common values:

Troubleshooting

Output Format

When generating curl commands for the user, provide:

1. What it does — one sentence explaining the beast mode
2. The formula — so they can verify the logic
3. Numbered curl commands — in execution order, ready to copy/paste
4. What to do with each response — especially saving legacyId from Step 5a
5. Verify — tell them to check the card in Domo after running