# Calculation builder handbook

> A guided overview of Calculation Builder: where to start, how to configure calculations, and which calculation type to choose.

export const toc = [
  { value: "Start building metrics", id: "start-building-metrics", level: 2 },
  { value: "Create a Metric from Scratch", id: "create-a-metric-from-scratch", level: 3 },
  { value: "Create a Metric from an Existing One", id: "create-a-metric-from-an-existing-one", level: 3 },
  { value: "Aggregate a Dimension into a Metric", id: "aggregate-a-dimension-into-a-metric", level: 3 },
  { value: "Duplicate a Metric", id: "duplicate-a-metric", level: 3 },
  { value: "Create a Metric with AI", id: "create-a-metric-with-ai", level: 3 },
  { value: "Configure the field", id: "configure-the-field", level: 2 },
  { value: "Choose the Calculation Inputs", id: "choose-the-calculation-inputs", level: 3 },
  { value: "Set Field Metadata", id: "set-field-metadata", level: 3 },
  { value: "Apply a Field-Level Filter", id: "apply-a-field-level-filter", level: 3 },
  { value: "Control the Grouping", id: "control-the-grouping", level: 3 },
  { value: "Format the Result", id: "format-the-result", level: 3 },
  { value: "Choose the right calculation", id: "choose-the-right-calculation", level: 2 },
  { value: "Basic Aggregations", id: "basic-aggregations", level: 3 },
  { value: "Listing", id: "listing", level: 3 },
  { value: "Arithmetic", id: "arithmetic", level: 3 },
  { value: "Window Calculations", id: "window-calculations", level: 3 },
  { value: "Logical Calculations", id: "logical-calculations", level: 3 },
  { value: "Comparative Calculations", id: "comparative-calculations", level: 3 },
  { value: "Text", id: "text", level: 3 },
  { value: "Go beyond the builder", id: "go-beyond-the-builder", level: 2 },
  { value: "Switch to Formula Mode", id: "switch-to-formula-mode", level: 3 },
  { value: "Browse the Full Calculation List", id: "browse-the-full-calculation-list", level: 3 },
  { value: "Learn AQL", id: "learn-aql", level: 3 },
];

<Hero
  title="Calculation builder handbook"
  subtitle="Create reusable metrics with a point-and-click builder, then refine them with filters, grouping, formatting, AI, or AQL when the logic needs more control." />

<CardViewToggle storageKey="calculation-builder-card-view" />

Calculation Builder helps you turn dimensions and existing metrics into new fields without writing formulas. It is useful when you need a quick count, a filtered metric, a percent of total, a period comparison, a moving average, or a small text or arithmetic transformation.

Each field can be edited in **GUI mode** with Calculation Builder or **Formula mode** with [AQL](/as-code/aql). Start with the builder when the calculation matches a common pattern, then switch to Formula mode when you need custom logic.

## Start building metrics {#start-building-metrics}

You can open Calculation Builder from the dataset panel, visualization settings, or the result table. Pick the entry point that matches the field you already have in front of you.

<CardGrid cols={2}>
  <Card id="create-a-metric-from-scratch" title="Create a Metric from Scratch" badge="Start here" time="3 min" steps={["Open the dataset panel, viz settings, or result table.", "Create a new metric.", "Choose a calculation type.", "Fill in the inputs, then save the metric."]} media={{type: 'video', src: 'https://media.holistics.io/calculation-builder-add-new-metric.mp4'}} href="/docs/calculation-builder/quick-start#create-metrics-from-scratch" cta="View quick start">
    Start with a blank metric when you already know the calculation you want to build.
  </Card>
  <Card id="create-a-metric-from-an-existing-one" title="Create a Metric from an Existing One" badge="Self-service users" time="2 min" steps={["Find the metric you want to reuse.", "Create a new metric from it.", "Choose the next calculation.", "Save the result with a clear label."]} media={{type: 'video', src: 'https://media.holistics.io/calculation-builder-create-metric-from-this.mp4'}} href="/docs/calculation-builder/quick-start#create-metrics-from-an-existing-one" cta="View quick start">
    Build on a trusted metric, such as turning `Total orders` into `% of total orders`.
  </Card>
  <Card id="aggregate-a-dimension-into-a-metric" title="Aggregate a Dimension into a Metric" badge="Common task" time="2 min" steps={["Select a dimension.", "Choose an aggregation such as count, sum, average, min, or max.", "Review the generated metric name.", "Save or adjust the configuration."]} media={{type: 'video', src: 'https://media.holistics.io/calculation-builder-aggregate-on-dimension.mp4'}} href="/docs/calculation-builder/quick-start#aggregate-dimensions-into-metrics" cta="View quick start">
    Summarize a dimension into a metric, like `P75 - Delivery attempts`.
  </Card>
  <Card id="duplicate-a-metric" title="Duplicate a Metric" badge="Fast variant" time="2 min" steps={["Duplicate an existing metric.", "Change the filter, grouping, format, or input.", "Rename it so the difference is obvious.", "Save the new metric."]} media={{type: 'video', src: 'https://media.holistics.io/calculation-builder-duplicate.mp4'}} href="/docs/calculation-builder/quick-start#duplicate-existing-metrics" cta="View quick start">
    Make a small variation, such as `Total orders (Australia)` from `Total orders`.
  </Card>
  <Card id="create-a-metric-with-ai" title="Create a Metric with AI" badge="Plain language" time="3 min" steps={["Describe the metric you want.", "Review how AI builds the calculation.", "Open it in Calculation Builder if you want to adjust it.", "Save when the logic is correct."]} media={{type: 'video', src: 'https://media.holistics.io/product/amql/calculation-builder-create-metrics-with-ai.mp4'}} href="/docs/calculation-builder/quick-start#create-metrics-with-ai" cta="View quick start">
    Ask for a metric in plain language. AI can reuse existing metrics or create the pieces it needs.
  </Card>
