preview_virtual_dimension_draft
Preview per-rule costs or a groupBy breakdown (read-only BigQuery). virtualDimensionId in inputs equals id from list/get/search. Operates on the latest pending draft if one exists (draftPersisted: true); otherwise previews published rules in memory without creating a draft (draftPersisted: false — not publishable). To publish changes after editing published-only state, call update_virtual_dimension_draft for an existing virtualDimensionId (or create_virtual_dimension_draft for a brand-new VDIM) — preview alone does not persist. Call after a successful create/update. Read the "summary" field first. Both modes share the same time window: optional datePreset (official presets — TRAILING_30_DAYS default, same enum as dashboards) or explicit from/to (YYYY-MM-DD, same shape as query); mutually exclusive. mode "costs": per-rule costs with totals.namedRulesSharePercent / totals.leftoverSharePercent, each rule's conditionCel and allocatesTo, plus howToRead. mode "breakdown": spend inside a target rule (ruleId or ruleIndex) split by groupBy — returns period (datePreset or from/to), scope.explanation, topValues[{ value, cost, percentOfScope }], and dailyTotals (not raw chart JSON). Discover valid groupBy values via search with type: ["dimensions"]. position (from get and preview costs output) and ruleIndex (preview/overlap input) refer to the same 0-based ordinal in the ordered rule list [...rules, leftover]. Prefer ruleId over ruleIndex. Target leftover via ruleId of leftoverRule or ruleIndex: rules.length. Optional currency (default USD) — pass the same value as query cost queries to align totals. costMetric selects the cost column (default cost); valid ids: cost, effective_cost, list_cost, contracted_cost (also accepts contracted_costs), unblended_cost, net_unblended_cost, amortized_cost, net_amortized_cost.
EXAMPLES:
• "Preview Environment VDIM draft costs" → { virtualDimensionId: "<virtualDimensionId from create/list>", mode: "costs" }
• "What cos_region values sit inside Production?" → { virtualDimensionId: "<virtualDimensionId from create/list>", mode: "breakdown", ruleId: "<from get/preview costs>", groupBy: "cos_region", datePreset: "TRAILING_30_DAYS" }
• "Preview costs in EUR to match earlier queries" → { virtualDimensionId: "<virtualDimensionId from create/list>", mode: "costs", currency: "EUR", from: "2025-01-01", to: "2025-03-31" }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | Explicit window end (YYYY-MM-DD). Use with from instead of datePreset — same shape as query. | |
| from | No | Explicit window start (YYYY-MM-DD). Use with to instead of datePreset — same shape as query. | |
| mode | Yes | `costs` (per-rule costs including leftover and rule metadata) or `breakdown` (drill into a rule). | |
| slug | No | Organization slug. Omit to auto-detect from your account (fails if you belong to multiple orgs). | |
| ruleId | No | Target rule id (breakdown mode; preferred over ruleIndex) | |
| groupBy | No | Dimension to split by (breakdown mode) | |
| currency | No | Cost currency (default USD). Pass the same currency as prior query calls to align preview totals. | |
| ruleIndex | No | Target rule index (breakdown mode fallback) | |
| costMetric | No | Cost column id (default cost). Valid: cost, effective_cost, list_cost, contracted_cost, unblended_cost, net_unblended_cost, amortized_cost, net_amortized_cost (also accepts contracted_costs → contracted_cost). | |
| datePreset | No | Official date preset (same values as dashboards/query context). Default TRAILING_30_DAYS. Mutually exclusive with from/to. | |
| virtualDimensionId | Yes | Virtual dimension id (stable public identifier) |