Add calculated fields documentation

docs-mintlify/docs.json

@@ -57,6 +57,7 @@
                 ]
               },
               "docs/explore-analyze/explore",
+              "docs/explore-analyze/calculated-fields",
               "docs/explore-analyze/analytics-chat"
             ]
           },

docs-mintlify/docs/explore-analyze/calculated-fields.mdx

@@ -0,0 +1,190 @@
+---
+title: Calculated fields
+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 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.
+
+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.
+
+## Creating calculated fields
+
+### Point and click
+
+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
+  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. The inner query
+retrieves semantic model measures using the `MEASURE()` function, and the outer
+query computes the derived value.
+
+## How it works under the hood
+
+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.
+
+This backend execution model has key advantages over tools that compute custom
+fields in the browser:
+
+- **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 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 completion rate 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 combinations
+
+Combine multiple measures to calculate profit and margin:
+
+```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 (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 metrics | Reusable, governed metrics |
+
+When you find yourself reusing the same calculated field across multiple queries,
+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
+[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
+[ref-pre-agg]: /docs/pre-aggregations/getting-started