Summary

This page is for the rare case where the Analytics Catalog doesn't already have the metric you need — for example, a count with a very specific filter, or arithmetic over two facts that no one has wired up yet. You'll write the missing metric in MAQL, the formula language Alvys Reports uses for measures.

💡 Check the Catalog first. Your tenant's Analytics Catalog is rich — hundreds of pre-built metrics covering trips, revenue, cost, on-time performance, miles, drivers, and more. Before writing a custom metric, search the Catalog: there's a good chance the metric you need is already there. See Build visualizations with drag-and-drop for the drag-and-drop walkthrough.

Recap: a metric is a formula that turns raw numbers from your data into a calculated value — for example, "total revenue this month" or "on-time delivery rate." Metrics live in the Analytics Catalog and can be reused on any visualization.

MAQL is the formula language for measures. It looks a little like SQL but stays inside the Visualization Designer.

Quickstart — write your first custom metric

Open the metric editor

In the Metrics bucket on the Configuration panel, click + and pick New metric. The formula bar opens above the canvas.

📷 Screenshot — Visualization Designer — formula bar open above the canvas, ready for a MAQL expression.

Write a simple sum

Every MAQL metric starts with SELECT. The simplest one references an existing metric directly:

SELECT {metric/trip_count_all}

This returns the total trip count, sliced by whatever attributes are on the visualization.