</CardGrid>

## Configure the field {#configure-the-field}

After choosing a calculation, review the field settings before saving. These settings control what the field computes, how it appears to other users, and how it behaves inside a report.

<CardGrid cols={2}>
  <Card id="choose-the-calculation-inputs" title="Choose the Calculation Inputs" badge="Required" time="2 min" steps={["Pick a calculation type.", "Fill in the required inputs.", "Use fields, text, numbers, or options depending on the calculation.", "Check the preview before saving."]} media={{type: 'image', src: 'https://media.holistics.io/config-field-parameters.png'}} href="/docs/calculation-builder#calculation-inputs" cta="View details">
    Inputs define the calculation logic. For example, a divide calculation needs a numerator field and a denominator field.
  </Card>
  <Card id="set-field-metadata" title="Set Field Metadata" badge="Good hygiene" time="2 min" steps={["Give the field a readable label.", "Use a clear name for formula references.", "Add a short description.", "Save the metadata with the field."]} media={{type: 'image', src: 'https://media.holistics.io/config-field-metadata.png'}} href="/docs/calculation-builder#field-metadata" cta="View details">
    Make the metric understandable in reports and easy to reference in formulas later.
  </Card>
  <Card id="apply-a-field-level-filter" title="Apply a Field-Level Filter" badge="Focused logic" time="2 min" steps={["Open the field filter settings.", "Add the condition that should apply only to this field.", "Review the filtered result.", "Save the field."]} media={{type: 'image', src: 'https://media.holistics.io/config-field-filter.png'}} href="/docs/calculation-builder#filter" cta="View details">
    Build metrics like `Delivered orders` without changing the other fields on the same visualization.
  </Card>
  <Card id="control-the-grouping" title="Control the Grouping" badge="Advanced" time="3 min" steps={["Open the group-by settings.", "Choose whether to exclude dimensions or group only by selected dimensions.", "Check whether the metric should follow the report context.", "Save after the level of detail looks right."]} media={{type: 'image', src: 'https://media.holistics.io/config-field-group-only-by.png'}} href="/docs/calculation-builder#group-by" cta="View details">
    Set the level of detail for a metric, such as grouping only by country even when the report has more dimensions.
  </Card>
  <Card id="format-the-result" title="Format the Result" badge="Presentation" time="1 min" steps={["Open the format settings.", "Choose a number, currency, percent, or other display format.", "Set decimals where needed.", "Save the field."]} media={{type: 'image', src: 'https://media.holistics.io/config-field-format.png'}} href="/docs/calculation-builder#format" cta="View details">
    Turn raw values into readable outputs, such as showing `0.2434` as `24.34%`.
  </Card>
</CardGrid>

## Choose the right calculation {#choose-the-right-calculation}

Calculation Builder groups common metric patterns into categories. Start with the category that matches the business question, then choose the exact calculation inside it.

