diff --git a/guides/formula-table-calculations.mdx b/guides/formula-table-calculations.mdx index 5d39f79a..e4699031 100644 --- a/guides/formula-table-calculations.mdx +++ b/guides/formula-table-calculations.mdx @@ -1,23 +1,14 @@ --- title: "Formula table calculations" description: "Build table calculations using a spreadsheet-style formula syntax instead of raw SQL." -sidebarTitle: "Formula (Beta)" +sidebarTitle: "Formula" --- - - **Formula table calculations are in [Beta](/references/workspace/feature-maturity-levels).** - - The feature is enabled by default on supported warehouses, with no - flag required, and we're actively expanding the function catalog. - We'd love your feedback while we iterate. See [feature maturity levels](/references/workspace/feature-maturity-levels) - for details. - - Formula table calculations let you write table calculations in a spreadsheet-style syntax, the way you would in Google Sheets or Excel, -instead of raw SQL. When you create a new [table calculation](/guides/table-calculations) -on a supported warehouse, **Formula** is the default input mode. You -can switch to the SQL editor any time. +instead of raw SQL. When you create a new [table calculation](/guides/table-calculations), +**Formula** is the default input mode. You can switch to the SQL editor +any time. Creating a formula table calculation @@ -37,20 +28,10 @@ editor is always one click away. ## Supported warehouses -| Warehouse | Formula support | -| ----------- | --------------- | -| BigQuery | ✅ | -| ClickHouse | ✅ | -| Databricks | ✅ | -| DuckDB | ✅ | -| PostgreSQL | ✅ | -| Redshift | ✅ | -| Snowflake | ✅ | -| Athena | 🚧 Not yet | -| Trino | 🚧 Not yet | - -On warehouses where formulas aren't supported yet, the Formula toggle -is hidden and the SQL editor works exactly as it always has. +Formula table calculations work on every warehouse Lightdash supports: +Athena, BigQuery, ClickHouse, Databricks, DuckDB, PostgreSQL, Redshift, +Snowflake, and Trino. The same formula compiles to the correct SQL for +whichever warehouse your project is connected to. ## Writing your first formula @@ -111,13 +92,21 @@ You can use: ### Date -| Function | Description | -| ------------ | --------------------- | -| `TODAY()` | Current date | -| `NOW()` | Current timestamp | -| `YEAR(d)` | Extract year | -| `MONTH(d)` | Extract month | -| `DAY(d)` | Extract day | +| Function | Description | +| --------------------------------- | -------------------------------------------------------------------------------------------- | +| `TODAY()` | Current date | +| `NOW()` | Current timestamp | +| `YEAR(d)` | Extract year | +| `MONTH(d)` | Extract month | +| `DAY(d)` | Extract day | +| `LAST_DAY(d)` | Last day of the month containing `d` | +| `DATE_TRUNC(d, unit)` | Truncate `d` to the start of `unit` (`"day"`, `"week"`, `"month"`, `"quarter"`, `"year"`) | +| `DATE_ADD(d, n, unit)` | Add `n` whole `unit`s to `d` (e.g. `DATE_ADD(orders_date, 3, "month")`) | +| `DATE_SUB(d, n, unit)` | Subtract `n` whole `unit`s from `d` | +| `DATE_DIFF(start, end, unit)` | Whole-`unit` calendar-boundary difference. Positive when `end > start`. | + +`unit` is always one of `"day"`, `"week"`, `"month"`, `"quarter"`, +`"year"` — quoted as a string literal. ### Aggregation @@ -205,12 +194,6 @@ a formula (or vice versa), delete the old one and create a new one in the mode you want. - -The Formula toggle is hidden and the SQL editor is the only option. -Existing SQL table calculations keep working on every warehouse. The -beta is strictly additive. - - Post in the [Lightdash Community Slack](https://join.slack.com/t/lightdash-community/shared_invite/zt-3pbwqmq5e-vhTc7HHcS787w618ngoPHA) or [open a GitHub issue](https://github.com/lightdash/lightdash/issues). @@ -224,4 +207,3 @@ See [Contact Us](/contact/contact-info) for more options. - [Table calculations overview](/guides/table-calculations) - [Table calculation functions](/references/table-calculation-functions/row-functions) - [SQL templates for table calculations](/guides/table-calculations/sql-templates) -- [Feature maturity levels](/references/workspace/feature-maturity-levels) diff --git a/guides/table-calculations.mdx b/guides/table-calculations.mdx index fe9d7554..2398dc30 100644 --- a/guides/table-calculations.mdx +++ b/guides/table-calculations.mdx @@ -7,19 +7,16 @@ description: "Table calculations make it easy to create metrics on the fly (for You add table calculations in the Explore view and they appear as green columns in your results table (remember, [dimensions](/references/dimensions) are blue, and [metrics](/references/metrics) are orange). - + Table calculation column in the results table + Table calculation column in the results table Table calculations can be built in two ways: -- **[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. -- **SQL**: raw SQL, available on every warehouse. +- **[Formula](/guides/formula-table-calculations)**: a spreadsheet-style syntax that reads like Google Sheets. The default mode for new table calculations. +- **SQL**: raw SQL. - - **[Formula table calculations](/guides/formula-table-calculations) are in [Beta](/references/workspace/feature-maturity-levels).** Enabled by default on supported warehouses: BigQuery, ClickHouse, Databricks, DuckDB, PostgreSQL, Redshift, and Snowflake. - - -With either mode you can build mathematical, True/False, text, and date-based calculations on top of your results. +Both modes are available on every warehouse Lightdash supports. With either mode you can build mathematical, True/False, text, and date-based calculations on top of your results. ## When to use table calculations @@ -48,7 +45,8 @@ Table calculations work with whatever data you've already pulled into your resul Quick calculations are shortcuts to the most common table calculations, these are only available to metrics in the contextual menu in the results table. -![](/images/guides/table-calculations/quick-table-calculation-b1e76d3e54d84ca3c5066ffdf989514b.png) + Quick calculation menu on a metric column + Quick calculation menu on a metric column To learn more about what these calculations are doing, check out the docs [here](/guides/table-calculations/sql-templates). Once the table calculation is generated you can edit it to modify the SQL query or update the format. @@ -58,7 +56,8 @@ To learn more about what these calculations are doing, check out the docs [here] Once you've got some data in your results table, you can create a table calculation by clicking on the `+ Table calculation` in the `Results` tab of the Explore view: - ![](/images/guides/table-calculations/create-new-table-calc-772add6d063a5122c0a25accf798fbb3.jpg) + + Table calculation button in the Results header + + Table calculation button in the Results header ##### Write the SQL for your table calculation in the pop-up box @@ -68,7 +67,8 @@ Your table calculation is defined using raw SQL that you write up in this pop up To reference the metrics and dimensions in your results table, you can either use the autocomplete, or you can manually write the full field name using the format `${table_name.field_name}`. - ![](/images/guides/table-calculations/add-table-calc-sql-20de5398dc117ef3d4087cf3b6d9939b.jpg) + Add table calculation modal with SQL editor and inline format options + Add table calculation modal with SQL editor and inline format options @@ -84,10 +84,11 @@ These functions compile to SQL window functions automatically, so you don't need ##### Update the format of your table calculation (if needed) -If needed, you can update the format of your table calculation to things like percent formatting using the `format` tab. +If needed, you can update the format of your table calculation — percent, currency, number with custom prefix/suffix — in the **Format** section of the modal, just below the SQL editor. - ![](/images/guides/table-calculations/format-table-calc-c0e3828b6681db084b4ddd6799ff2c96.jpg) + Format options for a table calculation + Format options for a table calculation | Format types | Description | Raw value | How it might look like in Lightdash | @@ -97,12 +98,13 @@ If needed, you can update the format of your table calculation to things like pe | Currency | Adds currency symbol and default locale format | 1234.1234 | $ 1234.12 | | Number | Formats number with prefix and suffix | 123.1234 | Speed: 123.12 km/h | -##### To delete or edit your table calculation, just click on the gear icon by the field name +##### To edit or remove your table calculation, open the column dropdown -If you need to edit or delete a table calculation, you can just click on the toggle beside the field and do what you need to do! +Click the chevron next to the table calculation column header in the results table. From there you can **Edit calculation** to reopen the modal, or **Remove** to drop it. - ![](/images/guides/table-calculations/edit-delete-table-calc-520776c8631697527bf3760000dce88e.jpg) + Edit / delete dropdown on a table calculation column header + Edit / delete dropdown on a table calculation column header diff --git a/images/guides/formula-table-calculations/create-table-calculation-formula-dark.png b/images/guides/formula-table-calculations/create-table-calculation-formula-dark.png index cf685598..4e4f9922 100644 Binary files a/images/guides/formula-table-calculations/create-table-calculation-formula-dark.png and b/images/guides/formula-table-calculations/create-table-calculation-formula-dark.png differ diff --git a/images/guides/formula-table-calculations/create-table-calculation-formula-light.png b/images/guides/formula-table-calculations/create-table-calculation-formula-light.png index 4780ea15..ef0a33a7 100644 Binary files a/images/guides/formula-table-calculations/create-table-calculation-formula-light.png and b/images/guides/formula-table-calculations/create-table-calculation-formula-light.png differ diff --git a/images/guides/table-calculations/add-table-calc-sql-20de5398dc117ef3d4087cf3b6d9939b.jpg b/images/guides/table-calculations/add-table-calc-sql-20de5398dc117ef3d4087cf3b6d9939b.jpg deleted file mode 100644 index bbb69ccf..00000000 Binary files a/images/guides/table-calculations/add-table-calc-sql-20de5398dc117ef3d4087cf3b6d9939b.jpg and /dev/null differ diff --git a/images/guides/table-calculations/create-new-table-calc-772add6d063a5122c0a25accf798fbb3.jpg b/images/guides/table-calculations/create-new-table-calc-772add6d063a5122c0a25accf798fbb3.jpg deleted file mode 100644 index e0695d8e..00000000 Binary files a/images/guides/table-calculations/create-new-table-calc-772add6d063a5122c0a25accf798fbb3.jpg and /dev/null differ diff --git a/images/guides/table-calculations/create-table-calc-button-dark.png b/images/guides/table-calculations/create-table-calc-button-dark.png new file mode 100644 index 00000000..22361863 Binary files /dev/null and b/images/guides/table-calculations/create-table-calc-button-dark.png differ diff --git a/images/guides/table-calculations/create-table-calc-button-light.png b/images/guides/table-calculations/create-table-calc-button-light.png new file mode 100644 index 00000000..0f163d6f Binary files /dev/null and b/images/guides/table-calculations/create-table-calc-button-light.png differ diff --git a/images/guides/table-calculations/edit-delete-table-calc-520776c8631697527bf3760000dce88e.jpg b/images/guides/table-calculations/edit-delete-table-calc-520776c8631697527bf3760000dce88e.jpg deleted file mode 100644 index 13f50a41..00000000 Binary files a/images/guides/table-calculations/edit-delete-table-calc-520776c8631697527bf3760000dce88e.jpg and /dev/null differ diff --git a/images/guides/table-calculations/format-table-calc-c0e3828b6681db084b4ddd6799ff2c96.jpg b/images/guides/table-calculations/format-table-calc-c0e3828b6681db084b4ddd6799ff2c96.jpg deleted file mode 100644 index 15173089..00000000 Binary files a/images/guides/table-calculations/format-table-calc-c0e3828b6681db084b4ddd6799ff2c96.jpg and /dev/null differ diff --git a/images/guides/table-calculations/quick-calculation-menu-dark.png b/images/guides/table-calculations/quick-calculation-menu-dark.png new file mode 100644 index 00000000..0e0b7214 Binary files /dev/null and b/images/guides/table-calculations/quick-calculation-menu-dark.png differ diff --git a/images/guides/table-calculations/quick-calculation-menu-light.png b/images/guides/table-calculations/quick-calculation-menu-light.png new file mode 100644 index 00000000..32c93dac Binary files /dev/null and b/images/guides/table-calculations/quick-calculation-menu-light.png differ diff --git a/images/guides/table-calculations/quick-table-calculation-b1e76d3e54d84ca3c5066ffdf989514b.png b/images/guides/table-calculations/quick-table-calculation-b1e76d3e54d84ca3c5066ffdf989514b.png deleted file mode 100644 index 2dc9d669..00000000 Binary files a/images/guides/table-calculations/quick-table-calculation-b1e76d3e54d84ca3c5066ffdf989514b.png and /dev/null differ diff --git a/images/guides/table-calculations/table-calc-edit-delete-dark.png b/images/guides/table-calculations/table-calc-edit-delete-dark.png new file mode 100644 index 00000000..60f5be8d Binary files /dev/null and b/images/guides/table-calculations/table-calc-edit-delete-dark.png differ diff --git a/images/guides/table-calculations/table-calc-edit-delete-light.png b/images/guides/table-calculations/table-calc-edit-delete-light.png new file mode 100644 index 00000000..223aa609 Binary files /dev/null and b/images/guides/table-calculations/table-calc-edit-delete-light.png differ diff --git a/images/guides/table-calculations/table-calc-format-dark.png b/images/guides/table-calculations/table-calc-format-dark.png new file mode 100644 index 00000000..242fd9e7 Binary files /dev/null and b/images/guides/table-calculations/table-calc-format-dark.png differ diff --git a/images/guides/table-calculations/table-calc-format-light.png b/images/guides/table-calculations/table-calc-format-light.png new file mode 100644 index 00000000..40683a42 Binary files /dev/null and b/images/guides/table-calculations/table-calc-format-light.png differ diff --git a/images/guides/table-calculations/table-calc-modal-dark.png b/images/guides/table-calculations/table-calc-modal-dark.png new file mode 100644 index 00000000..8e84ddd5 Binary files /dev/null and b/images/guides/table-calculations/table-calc-modal-dark.png differ diff --git a/images/guides/table-calculations/table-calc-modal-light.png b/images/guides/table-calculations/table-calc-modal-light.png new file mode 100644 index 00000000..66737ba9 Binary files /dev/null and b/images/guides/table-calculations/table-calc-modal-light.png differ diff --git a/images/guides/table-calculations/table-calc-results-dark.png b/images/guides/table-calculations/table-calc-results-dark.png new file mode 100644 index 00000000..21402def Binary files /dev/null and b/images/guides/table-calculations/table-calc-results-dark.png differ diff --git a/images/guides/table-calculations/table-calc-results-light.png b/images/guides/table-calculations/table-calc-results-light.png new file mode 100644 index 00000000..ab80578f Binary files /dev/null and b/images/guides/table-calculations/table-calc-results-light.png differ diff --git a/images/guides/table-calculations/table-calculations-add-a932fb32af1dc604d4ef709886f9a833.jpg b/images/guides/table-calculations/table-calculations-add-a932fb32af1dc604d4ef709886f9a833.jpg deleted file mode 100644 index 928b73c6..00000000 Binary files a/images/guides/table-calculations/table-calculations-add-a932fb32af1dc604d4ef709886f9a833.jpg and /dev/null differ