# Build your own calculations

> Every calculation an Explorer can build in Holistics without code: aggregations, ratios, time comparisons, running totals, buckets, and more, with correct AQL underneath.

export const toc = [
  {
    "value": "Getting started",
    "id": "getting-started",
    "level": 2
  },
  {
    "value": "Before you build",
    "id": "before-you-build",
    "level": 2
  },
  {
    "value": "Core metrics",
    "id": "core-metrics",
    "level": 2
  },
  {
    "value": "Trends over time",
    "id": "trends-over-time",
    "level": 2
  },
  {
    "value": "Segment and compare",
    "id": "segment-and-compare",
    "level": 2
  }
];

{/* Built from the shared Hero / CardGrid / Card layout primitives: content lives
    inline here as markdown plus cards. Section headings are real markdown (##) so the
    right-rail "On this page" nav is generated automatically. Each card's `media` prop
    renders an inline thumbnail (video autoplays muted while on screen; images render
    as-is). `time` shows the estimated time investment; `steps` powers the collapsible
    "Quick steps" preview, so readers can skim the gist without opening the full guide.
    Cards deep-link into the Calculation Builder reference (/docs/calculation-builder)
    and, where relevant, into the AQL reference. */}

<Hero
  title="Build your own calculations"
  subtitle="A get-started guide for Explorers creating their own metrics, no code required. Build them with a few clicks, and each one generates correct AQL and handles Level of Detail for you, so the same definition holds up in every report." />

## Getting started {#getting-started}

This handbook focuses on practical calculation patterns: ratios, filtered metrics, time comparisons, buckets, and other metrics Explorers can build without code. Viewers can open shared dashboards and reports, but they cannot create these calculation fields.

There are two quick ways to open Calculation Builder. For the full orientation, including the catalog, AI-generated metrics, and generated AQL, see [Start building with Calculation Builder](/docs/calculation-builder/start-building).

<CardGrid cols={2}>
  <Card id="start-from-the-result-table" title="Start from the result table" badge="Explorers" time="1 min" steps={["Open a report in exploration mode.", "Click a metric or column in the result table.", "Choose the calculation you want to create."]} media={{type: 'image', src: 'https://media.holistics.io/b0778819-create-from-column.png'}} href="/docs/calculation-builder/start-building#start-building" cta="See where to click">
    Use this when you are already looking at a result and want to derive a new metric from the value in front of you.
  </Card>
  <Card id="start-from-the-dataset-tree" title="Start from the dataset tree" badge="Explorers" time="1 min" steps={["Expand a model in the dataset tree.", "Find the field you want to build from.", "Open its more-options menu and choose Create metric from this."]} media={{type: 'image', src: 'https://media.holistics.io/45da757b-create-from-tree.png'}} href="/docs/calculation-builder/start-building#start-building" cta="See where to click">
    Use this when you are building a report from scratch and already know which field should become a metric.
  </Card>
</CardGrid>

Once you know where the builder lives, it helps to understand a few controls that apply across many calculations.

## Before you build {#before-you-build}

Calculation Builder is not a separate formula system. It creates normal Holistics metrics that you can reuse, inspect, adjust, and compose with other calculations.

Most calculations start from a metric you already have. From an existing metric's menu:

- Choose **Create metric from this** when you want a new metric based on the current one. For example, build a filtered revenue metric first, then compare that filtered metric against the previous period.
- Use **Duplicate** when you want to keep the same shape but change one condition, like duplicating a completed-orders metric and changing the status to refunded.
- Rename the metric through **Label**, **Name**, and **Description** so it reads clearly in the report.

<CardGrid cols={2}>
  <Card id="create-and-edit-calculations-with-ai" title="Create and edit calculations with AI" badge="Explorers" time="3 min" steps={["Open the calculation menu and choose Generate metrics with AI.", "Describe the metric you want in plain language.", "Let AI build the metric for you.", "Review and adjust the result in the same Calculation Builder."]} media={{type: 'image', src: 'https://media.holistics.io/45da757b-create-from-tree.png'}} href="/docs/calculation-builder/start-building#create-with-ai" cta="View full guide">
    Describe a metric in plain language, then refine the result through the same GUI, not raw AQL.
  </Card>
  <Card id="see-the-aql-underneath" title="See the AQL underneath" badge="Explorers" time="3 min" steps={["Build a metric, such as a filtered revenue metric.", "Open the Definition popover on the metric.", "Read the exact AQL the GUI action generated.", "Use Formula mode when you need to write the expression directly."]} media={{type: 'image', src: 'https://media.holistics.io/5d68408a-definition-aql.png'}} href="/docs/calculation-builder/start-building#see-the-generated-aql" cta="View full guide">
    Every click writes correct AQL. You do not need to read it, but it is there when you want to verify or extend the metric.
  </Card>
  <Card id="control-level-of-detail" title="Control Level of Detail" badge="Explorers" time="5 min" steps={["Create a custom grouped metric from any metric, such as an order count.", "Set Grouping for aggregation: group only by a grain, or group by all dimensions except some.", "Use it for a total beside detail rows, or for an aggregate of an aggregate.", "The metric carries its grain into any report and adapts to context."]} media={{type: 'image', src: 'https://media.holistics.io/6e3f4b79-calculation-builder-common-metric-settings.png'}} href="/docs/calculation-builder#common-metric-settings" cta="View setting">
    Compute a metric at a different grain than the report: a higher-level total beside detail rows, or a nested aggregate like average orders per customer by age bracket.
  </Card>
</CardGrid>

With that foundation, use the examples below as a menu of common calculations to try.

## Core metrics {#core-metrics}

These are the everyday numbers: a metric scoped to the rows you care about, a ratio, and an aggregation over any field. They cover most of what an Explorer builds day to day.