<CardGrid cols={2}>
  <Card id="basic-aggregations" title="Basic Aggregations" badge="Counts and totals" time="3 min" steps={["Choose a dimension or table.", "Pick count, count distinct, sum, average, min, max, median, percentile, variance, or standard deviation.", "Set any required percentile or aggregation options.", "Save the metric."]} media={{type: 'image', src: 'https://media.holistics.io/calculation-builder-sum.png'}} href="/docs/calculation-builder/available-calculations/basic-aggregations" cta="View calculations">
    Summarize rows into metrics like total revenue, unique customers, median order value, or P95 response time.
  </Card>
  <Card id="listing" title="Listing" badge="Related values" time="2 min" steps={["Choose List.", "Pick the table to list from.", "Choose display fields.", "Use the result beside an aggregation."]} media={{type: 'image', src: 'https://media.holistics.io/calculation-builder-list.png'}} href="/docs/calculation-builder/available-calculations/listing" cta="View calculation">
    Show related values next to an aggregation, such as products on each order or tags on a support ticket.
  </Card>
  <Card id="arithmetic" title="Arithmetic" badge="Field math" time="2 min" steps={["Choose Add, Subtract, Multiply, or Divide.", "Select the two input fields.", "Name the result.", "Format the output if needed."]} media={{type: 'image', src: 'https://media.holistics.io/calculation-builder-divide.png'}} href="/docs/calculation-builder/available-calculations/arithmetic" cta="View calculations">
    Combine fields into calculations like profit, conversion rate, tax amount, or line total.
  </Card>
  <Card id="window-calculations" title="Window Calculations" badge="Across rows" time="4 min" steps={["Choose rank, running total, or moving calculation.", "Select the metric or dimension to calculate over.", "Choose the ordering or window settings.", "Review the result in the visualization."]} media={{type: 'image', src: 'https://media.holistics.io/calculation-builder-moving-average.png'}} href="/docs/calculation-builder/available-calculations/window-calculations" cta="View calculations">
    Rank items, accumulate a running total, or smooth a trend with moving averages and rolling sums.
  </Card>
  <Card id="logical-calculations" title="Logical Calculations" badge="Conditions" time="3 min" steps={["Choose a conditional aggregation or Case when.", "Set the base field or cases.", "Add the condition logic.", "Save with a descriptive label."]} media={{type: 'image', src: 'https://media.holistics.io/calculation-builder-case-when.png'}} href="/docs/calculation-builder/available-calculations/logical-calculations" cta="View calculations">
    Count, sum, average, min, or max only matching records, or use Case when to bucket values into labels.
  </Card>
  <Card id="comparative-calculations" title="Comparative Calculations" badge="Context" time="4 min" steps={["Choose percent of total or period over period.", "Select the metric to compare.", "Choose the total scope or comparison period.", "Pick the display option and save."]} media={{type: 'image', src: 'https://media.holistics.io/calculation-builder-period-over-period-value.png'}} href="/docs/calculation-builder/available-calculations/comparative-calculations" cta="View calculations">
    Show share of a total or compare a metric against a previous period, such as this month vs last month.
  </Card>
  <Card id="text" title="Text" badge="Labels" time="2 min" steps={["Choose Concat.", "Add field values, plain text, or separators.", "Preview the combined text.", "Save the result."]} media={{type: 'image', src: 'https://media.holistics.io/calculation-builder-concat.png'}} href="/docs/calculation-builder/available-calculations/text" cta="View calculation">
    Combine text fields and fixed strings, such as full name or a city-and-country label.
  </Card>
</CardGrid>

## Go beyond the builder {#go-beyond-the-builder}

Calculation Builder covers common metric patterns. When you need logic that does not fit the menu, use Formula mode and write the field directly in AQL.

<CardGrid cols={3}>
  <Card id="switch-to-formula-mode" title="Switch to Formula Mode" badge="Custom logic" time="4 min" steps={["Open the field.", "Switch from GUI mode to Formula mode.", "Write or edit the AQL expression.", "Run the report and check the result."]} href="/as-code/aql" cta="Learn AQL">
    Use the AQL editor when the calculation needs custom logic beyond the visual builder.
  </Card>
  <Card id="browse-the-full-calculation-list" title="Browse the Full Calculation List" badge="Reference" time="2 min" steps={["Open the available calculations page.", "Search or filter the calculation table.", "Open the calculation category.", "Review inputs and examples."]} href="/docs/calculation-builder/available-calculations" cta="Open reference">
    Search the full Calculation Builder catalog, including inputs, examples, preview images, and category links.
  </Card>
  <Card id="learn-aql" title="Learn AQL" badge="Power users" time="30 min" steps={["Read the 30-minute AQL guide.", "Use the function cheatsheet for syntax.", "Borrow examples from the cookbook.", "Return to Formula mode to apply the pattern."]} href="/as-code/aql/learn-in-30-minutes" cta="Start learning">
    Learn the language that powers Calculation Builder when you want more control over metric logic.
  </Card>
</CardGrid>