Visual calculations

Visual calculations are governed post-aggregation analysis attached to one visual. They operate only on fields already present in that visual’s compiled result frame. They do not query the semantic model, traverse model relationships, or accept arbitrary formulas.

Choose the right calculation layer

Use a semantic measure when the business definition should be reused across visuals, dashboards, APIs, exports, or agents. Revenue, gross margin, active customers, and other governed business concepts belong in the semantic model.

Use a visual calculation when the input is already aggregated and the analysis depends on the displayed structure or ordering. Running totals, moving averages, period differences, percent of parent, percent of grand total, rank, cumulative contribution, and a lookup within the visible frame are good examples.

A visual calculation is stored with one visual. Its result changes with the visual’s governed filters and compiled frame, but it cannot change the meaning of the source measure.

Author a closed template

visuals:
  monthly_revenue:
    type: line
    title: Revenue and running total
    calculations:
      - id: running_revenue
        label: Running revenue
        template: running_total
        source: value
        axis: rows
        order_by:
          - field: label
            direction: asc
        format: currency
    query:
      dimensions:
        month: orders.purchase_month
      measures:
        revenue: null
      sort:
        - field: month
          direction: asc
      limit: 30

source, order_by, partition_by, parent, and lookup.field address compiled result-frame aliases. They never contain SQL, DAX, JavaScript, or semantic expressions. For built-in categorical charts, the common aliases are label, series, and value. Tables and point visuals retain their explicit query aliases.

The supported templates are:

• running_total
• moving_average
• difference
• percentage_difference
• percent_of_parent
• percent_of_grand_total
• rank
• cumulative_contribution
• lookup

Order-sensitive templates require an explicit order_by. moving_average also requires a positive window. percent_of_parent requires parent or partition_by, and lookup requires one unambiguous field/value match within each partition.

Ordering is stable: authored sort fields are applied in sequence, equal values retain result-frame order, and null order values sort last in either direction. Null source values produce null at that row and do not poison later running totals, moving averages, shares, or cumulative contributions.

Axes, partitions, and reset

axis is one of rows, columns, hierarchy, or facets. Use partition_by to keep independent series, facets, matrix rows, or hierarchy branches from affecting one another.

reset: highest_parent uses the first declared hierarchy partition. reset: lowest_parent uses all declared hierarchy partitions. reset: none keeps the explicit partition unchanged.

Fields used only to order, partition, or look up a result can set hidden: true. Hidden fields remain in the governed frame and provenance metadata but are not rendered as a chart series or table column.

Completeness and provenance

Every compiled field identifies whether it is modeled, aggregated, or visually calculated. Visual-calculation fields retain their calculation ID and source aliases, so tooltips, exports, accessibility projections, and agent results can distinguish them from semantic measures.

Inline calculations run over the complete bounded result frame. Calculated tables evaluate one deterministic, bounded visible frame before virtualized windows are sliced, so scrolling does not restart a running total. If a query reaches its row cap or otherwise returns an incomplete frame, LeapView marks the visual partial and emits a visual_calculation_incomplete_frame diagnostic. It never presents a rank, total, or percentage over a truncated frame as complete.