To pick a reference, type { and the editor offers autocomplete from your tenant's catalog (metrics, facts, attributes, and labels). Pick the item you want and the editor inserts the full reference.

Filter inside the metric

To restrict the metric to a subset, use WHERE:

SELECT {metric/trip_count_all}
WHERE {label/load_origin_state.load_origin_state} = "US-TX"

This returns the trip count where the load originates from Texas. Use IN ("US-TX","US-CA","US-FL") to match multiple states at once.

Compare to a previous period

To compare this period to the previous one, combine FOR Previous(...) with a date label:

SELECT {metric/trip_count_all}
FOR Previous({label/load_created_at.year})
WHERE {label/load_origin_state.load_origin_state} = "US-TX"

This returns the trip count from the previous year, filtered to Texas-origin loads. The visualization's current time axis (year, quarter, or month) determines what "previous" actually means.

Save the metric

Click Save in the formula bar. Give the metric a clear name like Revenue — Texas only. It's now in your tenant's Analytics Catalog and reusable across visualizations.

⚠️ Custom metrics are tenant-visible. Just like saved visualizations, custom metrics are shared with everyone who has access to the Visualization Designer on your tenant. Name them clearly.

A few more example formulas

Once you're comfortable with the basics, MAQL can get expressive. Here are real-shape examples from Alvys-curated dashboards.

Count of all trip IDs:

SELECT COUNT({label/TRIPS.TRIP_ID})

Trips per driver — a ratio of two existing metrics:

SELECT
  {metric/operational_trip_count_excluding_cancelled_tonu}
  / {metric/operational_trip_driver_count}

Average delivery delay — only count trips that were actually late:

SELECT AVG(
  CASE
    WHEN {metric/trip_late_minutes} > 0
    THEN {metric/trip_late_minutes}
  END
)

Active driver count — filter on a boolean label:

SELECT COUNT({label/driver_id})
WHERE {label/ACTIVE_ASSET} = "true"

These are good shapes to model from — copy one, swap the metric or label references for the question you're asking, and save the result.

Tips

Name custom metrics for the audience. "Revenue YoY %" reads better than "rev_yoy_pct".
Test the same metric in multiple slicings before saving — MAQL is context-aware, and the number can change depending on which attributes are on the visualization.

Function reference

The rest of this page is the full catalog of MAQL functions you can use inside the formula bar.

💡 The examples below use illustrative names like {fact/revenue} and {attribute/year} to show MAQL syntax. Your tenant's actual catalog uses real names — the editor's autocomplete ({ triggers it) shows you what's available.

Basic syntax

Every MAQL metric starts with SELECT. Clause order is alphabetical: BY, WHERE, WITHOUT.

SELECT <expression> [BY <attribute>] [WHERE <filter>]

References are wrapped in { ... }:

{fact/<id>} — a raw numeric column from your dataset.
{metric/<id>} — an existing saved metric.
{attribute/<id>} — a categorical attribute.
{label/<id>} — a textual label of an attribute (used in filter values).

Arithmetic: + - * /. Strings use double quotes. Comments start with #.

Aggregation

Function	Signature	What it does
`SUM`	`SUM(fact)`	Sum of all values
`AVG`	`AVG(fact)`	Arithmetic mean
`MIN`	`MIN(fact)`	Smallest value
`MAX`	`MAX(fact)`	Largest value
`COUNT`	`COUNT(attribute)`	Count of distinct attribute values
`MEDIAN`	`MEDIAN(fact)`	Median
`APPROXIMATE_COUNT`	`APPROXIMATE_COUNT(attribute)`	Fast approximate distinct count for large datasets

SELECT SUM({fact/revenue})
SELECT COUNT({attribute/load_id})

Math

Function	What it does
`ABS(x)`	Absolute value
`ROUND(x, n)`	Round to `n` decimals
`CEILING(x)`	Round up to next integer
`FLOOR(x)`	Round down to next integer
`POWER(x, y)`	`x` raised to `y`
`SQRT(x)`	Square root
`LN(x)`	Natural log
`LOG(x)`	Base-10 log
`EXP(x)`	e^x
`GREATEST(a, b, ...)`	Largest of the arguments
`LEAST(a, b, ...)`	Smallest of the arguments
`SIGN(x)`	-1, 0, or 1
`TRUNC(x)`	Truncate toward zero

Conditional logic

IF / THEN / ELSE

SELECT IF <condition> THEN <expr_if_true> ELSE <expr_if_false> END

CASE

SELECT CASE
         WHEN <condition_1> THEN <expr_1>
         WHEN <condition_2> THEN <expr_2>
         ELSE <expr_else>
       END

If no ELSE is given and nothing matches, the result is null.

⚠️ Multidimensionality rule. Wrap CASE / IF inside SUM(...) when the WHEN condition references an attribute that isn't on the visualization. Otherwise the formula fails.

Filtering — WHERE / HAVING / LIKE / Ranking

WHERE — filter on attribute label values:

SELECT {metric/revenue} WHERE {label/state} IN ("TX", "CA")
SELECT {metric/revenue} WHERE {label/year} = "2026" AND {label/month} = "5"
SELECT {metric/revenue} WHERE NOT ({label/state} = "TX")

LIKE — pattern match on labels:

SELECT {metric/revenue} WHERE {label/customer_name} LIKE "Acme%"

% matches any sequence; _ matches a single character.

HAVING — filter on aggregated metric results:

SELECT SUM({fact/revenue}) HAVING SUM({fact/revenue}) > 10000

Ranking — keep only top / bottom N:

SELECT SUM({fact/revenue}) WHERE TOP(5) IN (SELECT SUM({fact/revenue}) BY {attribute/customer})

Logical operators

AND, OR, NOT
IN ( ... ) for list membership
NOT IN ( ... ) for negated list membership
Comparison: =, !=, <, <=, >, >=

Time-series — FOR Previous / FOR Next

Shift a metric to a past or future period. The shift adapts to the time attribute on the visualization.

SELECT {metric/revenue} FOR Previous({attribute/year})
SELECT {metric/revenue} FOR Previous({attribute/quarter}, 3)
SELECT {metric/revenue} FOR Next({attribute/month})
SELECT {metric/revenue} FOR Each({attribute/customer})

Companion functions: FOR PreviousPeriod, FOR NextPeriod, FOR Each.

Time macros (anchored to current real-world date)

SELECT {metric/revenue} WHERE {attribute/date} = THIS(DAY)
SELECT {metric/revenue} WHERE {attribute/month} = PREVIOUS(MONTH)
SELECT {metric/revenue} WHERE {attribute/month} = THIS(MONTH, -2)
SELECT {metric/revenue} WHERE {attribute/year} = NEXT(YEAR)

Granularities: DAY, WEEK, MONTH, QUARTER, YEAR, WEEKOFYEAR, MONTHOFYEAR, QUARTEROFYEAR, DAYOFMONTH, DAYOFWEEK, DAYOFYEAR.

Shortcuts:

PREVIOUS(g) ≡ THIS(g, -1)
NEXT(g) ≡ THIS(g, 1)

Running totals

Function	What it does
`RUNSUM(x)`	Cumulative sum
`RUNAVG(x)`	Cumulative average
`RUNMIN(x)` / `RUNMAX(x)`	Cumulative min / max
`RUNVAR(x)`	Cumulative variance
`RUNSTDEV(x)`	Cumulative standard deviation

Use WITHIN (<attribute>) to reset the cumulative at each new value of an attribute:

SELECT RUNSUM(SUM({fact/revenue})) WITHIN ({attribute/quarter})

Ranking

Function	What it does
`RANK(metric)`	Rank within the current context (1 = highest)
`TOP(n)` / `BOTTOM(n)`	Used inside WHERE to keep top / bottom N rows

BY clauses — overriding context

Form	What it does
`BY <attr>`	Compute grouped only by the named attribute
`BY ALL <attr>`	Compute ignoring the named attribute
`BY ALL OTHER`	Compute ignoring all attributes on the visualization
`BY <attr> ALL OTHER`	Compute grouped only by `<attr>`, ignoring everything else

# Share of total:
SELECT SUM({fact/revenue}) / (SELECT SUM({fact/revenue}) BY ALL OTHER)# Customer-level total even when sliced by year:
SELECT SUM({fact/revenue}) BY {attribute/customer} ALL OTHER

Statistical functions

Function	What it does
`STDEV(fact)`	Standard deviation
`VAR(fact)`	Variance
`PERCENTILE(fact, p)`	p-th percentile
`CORREL(fact_a, fact_b)`	Correlation coefficient
`MOVING_AVG(metric, n)`	Moving average over last `n` periods

NULL handling

Arithmetic on a NULL yields NULL. Use IF / CASE to substitute zero:

SELECT IF SUM({fact/x}) IS NULL THEN 0 ELSE SUM({fact/x}) END

For division safety:

SELECT IF SUM({fact/denominator}) = 0 OR SUM({fact/denominator}) IS NULL
       THEN 0
       ELSE SUM({fact/numerator}) / SUM({fact/denominator})
       END

Number formatting

The number format lives on the metric, not in MAQL itself. Open the Format dropdown in the metric editor.

Format string placeholders

0 — required digit (pads with zero).
# — optional digit (no padding).
. — decimal point.
, — thousands separator.
% — multiply value by 100 and append %.
\ — escape a literal symbol.

Truncation suffixes

#,K — thousands, suffix "K"
#,,M — millions, suffix "M"
#,,,B — billions, suffix "B"

Colors and conditional formatting

[Blue]#,#.##
[color=99AE00]#,#.##
[backgroundcolor=00FF00]#,#.##

Conditional rules:

[<400000][red]$#,#.##;
[<500000][magenta]$#,#.##;
[<600000][yellow]$#,#.##;
[>=600000][green]$#,#.##

Rules apply left-to-right; first match wins.

Auto-rounding by magnitude

[>=1000000000]#,,,.0 B;
[>=1000000]#,,.0 M;
[>=1000]#,.0 K;
#,##0

Advanced — write custom metrics with MAQL