Skip to content

Commit 3760b96

Browse files
joaovianaclaude
joaoviana
and
claude
authored
docs: add Formula table calculations (Beta) guide (#558)
* docs: add Formula table calculations (Beta) guide Announces the beta launch of formula-based table calculations and documents the supported warehouses, formula syntax, function catalog, worked examples, and FAQs. Updates the table-calculations overview with a beta callout pointing at the new guide. Wires the new page into docs.json navigation. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(formula): add screenshots with light and dark variants - "Creating a formula table calculation" — placed under the intro - "Formula in the results table" — placed under the first-formula section Both rendered with Mintlify's className="block dark:hidden" / className="hidden dark:block" pattern so the correct variant shows per theme. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(nav): nest table-calc pages under a Table calculations group Removes the IA weirdness where "Table calculations" (overview) and "Formula table calculations" (Beta guide) were peer entries. Now they live inside a single "Table calculations" group, alongside the existing "Table calculation functions" and "SQL templates" sub-groups (latter renamed from "Table calc SQL templates" — cleaner given the parent group already names the topic). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(nav): shorten table-calc sidebar labels The "Table calculations" group had every child repeating "Table calculations" in its label, which made the sidebar read as a stutter. Use sidebarTitle frontmatter and inner-group rename to trim labels while keeping the full page titles (and URLs) intact: - guides/table-calculations → "Overview" - guides/formula-table-calculations → "Formula (Beta)" - Inner group "Table calculation functions" → "Functions" In-page headings and SEO titles are unchanged; URLs are unchanged. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(formula): tighten prose, drop em dashes Replaces em dashes introduced in the initial draft with periods, commas, colons, and parentheses as appropriate. The em-dash-heavy voice felt AI-written; the result reads more naturally. Also: - Changes bullet-list separators from "Label — value" to "Label: value". - Replaces "Google Sheets–style" with "spreadsheet-style" where the Google-Sheets comparison was already made elsewhere in the paragraph. - Applies the same treatment to the two-bullet intro and the Beta callout in the table-calculations overview. Pre-existing em dashes elsewhere in table-calculations.mdx are intentionally left untouched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(formula): trim the FAQ to three entries Drops three FAQs that were filler: - "Does the formula run on my warehouse?" (answer was obvious) - "Can I mix aggregates and scalar expressions?" (niche; the function reference already implies yes) - "How do I reference a field with unusual characters?" (edge case already covered by the "use SQL" escape-hatch in the intro) Also simplifies the "I found a bug" FAQ to the standard Slack + GitHub pattern used in contact/contact-info.mdx, rather than a bespoke copy. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent d0edf1b commit 3760b96

7 files changed

Lines changed: 262 additions & 19 deletions

‎docs.json‎

Lines changed: 24 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -96,26 +96,32 @@
9696
"guides/how-to-promote-content",
9797
"guides/verified-content",
9898
"guides/keyboard-shortcuts",
99-
"guides/table-calculations",
10099
{
101-
"group": "Table calculation functions",
100+
"group": "Table calculations",
102101
"pages": [
103-
"references/table-calculation-functions/row-functions",
104-
"references/table-calculation-functions/pivot-functions",
105-
"references/table-calculation-functions/aggregate-functions"
106-
]
107-
},
108-
{
109-
"group": "Table calc SQL templates",
110-
"pages": [
111-
"guides/table-calculations/sql-templates",
112-
"guides/table-calculations/table-calculation-sql-templates/percent-change-from-previous",
113-
"guides/table-calculations/table-calculation-sql-templates/percent-of-previous-value",
114-
"guides/table-calculations/table-calculation-sql-templates/percent-of-total-column",
115-
"guides/table-calculations/table-calculation-sql-templates/percent-of-group-pivot-total",
116-
"guides/table-calculations/table-calculation-sql-templates/rank-in-column",
117-
"guides/table-calculations/table-calculation-sql-templates/running-total",
118-
"guides/table-calculations/table-calculation-sql-templates/rolling-window"
102+
"guides/table-calculations",
103+
"guides/formula-table-calculations",
104+
{
105+
"group": "Functions",
106+
"pages": [
107+
"references/table-calculation-functions/row-functions",
108+
"references/table-calculation-functions/pivot-functions",
109+
"references/table-calculation-functions/aggregate-functions"
110+
]
111+
},
112+
{
113+
"group": "SQL templates",
114+
"pages": [
115+
"guides/table-calculations/sql-templates",
116+
"guides/table-calculations/table-calculation-sql-templates/percent-change-from-previous",
117+
"guides/table-calculations/table-calculation-sql-templates/percent-of-previous-value",
118+
"guides/table-calculations/table-calculation-sql-templates/percent-of-total-column",
119+
"guides/table-calculations/table-calculation-sql-templates/percent-of-group-pivot-total",
120+
"guides/table-calculations/table-calculation-sql-templates/rank-in-column",
121+
"guides/table-calculations/table-calculation-sql-templates/running-total",
122+
"guides/table-calculations/table-calculation-sql-templates/rolling-window"
123+
]
124+
}
119125
]
120126
}
121127
]

