afv-library/skills/tableau-next-semantic-model-generate/references/best-practices.md

Best Practices

Long-form rationale + examples for each principle summarized in SKILL.md.

Prefer CLC Fields Over Raw Fields

When creating fields, prefer calculated fields (_clc) even for simple formulas. This centralizes business logic and makes it reusable.

Example:

# Instead of using raw [Table].[Amount] everywhere, create:
python scripts/create_calc_field.py \
  --sdm Sales_Cloud12_backward \
  --type measurement \
  --name Total_Revenue_clc \
  --label "Total Revenue" \
  --expression "SUM([Opportunity_TAB_Sales_Cloud].[Amount])" \
  --aggregation Sum

Use Meaningful Names

API names should communicate business meaning, not generic identifiers.

Good:

• Win_Rate_clc
• Total_Revenue_mtc
• Deal_Size_Category_clc

Bad:

• Field_1_clc
• Metric_2_mtc
• Calc_Field_clc

Two-Step Workflow for Metrics

Create the calculated field first, then the metric. Metrics reference calc fields by API name in measurementReference.calculatedFieldApiName, so attempting to create a metric before its calc field exists will fail with a "Field not found" error.

Test Fields Before Creating Metrics

After creating a calc field, verify it works in a visualization before creating a metric. This catches expression errors early.

Verification steps after field/metric creation:

1. Confirm existence: Run discover_sdm.py --sdm {{NAME}} --json and search for your API name in the response
2. Check API response: POST response includes apiName and success: true on successful creation
3. Test in visualization: Create a simple chart using the calc field, or reference the metric in a dashboard widget
4. Validate calculations: Compare output values against manual calculations to verify expression logic

Read Aggregation Types from SDM

Don't assume aggregation types — inspect the SDM to see how similar fields are configured. Use discover_sdm.py --sdm {{NAME}} --json and look at aggregationType for existing measurements.