beast-mode-creation

Beast Mode ジェネレーター

Domo の Beast Mode（計算フィールド）を作成し、実行するための curl コマンドを出力します。

Beast Mode は、MySQL 形式の数式を使用して既存のデータセット列から計算される仮想列です。単一のカードに適用することも、データセット上のすべてのカードで共有することもできます。

このスキルを使用するタイミング

• ユーザーがスキーマに存在しないフィールドを求めている
• ビジュアライゼーションで派生指標（パーセンテージ、連結、条件式）が必要
• ユーザーが「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)

---

前提条件

通常、これらの値は CLI ツールのコンテキストで利用できます。

パラメーター	ソース	必須
instanceUrl	Domo インスタンス（例：domo-gordon-pont.domo.com）	常に
devToken	CLI 認証／開発者トークン	常に
dataSourceId	データセット UUID	常に
cardId	カード ID	カードに適用する場合
userId	現在のユーザーの Domo ID	データセットレベル（所有者フィールド）の場合

不足している値がある場合は、コマンドを生成する前にユーザーに確認してください。

---

ステップ 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 関数が使用できます

数式を記述する前に、参照するすべての列がデータセットのスキーマに実際に存在することを確認してください。すでにスキーマを取得している場合（コンテキストまたは以前の取得から）、ユーザーが指定した列と照合します。列が存在しない場合は、処理を中止してユーザーに伝えてください。データに存在しない列を使った数式は生成しないでください。これにより、検証ステップに進む前にエラーを早期に検出できます。

---

ステップ 2：列スキーマを取得する

データセットの列をまだ取得していない場合は、先に取得してください。数式の検証と列名が正しいことの確認にスキーマが必要です。

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 のスキーマ応答を使用してください）。formulas オブジェクトのキーには、生成した一意の ID（例：calculation_abc123）を使用します。

成功時の応答：

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

検証に失敗した場合は、次の項目を確認してください。

• invalidColumns — 列名が存在しません（誤字ですか？スキーマを確認してください）
• status: "INVALID" — 数式の構文エラー
• ユーザーにエラーを伝え、続行する前に内容を確認してください

検証応答を使用して、作成ペイロードのフィールドに値を設定します。

• 結果から dataType を取得します（API が正しい戻り値の型を推論します）
• containsAggregation → 作成ペイロードの aggregated に対応します
• columnPositions → 作成ペイロードに含めます

---

ステップ 4：スコープを選択する

デフォルトではデータセットレベルを選択してください。データセット上のすべてのカードで再利用でき、より一般的なニーズに対応できます。

カードレベルを使用するのは、ユーザーが単一用途だと明示している場合、または数式が特定のビジュアライゼーションの設定に固有の場合に限ります。

本当に判断できない場合を除き、質問しないでください。数式がビジネスメトリック（売上、利益率、件数、ステータスフラグ）を表す場合は、ほぼ確実にデータセットに属します。

---

ステップ 5：Curl コマンドを生成する

データセットレベル（デフォルト）— 2 つのステップ

ステップ 5a：データセットにビーストモードを作成する

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}）は定義全体を置き換えます。まずカードを読み込み、ビーストモードを 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}"
  }'

レスポンスにビーストモードをマージし、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}'

---

カードレベル — 1 つのステップ

まず既存のカードを読み込み（上記と同じ）、代わりに 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 します。

---

カードレベルとデータセットレベルの主な違い

項目	カードレベル	データセットレベル
ペイロード内の場所	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 が返される	列名の誤り、またはバッククォートがない	スキーマを確認し、バッククォートで囲みます
検証で INVALID ステータスが返される	数式の構文エラー	括弧、CASE/WHEN/END を確認します
PUT カードが 400 を返す	カード本文が不完全	まずカードを読み込み、マージした本文全体を PUT してください
UI にビーストモードが表示されない	persistedOnDataSource の値が誤っている	false = カードレベル、true = データセットレベル
PUT 後にカードのチャート／列が失われる	PUT に数式だけが含まれ、本文全体が含まれていない	必ず最初にカード定義を読み込み、マージしてから PUT してください

---

出力形式

ユーザー向けに curl コマンドを生成するときは、次の内容を含めてください。

1. 内容 — ビーストモードの動作を説明する1文
2. 計算式 — ロジックを確認できるようにします
3. 番号付きの curl コマンド — 実行順に並べ、コピーして貼り付ければすぐに使える形式にします
4. 各レスポンスの処理方法 — 特に、ステップ5aで legacyId を保存する方法を説明します
5. 確認 — 実行後に Domo でカードを確認するよう伝えます