From b66972593a2f6f70d691aef1269c6e8285613e93 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 3 Apr 2026 05:22:19 +0000 Subject: [PATCH 1/2] Add calculated fields documentation to Explore & Analyze section Generated-By: mintlify-agent --- docs-mintlify/docs.json | 1 + .../explore-analyze/calculated-fields.mdx | 153 ++++++++++++++++++ 2 files changed, 154 insertions(+) create mode 100644 docs-mintlify/docs/explore-analyze/calculated-fields.mdx diff --git a/docs-mintlify/docs.json b/docs-mintlify/docs.json index 8980769b696dd..3b9ccdc8f118f 100644 --- a/docs-mintlify/docs.json +++ b/docs-mintlify/docs.json @@ -57,6 +57,7 @@ ] }, "docs/explore-analyze/explore", + "docs/explore-analyze/calculated-fields", "docs/explore-analyze/analytics-chat" ] }, diff --git a/docs-mintlify/docs/explore-analyze/calculated-fields.mdx b/docs-mintlify/docs/explore-analyze/calculated-fields.mdx new file mode 100644 index 0000000000000..5a2e94d92228c --- /dev/null +++ b/docs-mintlify/docs/explore-analyze/calculated-fields.mdx @@ -0,0 +1,153 @@ +--- +title: Calculated fields +description: Create ad-hoc calculations on top of your semantic model measures and dimensions at query time without modifying the data model. +--- + +Calculated fields let you derive new metrics and dimensions at query time using +[Semantic SQL][ref-semantic-sql]. Instead of modifying the data model, you can +write expressions that combine, transform, or compute values on top of existing +measures and dimensions directly in your query. + +This is useful when you need a one-off calculation for a specific analysis, want +to experiment with a new metric before adding it to the data model, or need to +create a derived value that is only relevant to a particular report. + +## How calculated fields work + +Calculated fields use [query post-processing][ref-post-processing] in Semantic +SQL. You write a semantic query as an inner query that selects measures and +dimensions from your data model, then wrap it in an outer query that performs +additional calculations. + +The inner query runs through the semantic layer with full governance, access +control, and pre-aggregation support. The outer query then applies your custom +calculations on top of those results. + +```sql +SELECT + status, + total_revenue, + total_orders, + total_revenue / total_orders AS avg_order_value +FROM ( + SELECT + status, + MEASURE(total_revenue) AS total_revenue, + MEASURE(count) AS total_orders + FROM orders + GROUP BY 1 +) AS data +``` + +In this example, `avg_order_value` is a calculated field that divides +`total_revenue` by `total_orders`. The inner query retrieves the semantic model +measures, and the outer query computes the derived value. + +## Where you can use calculated fields + +### Workbooks + +In a [Semantic Query tab][ref-querying-data], switch to the SQL editor and write +a query with an outer `SELECT` that includes your calculated expressions. This +gives you full control over the query while still leveraging the semantic layer +for the underlying data. + +### Explore + +When exploring data from a dashboard or Analytics Chat result, you can open the +SQL editor in [Explore][ref-explore] to add calculated fields to your query. + +### Analytics Chat + +The AI agent in [Analytics Chat][ref-analytics-chat] can create calculated fields +automatically. When you ask a question that requires a derived metric, the agent +writes Semantic SQL with post-processing to compute the result. You can ask +the agent to save frequently used calculations to your data model as permanent +measures or dimensions. + +## Examples + +### Ratios and percentages + +Calculate a percentage by dividing one measure by another: + +```sql +SELECT + category, + completed_orders, + total_orders, + ROUND(100.0 * completed_orders / total_orders, 1) AS completion_rate +FROM ( + SELECT + category, + MEASURE(completed_count) AS completed_orders, + MEASURE(count) AS total_orders + FROM orders + GROUP BY 1 +) AS data +``` + +### Conditional logic + +Use `CASE` expressions to create categorical fields: + +```sql +SELECT + customer_name, + lifetime_value, + CASE + WHEN lifetime_value >= 10000 THEN 'Enterprise' + WHEN lifetime_value >= 1000 THEN 'Mid-market' + ELSE 'Small' + END AS customer_tier +FROM ( + SELECT + name AS customer_name, + MEASURE(lifetime_value) AS lifetime_value + FROM customers + GROUP BY 1 +) AS data +``` + +### Arithmetic operations + +Combine multiple measures with arithmetic: + +```sql +SELECT + product_name, + revenue, + cost, + revenue - cost AS profit, + ROUND(100.0 * (revenue - cost) / revenue, 1) AS margin_pct +FROM ( + SELECT + name AS product_name, + MEASURE(total_revenue) AS revenue, + MEASURE(total_cost) AS cost + FROM products + GROUP BY 1 +) AS data +``` + +## Calculated fields vs. data model measures + +| | Calculated fields | Data model measures | +| --- | --- | --- | +| **Defined in** | Query (Semantic SQL) | Data model (YAML or JavaScript) | +| **Scope** | Single query or report | Available across all queries | +| **Pre-aggregation support** | Outer calculations are not pre-aggregated | Fully supported | +| **Access control** | Inherits from underlying members | Managed in the data model | +| **Best for** | Ad-hoc analysis, prototyping | Reusable, governed metrics | + +When you find yourself reusing the same calculated field across multiple queries, +consider adding it to your data model as a [calculated measure or +dimension][ref-calculated-members] to take advantage of pre-aggregations, +access control, and discoverability across your team. + +[ref-semantic-sql]: /docs/introduction#semantic-sql +[ref-post-processing]: /reference/core-data-apis/sql-api/query-format#query-post-processing +[ref-querying-data]: /docs/explore-analyze/workbooks/querying-data +[ref-explore]: /docs/explore-analyze/explore +[ref-analytics-chat]: /docs/explore-analyze/analytics-chat +[ref-calculated-members]: /docs/data-modeling/concepts/calculated-members From a3f58b6c9b1b8c5a3e9d1a352d5f6fc22f9dbb49 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 3 Apr 2026 15:19:24 +0000 Subject: [PATCH 2/2] docs: rewrite calculated fields to cover UI, AI agent, and SQL creation methods Generated-By: mintlify-agent --- .../explore-analyze/calculated-fields.mdx | 125 ++++++++++++------ 1 file changed, 81 insertions(+), 44 deletions(-) diff --git a/docs-mintlify/docs/explore-analyze/calculated-fields.mdx b/docs-mintlify/docs/explore-analyze/calculated-fields.mdx index 5a2e94d92228c..d938dbbd7c777 100644 --- a/docs-mintlify/docs/explore-analyze/calculated-fields.mdx +++ b/docs-mintlify/docs/explore-analyze/calculated-fields.mdx @@ -1,27 +1,61 @@ --- title: Calculated fields -description: Create ad-hoc calculations on top of your semantic model measures and dimensions at query time without modifying the data model. +description: Create ad-hoc calculations at query time by pointing and clicking in the UI, asking the AI agent, or writing Semantic SQL by hand. --- -Calculated fields let you derive new metrics and dimensions at query time using -[Semantic SQL][ref-semantic-sql]. Instead of modifying the data model, you can -write expressions that combine, transform, or compute values on top of existing -measures and dimensions directly in your query. +Calculated fields let you derive new metrics and dimensions at query time without +modifying the data model. You can create them by pointing and clicking in the +workbook UI, asking the AI agent, or writing Semantic SQL manually. -This is useful when you need a one-off calculation for a specific analysis, want -to experiment with a new metric before adding it to the data model, or need to -create a derived value that is only relevant to a particular report. +Unlike other analytics tools where custom fields are computed in the browser, +Cube compiles calculated fields into SQL and pushes computation down to your +data warehouse. This means calculated fields have no frontend row limits, +can operate on the full dataset, and benefit from the same query optimization +as any other warehouse query. -## How calculated fields work +## Creating calculated fields -Calculated fields use [query post-processing][ref-post-processing] in Semantic -SQL. You write a semantic query as an inner query that selects measures and -dimensions from your data model, then wrap it in an outer query that performs -additional calculations. +### Point and click -The inner query runs through the semantic layer with full governance, access -control, and pre-aggregation support. The outer query then applies your custom -calculations on top of those results. +In a [Semantic Query tab][ref-querying-data], you can create calculated fields +directly from the workbook UI: + +1. Open a workbook and select a **Semantic Query** tab. +2. Click the **+** button next to the measures or dimensions list to add a + calculated field. +3. Define your calculation using the available measures and dimensions. The UI + provides an expression editor where you can combine fields with arithmetic + operators, functions, and conditional logic. +4. Give the calculated field a name and run the query. + +The calculated field appears alongside your other query results and can be used +in charts, pivots, and filters within the same workbook. + +### AI agent + +The AI agent in [Analytics Chat][ref-analytics-chat] and in +[workbook Semantic Query tabs][ref-querying-data] can create calculated fields +for you automatically. + +Ask a question that requires a derived metric, and the agent writes the +appropriate Semantic SQL with post-processing to compute the result. For example: + +- _"Show me the profit margin for each product category"_ +- _"What percentage of orders are completed vs. total orders?"_ +- _"Add a column that classifies customers as enterprise, mid-market, or small + based on their lifetime value"_ + +The agent generates the query, including any calculated fields, and returns +the results. You can then explore the results further or save the query to a +workbook. + +### Semantic SQL + +For full control, write [Semantic SQL][ref-semantic-sql] directly in the SQL +editor of a workbook or Explore. Calculated fields use +[query post-processing][ref-post-processing]: you write an inner query that +selects measures and dimensions from your data model, then wrap it in an outer +query that performs additional calculations. ```sql SELECT @@ -39,37 +73,38 @@ FROM ( ) AS data ``` -In this example, `avg_order_value` is a calculated field that divides -`total_revenue` by `total_orders`. The inner query retrieves the semantic model -measures, and the outer query computes the derived value. - -## Where you can use calculated fields - -### Workbooks +In this example, `avg_order_value` is a calculated field. The inner query +retrieves semantic model measures using the `MEASURE()` function, and the outer +query computes the derived value. -In a [Semantic Query tab][ref-querying-data], switch to the SQL editor and write -a query with an outer `SELECT` that includes your calculated expressions. This -gives you full control over the query while still leveraging the semantic layer -for the underlying data. +## How it works under the hood -### Explore +When you create a calculated field—whether through the UI, the AI agent, or +by writing SQL—Cube compiles the entire query, including your calculated +expressions, into a single SQL statement that runs on your data warehouse. -When exploring data from a dashboard or Analytics Chat result, you can open the -SQL editor in [Explore][ref-explore] to add calculated fields to your query. +This backend execution model has key advantages over tools that compute custom +fields in the browser: -### Analytics Chat +- **No row limits.** Frontend-calculated fields are limited to the rows fetched + to the browser (typically a few thousand). Cube's calculated fields operate on + the full dataset in the warehouse. +- **Warehouse-native performance.** Your data warehouse optimizes and + parallelizes the computation. Complex calculations over millions of rows + complete in seconds rather than stalling the browser. +- **Consistent results.** Because the calculation happens on the full dataset + before any row limit is applied, aggregations and percentages reflect the + complete data—not a truncated sample. -The AI agent in [Analytics Chat][ref-analytics-chat] can create calculated fields -automatically. When you ask a question that requires a derived metric, the agent -writes Semantic SQL with post-processing to compute the result. You can ask -the agent to save frequently used calculations to your data model as permanent -measures or dimensions. +The inner query still passes through the semantic layer with full governance, +access control, and [pre-aggregation][ref-pre-agg] support. The outer +calculation runs on top of those governed results. ## Examples ### Ratios and percentages -Calculate a percentage by dividing one measure by another: +Calculate a completion rate by dividing one measure by another: ```sql SELECT @@ -109,9 +144,9 @@ FROM ( ) AS data ``` -### Arithmetic operations +### Arithmetic combinations -Combine multiple measures with arithmetic: +Combine multiple measures to calculate profit and margin: ```sql SELECT @@ -134,16 +169,17 @@ FROM ( | | Calculated fields | Data model measures | | --- | --- | --- | -| **Defined in** | Query (Semantic SQL) | Data model (YAML or JavaScript) | +| **Defined in** | Query (UI, AI agent, or Semantic SQL) | Data model (YAML or JavaScript) | | **Scope** | Single query or report | Available across all queries | +| **Execution** | Compiled to SQL, runs on the warehouse | Compiled to SQL, runs on the warehouse | | **Pre-aggregation support** | Outer calculations are not pre-aggregated | Fully supported | | **Access control** | Inherits from underlying members | Managed in the data model | -| **Best for** | Ad-hoc analysis, prototyping | Reusable, governed metrics | +| **Best for** | Ad-hoc analysis, prototyping metrics | Reusable, governed metrics | When you find yourself reusing the same calculated field across multiple queries, -consider adding it to your data model as a [calculated measure or -dimension][ref-calculated-members] to take advantage of pre-aggregations, -access control, and discoverability across your team. +consider promoting it to a [calculated measure or dimension][ref-calculated-members] +in your data model. This gives you pre-aggregation support, access control, and +discoverability across your team. [ref-semantic-sql]: /docs/introduction#semantic-sql [ref-post-processing]: /reference/core-data-apis/sql-api/query-format#query-post-processing @@ -151,3 +187,4 @@ access control, and discoverability across your team. [ref-explore]: /docs/explore-analyze/explore [ref-analytics-chat]: /docs/explore-analyze/analytics-chat [ref-calculated-members]: /docs/data-modeling/concepts/calculated-members +[ref-pre-agg]: /docs/pre-aggregations/getting-started