<CardGrid cols={2}>
  <Card id="filter-a-metric-to-a-subset" title="Filter a metric to a subset" badge="Explorers" time="3 min" steps={["Start from any metric.", "Choose Create metric from this → Metric controls → Filtered metric.", "Set a condition on a dimension, for example an order status.", "The filter applies to this metric only, so your other metrics stay untouched."]} media={{type: 'video', src: 'https://media.holistics.io/c08a2d58-filter-metric.mp4'}} href="/docs/calculation-builder#filter" cta="View full guide">
    Scope one metric to a slice of rows, like an orders metric that counts only delivered orders.
  </Card>
  <Card id="build-a-ratio-like-average-order-value" title="Build a ratio like Average Order Value" badge="Explorers" time="3 min" steps={["Open a metric's menu and choose Arithmetic → Divide.", "Pick your numerator metric (say, revenue).", "Pick your denominator metric (say, order count).", "Format the result as currency."]} media={{type: 'video', src: 'https://media.holistics.io/f4723390-arithmetic-aov.mp4'}} href="/docs/calculation-builder#arithmetic" cta="View full guide">
    Define a ratio like average order value once as one metric divided by another, correct at every grain.
  </Card>
  <Card id="aggregate-any-field" title="Aggregate any field" badge="Explorers" time="2 min" steps={["Click a numeric field in the table or the dataset tree.", "Choose an aggregation such as sum, count, or average.", "Reach for median, percentiles, or standard deviation when you need them.", "Name the metric so it reads clearly."]} media={{type: 'image', src: 'https://media.holistics.io/83b4a095-basic-aggregations.png'}} href="/reference/aql/aggregator-functions" cta="See the functions">
    Roll a field up with sum, count, average, median, percentiles, or standard deviation.
  </Card>
</CardGrid>

## Trends over time {#trends-over-time}

Time-based calculations answer how a number is moving. Compare against a past period, accumulate as you go, or run a sliding window to smooth the trend or measure how much it's swinging.

<CardGrid cols={2}>
  <Card id="compare-to-a-previous-period" title="Compare to a previous period" badge="Explorers" time="4 min" steps={["Click the metric you want to compare.", "Choose Period over period.", "Point it at your date dimension.", "Pick the display value, the absolute change, or the percent change."]} media={{type: 'video', src: 'https://media.holistics.io/beb7a918-calc-period-over-period.mp4'}} href="/docs/calculation-builder#period-over-period" cta="View full guide">
    Put this quarter next to last, as a value, a change, or a percent, with no self-join.
  </Card>
  <Card id="accumulate-with-a-running-total" title="Accumulate with a running total" badge="Explorers" time="3 min" steps={["Click the metric.", "Choose Running total.", "Pick the date dimension to accumulate along.", "Read the cumulative value building up period by period."]} media={{type: 'video', src: 'https://media.holistics.io/67a6c976-calc-running-total.mp4'}} href="/docs/calculation-builder#running-total" cta="View full guide">
    Turn monthly revenue into cumulative revenue to date, accumulated along your date dimension.
  </Card>
  <Card id="smooth-a-trend-with-a-moving-average" title="Smooth a trend with a moving average" badge="Explorers" time="3 min" steps={["Click the metric on a time-based report.", "Choose Moving Calculation.", "Keep the function on Average.", "Shape the window with Previous and Next: trailing, centered, or leading."]} media={{type: 'video', src: 'https://media.holistics.io/01fe1425-calc-moving-average.mp4'}} href="/docs/calculation-builder#moving-calculations" cta="View full guide">
    Average a noisy week-to-week line into a readable trend. A trailing window is the classic moving average; a centered window smooths most cleanly.
  </Card>
  <Card id="measure-volatility-totals-and-extremes" title="Measure volatility, totals, and extremes" badge="Explorers" time="4 min" steps={["Click the metric on a time-based report.", "Choose Moving Calculation.", "Pick the function: standard deviation, sum, min, or max.", "Shape the window with Previous and Next."]} media={{type: 'video', src: 'https://media.holistics.io/1b4ce445-function-family.mp4'}} href="/docs/calculation-builder#pick-the-function" cta="View full guide">
    The same window can do more than smooth. A moving standard deviation gauges volatility, a trailing sum gives a rolling total like trailing 12 months, and a moving min or max tracks running highs and lows.
  </Card>
</CardGrid>

## Segment and compare {#segment-and-compare}

Sometimes the story is in how the parts stack up against each other. Show each slice as a share of the whole, or group a continuous field into tiers you can compare.

<CardGrid cols={2}>
  <Card id="show-each-part-as-a-percent-of-total" title="Show each part as a percent of total" badge="Explorers" time="3 min" steps={["Click the metric.", "Choose Percent of total.", "Pick the Total Value: row, column, or grand total in a pivot; grand or custom in a flat table.", "Format the result as a percent."]} media={{type: 'video', src: 'https://media.holistics.io/92077c93-percent-of-total-pivot.mp4'}} href="/docs/calculation-builder#percent-of-total" cta="View full guide">
    Read each part as a share of the whole, and choose which whole: the row, the column, or the grand total.
  </Card>
  <Card id="bucket-values-with-case-when" title="Bucket values with Case when" badge="Explorers" time="4 min" steps={["Open the calculation menu and choose Case when.", "Add a condition and the value it should return.", "Add more conditions for each tier, such as age or spend band.", "Set a default value for anything that does not match."]} media={{type: 'video', src: 'https://media.holistics.io/f832f677-calc-casewhen.mp4'}} href="/docs/calculation-builder#case-when" cta="View full guide">
    Turn a continuous field into tiers (the result is a dimension), like grouping customers by age or by spend band.
  </Card>
</CardGrid>