‎guides/formula-table-calculations.mdx‎

Lines changed: 227 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,227 @@
1+
---
2+
title: "Formula table calculations"
3+
description: "Build table calculations using a spreadsheet-style formula syntax instead of raw SQL."
4+
sidebarTitle: "Formula (Beta)"
5+
---
6+
7+
<Info>
8+
**Formula table calculations are in Beta (Early Access).**
9+
10+
The feature is enabled by default on supported warehouses, with no
11+
flag required, and we're actively expanding the function catalog.
12+
We'd love your feedback while we iterate. See [feature maturity levels](/references/workspace/feature-maturity-levels)
13+
for details.
14+
</Info>
15+
16+
Formula table calculations let you write table calculations in a
17+
spreadsheet-style syntax, the way you would in Google Sheets or Excel,
18+
instead of raw SQL. When you create a new [table calculation](/guides/table-calculations)
19+
on a supported warehouse, **Formula** is the default input mode. You
20+
can switch to the SQL editor any time.
21+
22+
<Frame>
23+
<img src="/images/guides/formula-table-calculations/create-table-calculation-formula-light.png" alt="Creating a formula table calculation" className="block dark:hidden" />
24+
<img src="/images/guides/formula-table-calculations/create-table-calculation-formula-dark.png" alt="Creating a formula table calculation" className="hidden dark:block" />
25+
</Frame>
26+
27+
## Why use formulas?
28+
29+
- **Faster to write** for common calculations. No `OVER (…)` or
30+
`CASE WHEN` boilerplate to remember.
31+
- **Familiar** if you've used Google Sheets, Excel, or Airtable.
32+
- **Portable** across warehouses. The same formula compiles to the
33+
correct SQL for whichever warehouse your project is connected to.
34+
35+
If you need something the formula syntax doesn't cover yet, the SQL
36+
editor is always one click away.
37+
38+
## Supported warehouses
39+
40+
| Warehouse | Formula support |
41+
| ----------- | --------------- |
42+
| BigQuery | ✅ |
43+
| ClickHouse | ✅ |
44+
| Databricks | ✅ |
45+
| DuckDB | ✅ |
46+
| PostgreSQL | ✅ |
47+
| Redshift | ✅ |
48+
| Snowflake | ✅ |
49+
| Athena | 🚧 Not yet |
50+
| Trino | 🚧 Not yet |
51+
52+
On warehouses where formulas aren't supported yet, the Formula toggle
53+
is hidden and the SQL editor works exactly as it always has.
54+
55+
## Writing your first formula
56+
57+
Every formula starts with `=`. Reference a field by its column name
58+
(the same name you see in the results table header):
59+
60+
```
61+
=orders_total_order_amount * 1.2
62+
```
63+
64+
The result appears as a new green column in your results table:
65+
66+
<Frame>
67+
<img src="/images/guides/formula-table-calculations/table-calculation-formula-in-table-light.png" alt="Formula table calculation in the results table" className="block dark:hidden" />
68+
<img src="/images/guides/formula-table-calculations/table-calculation-formula-in-table-dark.png" alt="Formula table calculation in the results table" className="hidden dark:block" />
69+
</Frame>
70+
71+
You can use:
72+
73+
- **Numbers**: `42`, `3.14`, `-1.5`
74+
- **Strings**: `"hello"` or `'hello'`
75+
- **Booleans**: `TRUE`, `FALSE`
76+
- **Column references**: any field present in your results table
77+
- **Arithmetic operators**: `+`, `-`, `*`, `/`, `%` (modulo)
78+
- **Comparison operators**: `=`, `<>`, `>`, `<`, `>=`, `<=`
79+
- **Boolean operators**: `AND`, `OR`, `NOT`
80+
81+
## Function reference
82+
83+
### Math
84+
85+
| Function | Description |
86+
| --------------------------- | ------------------------------- |
87+
| `ABS(x)` | Absolute value |
88+
| `ROUND(x, [digits])` | Round to N decimal places |
89+
| `CEIL(x)` / `CEILING(x)` | Round up to nearest integer |
90+
| `FLOOR(x)` | Round down to nearest integer |
91+
| `MIN(x, [y])` | Minimum (scalar or aggregate) |
92+
| `MAX(x, [y])` | Maximum (scalar or aggregate) |
93+
94+
### Logical
95+
96+
| Function | Description |
97+
| ------------------------------- | ---------------------- |
98+
| `IF(condition, then, [else])` | Conditional expression |
99+
| `AND`, `OR`, `NOT` | Boolean operators |
100+
| `=`, `<>`, `>`, `<`, `>=`, `<=` | Comparison operators |
101+
102+
### String
103+
104+
| Function | Description |
105+
| ------------------------ | ----------------------- |
106+
| `CONCAT(a, b, …)` | Concatenate strings |
107+
| `LEN(s)` / `LENGTH(s)` | String length |
108+
| `TRIM(s)` | Remove whitespace |
109+
| `LOWER(s)` | Convert to lowercase |
110+
| `UPPER(s)` | Convert to uppercase |
111+
112+
### Date
113+
114+
| Function | Description |
115+
| ------------ | --------------------- |
116+
| `TODAY()` | Current date |
117+
| `NOW()` | Current timestamp |
118+
| `YEAR(d)` | Extract year |
119+
| `MONTH(d)` | Extract month |
120+
| `DAY(d)` | Extract day |
121+
122+
### Aggregation
123+
124+
| Function | Description |
125+
| -------------------------- | --------------------------- |
126+
| `SUM(x)` | Sum values |
127+
| `AVG(x)` / `AVERAGE(x)` | Average values |
128+
| `COUNT([x])` | Count rows (or non-null x) |
129+
| `SUMIF(condition, x)` | Sum where condition is true |
130+
| `AVERAGEIF(condition, x)` | Avg where condition is true |
131+
| `COUNTIF(condition)` | Count where condition true |
132+
133+
### Window
134+
135+
| Function | Description |
136+
| -------------------------------- | --------------------------------- |
137+
| `RUNNING_TOTAL(x)` | Running (cumulative) total |
138+
| `ROW_NUMBER()` | Sequential row number |
139+
| `RANK()` | Rank with gaps |
140+
| `DENSE_RANK()` | Rank without gaps |
141+
| `LAG(x, [offset], [default])` | Previous row's value |
142+
| `LEAD(x, [offset], [default])` | Next row's value |
143+
| `FIRST(x)` | First value in window |
144+
| `LAST(x)` | Last value in window |
145+
| `NTILE(n)` | Distribute rows into N buckets |
146+
| `MOVING_SUM(x, n)` | Sum of the last N rows |
147+
| `MOVING_AVG(x, n)` | Average of the last N rows |
148+
149+
### Null handling
150+
151+
| Function | Description |
152+
| ---------------------- | -------------------------------- |
153+
| `COALESCE(a, b, …)` | First non-null argument |
154+
| `ISNULL(x)` | `TRUE` if x is null |
155+
156+
## Examples
157+
158+
**Gross margin as a percentage**
159+
160+
```
161+
=ROUND((orders_revenue - orders_cost) / orders_revenue * 100, 2)
162+
```
163+
164+
**Flag high-value orders**
165+
166+
```
167+
=IF(orders_total_amount > 1000, "VIP", "Standard")
168+
```
169+
170+
**Running total of revenue**
171+
172+
```
173+
=RUNNING_TOTAL(orders_revenue)
174+
```
175+
176+
**Period-over-period growth %**
177+
178+
```
179+
=(orders_revenue - LAG(orders_revenue, 1, 0)) / LAG(orders_revenue, 1, 0) * 100
180+
```
181+
182+
**Bucket customers by spend**
183+
184+
```
185+
=IF(customers_lifetime_value > 10000, "Platinum",
186+
IF(customers_lifetime_value > 5000, "Gold",
187+
IF(customers_lifetime_value > 1000, "Silver", "Bronze")))
188+
```
189+
190+
**Percent of total**
191+
192+
```
193+
=orders_revenue / SUM(orders_revenue) * 100
194+
```
195+
196+
## FAQ
197+
198+
<AccordionGroup>
199+
200+
<Accordion title="Can I switch between SQL and Formula on the same table calculation?">
201+
No. The input mode is chosen when you create the table calculation
202+
and can't be changed afterwards, because formulas and SQL aren't
203+
always losslessly interconvertible. If you need to move a SQL calc to
204+
a formula (or vice versa), delete the old one and create a new one in
205+
the mode you want.
206+
</Accordion>
207+
208+
<Accordion title="What happens if my warehouse isn't supported yet?">
209+
The Formula toggle is hidden and the SQL editor is the only option.
210+
Existing SQL table calculations keep working on every warehouse. The
211+
beta is strictly additive.
212+
</Accordion>
213+
214+
<Accordion title="I found a bug or want a function that isn't listed">
215+
Post in the [Lightdash Community Slack](https://join.slack.com/t/lightdash-community/shared_invite/zt-3pbwqmq5e-vhTc7HHcS787w618ngoPHA)
216+
or [open a GitHub issue](https://github.com/lightdash/lightdash/issues).
217+
See [Contact Us](/contact/contact-info) for more options.
218+
</Accordion>
219+
220+
</AccordionGroup>
221+
222+
## Related
223+
224+
- [Table calculations overview](/guides/table-calculations)
225+
- [Table calculation functions](/references/table-calculation-functions/row-functions)
226+
- [SQL templates for table calculations](/guides/table-calculations/sql-templates)
227+
- [Feature maturity levels](/references/workspace/feature-maturity-levels)

‎guides/table-calculations.mdx‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
title: "Table calculations"
3+
sidebarTitle: "Overview"
34
description: "Table calculations make it easy to create metrics on the fly (for example, aggregating the data in your table over some window, or getting a running total of a column)."
45
---
56

@@ -9,7 +10,16 @@ You add table calculations in the Explore view and they appear as green columns
910
<img src="/images/guides/table-calculations/table-calculations-add-a932fb32af1dc604d4ef709886f9a833.jpg"/>
1011
</Frame>
1112

12-
Table calculations are built using raw SQL. That means you can use table calculations to build mathematical, True/False, text, and date-based calculations (basically, anything you can do in SQL, you can do in table calculations).
13+
Table calculations can be built in two ways:
14+
15+
- **[Formula](/guides/formula-table-calculations)** (Beta): a spreadsheet-style syntax that reads like Google Sheets. The default mode for new table calculations on supported warehouses.
16+
- **SQL**: raw SQL, available on every warehouse.
17+
18+
<Info>
19+
**[Formula table calculations](/guides/formula-table-calculations) are in Beta (Early Access).** Enabled by default on supported warehouses: BigQuery, ClickHouse, Databricks, DuckDB, PostgreSQL, Redshift, and Snowflake. See [feature maturity levels](/references/workspace/feature-maturity-levels).
20+
</Info>
21+
22+
With either mode you can build mathematical, True/False, text, and date-based calculations on top of your results.
1323

1424
## When to use table calculations
1525

‎images/guides/formula-table-calculations/create-table-calculation-formula-dark.png‎

133 KB
Loading

‎images/guides/formula-table-calculations/create-table-calculation-formula-light.png‎

148 KB
Loading

‎images/guides/formula-table-calculations/table-calculation-formula-in-table-dark.png‎

194 KB
Loading

‎images/guides/formula-table-calculations/table-calculation-formula-in-table-light.png‎

215 KB
Loading

0 commit comments

Comments
 (0)