Catalog Schema (Locked, Per-Calc Entry)
Schema authority for calc-inventory. Every catalog entry has these fields populated (or sentinel values per HC#8). Never invent an attribute. Never omit a required field.
Full Per-Calc Entry Schema
calc_name: {string}
calc_type: {row_level | aggregate | lod_fixed | lod_include | lod_exclude | table_calc}
formula: {formula_text}
return_type: {number | string | date | datetime | boolean | spatial | unknown}
is_aggregated_flag: {true | false}
derivation_prefix: {none | sum | usr}
references:
fields: [{field_name}, ...]
parameters: [{param_name} (cited, not resolved), ...]
sets: [{set_name} (cited, not resolved), ...]
hierarchies: [{hierarchy_name} (cited, not resolved), ...]
nested_calcs: [{calc_name}, ...]
external_references: [{ref_name}, ...] # references not resolvable in this DS
style_violations:
- rule_id: {S-NAME-01 | S-NAME-02 | ... | S-FORMAT-03}
severity: {error | warning | info}
rationale: {short_string}
perf_advisory_flags:
- flag_id: {PA-COUNTD-HIGH-CARDINALITY | PA-REGEXP-IN-AGGREGATE | ... | PA-STRING-ARITHMETIC}
rationale: {short_string}
complexity:
line_count: {N}
branch_depth: {N} # deepest IF/ELSEIF nesting
nested_lod_depth: {N} # 0 for non-LOD, 1 for flat, 2+ for nested
usage:
shelf_placements: {N | "unavailable_this_run"}
dashboards: [{dashboard_name}, ...] # or "unavailable_this_run"
flag: {unused | low_usage | in_use | unavailable_this_run}
notes: {optional_free_text}
Field-by-Field
- calc_name: the calc's user-visible name in the data source. Unique within a DS per Tableau's own model.
- calc_type: the calc's structural type.
row_levelfor bare arithmetic/string/date operations without aggregation wrappers.aggregatefor SUM/AVG/etc. wrappers.lod_*for FIXED/INCLUDE/EXCLUDE.table_calcfor WINDOW_/RUNNING_/RANK/INDEX/LOOKUP/PREVIOUS_VALUE. - formula: the full formula text as stored by Tableau. Never truncated in the YAML (markdown table may truncate for display).
- return_type: inferred from the formula's outermost operator.
unknownif not derivable (rare; usually broken calcs). - is_aggregated_flag: Tableau's own
isAggregatedflag fromlist-available-fields. Authoritative for AGG classification. - derivation_prefix: resolved via
resolve-field.usrfor AGG-flagged calcs,sumfor measure-role non-AGG calcs,nonefor dimension-role calcs. Never string-match the formula. - references.fields: every native field the formula references, in order of first appearance. No deduplication (a field cited twice is listed twice).
- references.parameters / sets / hierarchies: cited by name only. HC#6 forbids deeper resolution.
- references.nested_calcs: other calcs this calc references. Must resolve to another entry in the inventory OR appear in
external_references. - references.external_references: references not resolvable in this DS. Rare; usually indicates a broken calc, a cross-DS reference, or a stale reference from a consumed upstream handoff.
- style_violations: run from calc-linter's
style_catalog.md(read-only reference; never redefine). One entry per rule that fired. - perf_advisory_flags: run from calc-optimizer's
performance_hierarchy.md(read-only reference; never redefine). One entry per flag that fired. - complexity.line_count: count of newline characters + 1 in the formula.
- complexity.branch_depth: deepest IF/ELSEIF nesting depth. 0 for calcs with no IF branches. Counts nested IF-inside-IF, not sibling ELSEIFs (a 7-branch ELSEIF chain has branch_depth 1).
- complexity.nested_lod_depth: 0 for non-LOD calcs, 1 for a flat LOD, 2+ for nested LODs. Cited in
perf_advisory_flagsas PA-LOD-NESTED-DEPTH-2 when >=2. - usage.shelf_placements: count of worksheets where this calc appears on any shelf or mark encoding (Rows, Columns, Marks, Filters, Detail, etc.). From
search-workbook-fields. Sentinel"unavailable_this_run"if that tool call failed. - usage.dashboards: list of dashboard names that reference this calc (directly or transitively through worksheets). Empty list if unused. From
get-workbook-inventory. Sentinel"unavailable_this_run"if that tool call failed. - usage.flag: derived from shelf_placements and dashboards.
unusedif both are zero/empty.low_usageif placed on 1-2 worksheets and 0-1 dashboards.in_useotherwise.unavailable_this_runif either source tool failed for this entry. - notes: optional. Common uses: cycle detection (
"cycle: A → B → A"), external-reference rationale, style/perf-advisory caveats.
"Empty Entry" is Not Valid
Every field above MUST be populated per HC#8. Sentinel values (null, [], "unavailable_this_run") are acceptable substitutes; blank is not. A single-blank field blocks V-gate V1.
Derivation-Prefix Resolution (Locked)
resolve-field returns isAggregated: true for:
- Bare
SUM(...),AVG(...),COUNT(...),COUNTD(...),MIN(...),MAX(...),ATTR(...)wrappers. - Any
{FIXED ...},{INCLUDE ...},{EXCLUDE ...}LOD (regardless of what's inside the braces). - Any
WINDOW_*,RUNNING_*,RANK,INDEX,LOOKUP,PREVIOUS_VALUEtable calc.
isAggregated: false for:
- Bare row-level field references and arithmetic.
- Row-level string/date functions on native fields.
- Type-coercion functions (
INT,STR,FLOAT,DATE) applied to row-level fields.
derivation_prefix is usr when isAggregated: true, else sum for measure-role calcs, else none for dimension-role calcs. Confirmed across calc-writer/debugger/optimizer/linter behavioral runs 2026-09-04 through 2026-09-06.
Reference-Graph Rules (Locked)
- Every entry in
references.nested_calcsMUST resolve to another entry in the inventory OR appear inreferences.external_references. - Every entry in
references.external_referencesMUST have anotesblock explaining why (e.g., "references a calc from a different DS", "references a deleted calc"). - Cycles (A → B → A) are reported in the top-level
cycle_report, not silently included innested_calcs. Detection is depth-first traversal from every root calc; termination on revisiting an already-marked node. - Reference-graph consistency verified by V-gate V3 before delivery.
Batched-Pagination Reconciliation (Locked)
For 20+ calcs:
- Each batch produces a partial inventory of ~20 calcs.
- After all batches complete, reconcile into a single inventory:
- Deduplicate on
calc_name(calc names are unique within a DS per Tableau's own model). - Rebuild the reference graph across the full inventory (nested-calc references may span batches).
- Verify total count matches
list-available-fields's reported count.
- Deduplicate on
- V-gate V2 catches reconciliation errors before delivery.
Refuse to Fabricate
If any required field cannot be populated, use the appropriate sentinel value and note in notes. Never leave a field blank. Never invent a calc entry. Never mark a calc "unused" without confirming zero shelf placements AND zero downstream calc references.