@malloydata/render 0.0.423 → 0.0.425

package/docs/renderer_tags_overview.md

@@ -0,0 +1,916 @@
+# Malloy Renderer Tag Documentation
+
+This document outlines the tags used to control visualizations generated by the custom Malloy renderer. Add these tags as annotations to your Malloy queries (`.malloy` files) to influence how the resulting data is displayed.
+
+**Basic Syntax:**
+
+- Tags are prefixed with `#` followed by a space: `# tag_name` (e.g., `# currency`)
+- Tags with properties: `# tag_name { property1=value property2 ... }` (e.g., `# bar_chart { size=lg stack }`)
+- Boolean properties can often be added using dot notation: `# tag_name.property` (e.g., `# bar_chart.stack`)
+- Nested properties can target specific aspects: `# bar_chart { y.independent }`
+
+---
+
+## Chart Tags
+
+These tags render the entire result set as a specific chart type.
+
+### `# bar_chart`
+
+Renders the data as a bar chart. If `x`, `y`, and `series` fields aren't explicitly specified via tags, the renderer attempts to infer them from the query structure (typically first dimension for x, first measure for y, second dimension for series).
+
+**Properties:**
+
+- `.stack`: Stacks bars when a series is present.
+  - Syntax: `# bar_chart.stack` or `# bar_chart { stack }`
+- `.size`: Controls chart size presets.
+  - Values: `spark`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`.
+  - Syntax: `# bar_chart { size=lg }` or `# bar_chart.size=lg` (Legacy: `# size=lg` on the view)
+- `.size.width`: Sets a specific pixel width for the chart plot area.
+  - Syntax: `# bar_chart { size.width=300 }`
+- `.size.height`: Sets a specific pixel height for the chart plot area.
+  - Syntax: `# bar_chart { size.height=220 }`
+- `.x`: Specifies the field for the x-axis (category axis).
+  - Syntax: `# bar_chart { x=field_name }`
+  - `.x.limit`: Limits the number of bars shown on the x-axis. Automatically calculated based on chart width if not specified.
+    - Syntax: `# bar_chart { x.limit=10 }`
+  - `.x.independent`: Controls whether the x-axis scale is shared across nested charts. See "Automatic Axis/Legend Sharing" below.
+    - Syntax: `# bar_chart { x.independent }` or `# bar_chart { x.independent=false }`
+- `.y`: Specifies the field(s) for the y-axis (value axis). Can be a single field name or an array for measure-based series.
+  - Syntax: `# bar_chart { y=measure_name }` or `# bar_chart { y=['measure1', 'measure2'] }`
+  - `.y.independent`: Controls whether the y-axis scale is shared across nested charts (default is shared).
+    - Syntax: `# bar_chart { y.independent }`
+- `.series`: Specifies the field used for grouping/coloring bars.
+  - Syntax: `# bar_chart { series=dimension_name }`
+  - `.series.limit`: Limits the number of series shown (default `auto`, which uses 20 for bar charts). When limiting is active, series are ranked by their total sum of Y-values and the top N series are shown.
+    - Syntax: `# bar_chart { series.limit=5 }` or `# bar_chart { series.limit=auto }`
+  - `.series.independent`: Controls whether the series legend/colors are shared across nested charts. See "Automatic Axis/Legend Sharing" below.
+    - Syntax: `# bar_chart { series.independent }` or `# bar_chart { series.independent=false }`
+- `.title`: Sets the main title for the chart.
+  - Syntax: `# bar_chart { title='My Chart Title' }`
+- `.subtitle`: Sets a subtitle displayed below the title.
+  - Syntax: `# bar_chart { subtitle='Data for Q1' }`
+
+**Automatic Axis/Legend Sharing (Bar Chart):**
+
+- **X-Axis:** By default, the x-axis domain (the set of categories shown) is shared across nested charts _if_ the number of distinct x-values is small (currently <= 20). This keeps alignment consistent for comparable small multiples. If there are more than 20 distinct values, each nested chart gets its own independent x-axis domain.
+- **Series Legend/Colors:** Similarly, the series domain (legend items and colors) is shared across nested charts if the number of distinct series values is small (currently <= 20).
+- **Overriding:** You can force sharing by using `.independent=false` (e.g., `# bar_chart { x.independent=false }`) or force independence by using `.independent` or `.independent=true` (e.g., `# bar_chart { series.independent }`).
+- **Y-Axis:** The y-axis is shared by default unless explicitly set via `# bar_chart { y.independent }`.
+
+**Examples:**
+
+```
+// Simple bar chart, axes inferred
+# bar_chart
+view: my_bars is {
+  group_by: category
+  aggregate: total_sales
+  limit: 10
+}
+
+// Stacked bar chart with explicit axes and size
+# bar_chart { stack x=sale_month series=category y=total_sales size=lg }
+view: sales_by_month is { ... }
+
+// Measure-based series
+# bar_chart { x=brand y=['Sales $', 'Cost $'] }
+view: sales_vs_cost is { ... }
+
+// Independent Y-axis in a nested chart
+view: parent_view is {
+group_by: region
+nest: by_brand is {
+# bar_chart { y.independent title='Sales by Brand' }
+group_by: brand
+aggregate: total_sales
+limit: 5
+}
+}
+```
+
+### `# line_chart`
+
+Renders the data as a line chart. Inference for `x`, `y`, and `series` is similar to `# bar_chart`.
+
+**Properties:**
+
+- `.zero_baseline`: Controls if the y-axis must include zero. Default is `false` for line charts (unlike bar charts which always include zero). Set to `true` to force the y-axis to start at zero.
+  - Syntax: `# line_chart.zero_baseline=true` or `# line_chart { zero_baseline=true }`
+- `.size`: Controls chart size presets (e.g., `spark`).
+  - Syntax: `# line_chart { size=spark }` (Legacy: `# size=spark` on the view)
+- `.interpolate`: Sets the line interpolation mode.
+  - Values: e.g., `step`.
+  - Syntax: `# line_chart { interpolate=step }`
+- `.x`, `.y`, `.series`, `.title`, `.subtitle`: Similar to `# bar_chart` properties.
+  - `.y.independent`: Controls y-axis independence across nested charts. Also automatically set if `series.limit` is applied.
+  - `.series.limit`: Limits the number of lines (series) shown (default `auto`, which uses 12 for line charts). When limiting is active, series are ranked by their total sum of Y-values and the top N series are shown. Setting this automatically enables `y.independent=true`.
+  - `.series.independent`: Controls legend/color sharing across nested charts. See "Automatic Axis/Legend Sharing" below.
+
+**Automatic Axis/Legend Sharing (Line Chart):**
+
+- **X-Axis:** Similar to bar charts, the x-axis domain is shared by default if distinct x-values <= 20, otherwise independent.
+- **Series Legend/Colors:** Shared by default if distinct series values <= 20, otherwise independent.
+- **Overriding:** Use `.independent=false` to force sharing or `.independent` / `.independent=true` to force independence (e.g., `# line_chart { x.independent }`, `# line_chart { series.independent=false }`).
+- **Y-Axis:** Shared by default unless explicitly set via `# line_chart { y.independent }` or if `.series.limit` is used.
+
+**Examples:**
+
+```
+// Basic line chart
+# line_chart
+view: sales_trend is {
+  group_by: sale_date.month
+  aggregate: total_sales
+}
+
+// Line chart with y-axis not starting at zero
+# line_chart { zero_baseline=false }
+view: stock_price is { ... }
+
+// Multi-series line chart with limited series (implies y.independent)
+# line_chart { series.limit=5 }
+view: multi_brand_trend is {
+group_by: sale_date.day, brand
+aggregate: daily_sales
+}
+```
+
+### `# scatter_chart`
+
+_Note: This currently uses the legacy renderer._
+Renders the data as a scatter plot. Configuration relies mainly on field order (x, y, color, size, shape).
+
+**Properties:**
+
+- _(No specific nested properties identified in the current codebase examples for configuration via the tag itself, likely relies on field order/type)_
+
+**Example:**
+
+```
+# scatter_chart
+view: cost_vs_price is {
+  group_by: retail_price, cost, brand // x, y, color/shape inferred
+}
+```
+
+### `# big_value`
+
+Renders aggregate values as prominent metric cards, similar to KPI tiles in dashboards. This is ideal for displaying key metrics at a glance.
+
+**Important:** Only works with aggregate fields (measures). Does not support `group_by` dimensions.
+
+**Properties:**
+
+- `.size`: Controls card size preset.
+  - Values: `sm`, `md` (default), `lg`
+  - Syntax: `# big_value { size=lg }`
+- `.neutral_threshold`: Percentage threshold below which changes are shown as neutral (dash) instead of up/down arrows. Default is `0.05` (5%).
+  - Syntax: `# big_value { neutral_threshold=0.1 }`
+
+---
+
+#### Feature 1: Comparison Delta Indicators
+
+Show change vs a baseline value with colored up/down arrows (▲ green / ▼ red).
+
+**Field-level Properties (for comparison fields):**
+
+Add these properties to the comparison field (not the primary metric):
+
+- `.comparison_field`: The field name of the primary metric this value compares to.
+  - Syntax: `# big_value { comparison_field=current_sales }`
+- `.comparison_label`: Optional label shown next to the delta indicator.
+  - Syntax: `# big_value { comparison_label='vs Prior Year' }`
+- `.comparison_format`: How to calculate and display the change.
+  - Values: `pct` (percentage change, default) or `ppt` (percentage point difference)
+  - Syntax: `# big_value { comparison_format=ppt }`
+- `.down_is_good`: Set to `true` if a decrease should be shown as positive (green). Useful for cost or delay metrics.
+  - Syntax: `# big_value { down_is_good=true }`
+
+**Example:**
+
+```malloy
+# big_value
+view: sales_comparison is {
+  aggregate:
+    # label="Current Sales"
+    # currency
+    current_sales is revenue.sum()
+
+    // Shows: ▲ 8.7% vs Prior Year (green)
+    # big_value { comparison_field=current_sales comparison_label='vs Prior Year' }
+    # hidden
+    prior_sales is revenue.sum() * 0.92
+}
+```
+
+---
+
+#### Feature 2: Documentation Tooltips
+
+Add info icons with hover descriptions using `# description` tags.
+
+**Example:**
+
+```malloy
+# big_value
+view: documented_metrics is {
+  aggregate:
+    # description="Total revenue from completed sales. Updated daily."
+    # label="Total Revenue"
+    # currency
+    total_revenue is sales.sum()
+
+    # description="Win rate = Won / (Won + Lost). Industry average is 25%."
+    # label="Win Rate"
+    # percent
+    win_rate is won.sum() / (won.sum() + lost.sum())
+}
+```
+
+---
+
+#### Feature 3: Sparkline Trends
+
+Show mini line or bar charts alongside the metric value.
+
+**How it works:**
+
+1. Add `sparkline=nest_name` to the metric field to reference a sparkline nest
+2. Define the sparkline data as a nested view with `# line_chart { size=spark }` or `# bar_chart { size=spark }`
+3. Mark the nest as `# hidden` to prevent it from rendering separately
+
+**Metric Field Properties:**
+
+- `.sparkline`: The name of the nested view containing sparkline data.
+  - Syntax: `# big_value { sparkline=trend }`
+
+**Example:**
+
+```malloy
+# big_value
+view: sales_with_trend is {
+  aggregate:
+    # label="Total Sales"
+    # currency
+    # big_value { sparkline=trend }
+    total_sales is revenue.sum()
+
+  // Line sparkline showing trend over time
+  # line_chart { size=spark }
+  # hidden
+  nest: trend is {
+    group_by: order_date.month
+    aggregate: monthly_sales is revenue.sum()
+    order_by: order_date.month
+    limit: 12
+  }
+}
+
+// Bar sparkline
+# big_value
+view: with_bar_sparkline is {
+  aggregate:
+    # label="Order Count"
+    # big_value { sparkline=order_trend }
+    order_count is count()
+
+  # bar_chart { size=spark }
+  # hidden
+  nest: order_trend is {
+    group_by: region
+    aggregate: orders is count()
+    limit: 8
+  }
+}
+```
+
+---
+
+#### Formatting
+
+Big Value cards respect field formatting tags:
+- `# currency` - Format as currency (e.g., $1,234.56)
+- `# currency=euro` - Format as euros (€)
+- `# currency=pound` - Format as pounds (£)
+- `# percent` - Format as percentage
+- `# number="#,##0.0"` - Custom number format
+- `# number=big` - Abbreviate large numbers (1.2M, 3.5B)
+
+---
+
+#### Complete Example (All Features)
+
+```malloy
+# big_value
+view: executive_dashboard is {
+  aggregate:
+    # description="Total revenue this period. Target is $10M."
+    # label="Revenue"
+    # currency
+    # big_value { sparkline=revenue_trend }
+    revenue is sales.sum()
+
+    # big_value { comparison_field=revenue comparison_label='vs Target' }
+    # hidden
+    target_revenue is 10000000
+
+    # description="On-time delivery rate. SLA requires 95%."
+    # label="On-Time Rate"
+    # percent
+    ontime_rate is count() { where: delivered_on_time } / count()
+
+    # big_value { comparison_field=ontime_rate comparison_label='vs SLA' comparison_format=ppt }
+    # hidden
+    sla_target is 0.95
+
+  // Sparkline showing revenue trend
+  # line_chart { size=spark }
+  # hidden
+  nest: revenue_trend is {
+    group_by: order_date.month
+    aggregate: monthly_revenue is sales.sum()
+    order_by: order_date.month
+    limit: 12
+  }
+}
+```
+
+---
+
+## Data Limiting and Performance
+
+Both bar charts and line charts implement automatic data limiting to ensure good performance and readability. Understanding these limits helps you configure charts effectively.
+
+### Series Limiting
+
+**Default Limits:**
+- **Line Charts:** 12 series (when `series.limit=auto`)
+- **Bar Charts:** 20 series (when `series.limit=auto`)
+
+**How Series Are Selected:**
+When the number of unique series values exceeds the limit, the renderer:
+1. Calculates the total sum of Y-values for each series
+2. Ranks series by their total sum (highest to lowest)
+3. Shows only the top N series based on the limit
+4. Displays a message like "Showing 12 of 45 series"
+
+**Automatic Y-Axis Independence:**
+When series limiting is active, the renderer automatically sets `y.independent=true` to prevent misleading comparisons between charts that may be showing different subsets of series.
+
+### Data Point Limiting
+
+**Line Charts:**
+- Maximum of 5,000 data points per chart
+- When exceeded, shows message indicating data is limited
+- Affects the total number of plotted points after series filtering
+
+**Bar Charts:**
+- X-axis limiting based on available visual space
+- Automatically calculates how many bars can fit given the chart width and bar grouping
+- Can be overridden with `x.limit=N`
+
+### Visual Cues for Limited Data
+
+When data is limited, charts display informational messages:
+- **Series limiting:** "Showing 12 of 45 series"
+- **Data point limiting:** Indicates when data has been truncated
+
+### Nested Chart Behavior
+
+**Shared vs Independent Domains:**
+- **Root/Global charts:** Use the globally calculated top N series
+- **Nested charts:** May calculate their own local limits unless sharing is forced
+- **Automatic sharing:** Domains are shared when ≤20 distinct values, otherwise independent
+
+**Override Examples:**
+```malloy
+// Force showing all series (no limit)
+# line_chart { series.limit=1000 }
+
+// Use only top 5 series
+# bar_chart { series.limit=5 }
+
+// Force Y-axis sharing even with series limiting
+# line_chart { series.limit=8 y.independent=false }
+
+// Override bar chart X-axis limiting
+# bar_chart { x.limit=15 }
+```
+
+---
+
+## Layout & Structure Tags
+
+### `# dashboard`
+
+Arranges multiple nested views into a dashboard layout. Each nested view is rendered in its own tile.
+
+The dashboard has two layout modes. Flex mode is the default: tiles flow into a row and wrap onto a new row when it fills. Columns mode is entered with `columns=N`: tiles are placed into N equal-width columns.
+
+**Properties:**
+
+- `.table.max_height`: Sets a maximum pixel height for tables rendered within dashboard tiles. Useful for controlling layout with large tables. Set to `'none'` to disable max height.
+  - Syntax: `# dashboard { table.max_height=400 }` or `# dashboard { table.max_height=none }`
+- `.columns` (integer): Enters columns mode with N equal-width columns. A tile occupies one column by default and wraps onto a new row when a row fills. Use `# colspan` to make a tile occupy more than one column.
+  - Syntax: `# dashboard { columns=3 }`
+- `.gap` (pixels): Sets the spacing between tiles, in both flex mode and columns mode. Default is 16.
+  - Syntax: `# dashboard { gap=24 }`
+
+**Per-tile tags (applied to a nested view):**
+
+- `# colspan` (integer): In columns mode, makes the tile occupy that many columns (one by default). When a row's tiles total more than the column count, the overflow wraps onto the next row. Ignored in flex mode.
+- `# break`: Starts a new row. Tiles after a `# break` begin a fresh row. Works in both flex mode and columns mode.
+
+**Example:**
+
+```
+# dashboard
+view: sales_overview is {
+  nest: kpis is { select: total_sales, avg_margin } // Renders as text/single value
+
+# break
+nest: top_products_table is { // Renders as table
+group_by: product
+aggregate: total_sales
+limit: 5
+}
+
+nest: sales_by_category_chart is { // Renders as bar chart
+# bar_chart
+group_by: category
+aggregate: total_sales
+}
+}
+```
+
+### `# table`
+
+Explicitly renders data as a table. This is often the default for nested results if no other renderer tag is specified.
+
+**Properties:**
+
+- `.flatten`: Flattens a _single-row_ nested record's fields into the parent table as columns. The nested query should not have `group_by`.
+  - Syntax: `# flatten` (applied to the `nest:` definition)
+- `.pivot`: Transforms a nested query into horizontal columns where dimension values become column headers
+  -  Dimensions (fields in `group_by`) become column headers
+  -  Measures (fields in `aggregate`) become cell values
+  - Column headers display as "DimensionValue: measure_name"
+  -  Maximum 30 pivot columns.
+  - Syntax: `# pivot` (applied to a `nest:` or a query)
+    - `.dimensions`: Specifies which fields to use as pivot dimensions. If not specified, all `group_by` fields are used.
+    - Syntax: `# pivot { dimensions=[field1, field2] }`
+- `.transpose`: Rotates a table so rows become columns and columns become rows. Original column names become row headers, original row values become column headers. Default limit of 20 transpose columns.
+  - Syntax: `# transpose` (applied to the view)
+  - `.limit`: Override the default column limit. Syntax: `# transpose.limit=100`
+- `.size=fill`: Makes the table attempt to fill the width of its container.
+  - Syntax: `# table.size=fill`
+- `# column` (applied to a specific field within the view): Controls individual column appearance.
+  - `.width`: Sets column width. Accepts named sizes (`xs`, `sm`, `md`, `lg`, `xl`, `2xl`) or pixel values.
+    - Syntax: `# column { width=lg }` or `# column { width=150 }`
+  - `.height`: Sets a specific row height for cells in this column (in pixels).
+    - Syntax: `# column { height=40 }`
+  - `.word_break=break_all`: Allows long words/strings without spaces to break and wrap within the cell.
+    - Syntax: `# column { word_break=break_all }`
+
+**Examples:**
+
+```malloy
+// Column width and flatten
+view: detailed_table is {
+  group_by:
+    category
+    # column { width=lg }
+    brand
+  aggregate: total_sales
+
+  # flatten
+  nest: metrics is {
+    aggregate: avg_price, total_cost
+  }
+}
+
+// Pivot - dimensions auto-detected from group_by
+view: sales_by_category is {
+  group_by: category
+  aggregate: total_sales is sales.sum()
+
+  # pivot
+  nest: by_department is {
+    group_by: department
+    aggregate:
+      avg_price is price.avg()
+      total_units is units.sum()
+  }
+}
+// Creates columns: Men: avg_price | Men: total_units | Women: avg_price | Women: total_units
+
+// Pivot with explicit dimensions
+view: regional_sales is {
+  group_by: year
+  # pivot { dimensions=[region] }
+  nest: by_region is {
+    group_by: region
+    aggregate:
+      total_sales is sales.sum()
+      avg_margin is margin.avg()
+  }
+}
+
+// Transpose - swap rows and columns
+# transpose
+view: metrics_summary is {
+  group_by: category
+  aggregate:
+    avg_price is price.avg()
+    total_sales is sales.sum()
+    product_count is count()
+}
+// Instead of categories as rows, displays as:
+// |               | Jeans  | Outerwear |
+// |---------------|--------|-----------|
+// | avg_price     | 97.41  | 145.37    |
+// | total_sales   | 104,776| 92,269    |
+// | product_count | 1,024  | 856       |
+```
+
+### `# list`
+
+Renders the first non-hidden field of a nested result as a comma-separated list.
+
+**Example:**
+
+```
+view: product_summary is {
+  group_by: category
+  # list
+  nest: top_brands is {
+    group_by: brand
+    aggregate: total_sales
+    order_by: 2 desc
+    limit: 3
+  }
+}
+// Output might look like: Clothing: Brand A, Brand B, Brand C
+```
+
+### `# list_detail`
+
+Similar to `# list`, but uses the first two non-hidden fields to render items as `value (detail)`.
+
+**Example:**
+
+```
+view: brand_counts is {
+  group_by: category
+  # list_detail
+  nest: brand_details is {
+    group_by: brand
+    aggregate: num_products is count()
+    order_by: 2 desc
+    limit: 3
+  }
+}
+// Output might look like: Clothing: Brand A (15), Brand B (12), Brand C (10)
+```
+
+---
+
+## Field-Level Formatting & Rendering Tags
+
+These tags are typically applied directly to individual fields within a query.
+
+### `# currency`
+
+Formats a numeric field as currency. Supports both **shorthand** and **verbose** syntax for scaling and formatting options.
+
+#### Shorthand Syntax (Recommended)
+
+Pattern: `# currency={code}{decimals}{scale}`
+
+- `{code}`: Currency code (`usd`, `eur`, `gbp`)
+- `{decimals}`: Number of decimal places (0-4)
+- `{scale}`: Scale letter (`k`, `m`, `b`, `t`, `q`) - case insensitive
+
+| Tag | Output | Description |
+|-----|--------|-------------|
+| `# currency=usd` | $412 | USD, default decimals |
+| `# currency=usd0` | $412 | 0 decimals |
+| `# currency=usd2` | $412.12 | 2 decimals |
+| `# currency=usd0k` | $412k | thousands, 0 decimals |
+| `# currency=usd1m` | $412.1m | millions, 1 decimal |
+| `# currency=usd0b` | $1b | billions, 0 decimals |
+| `# currency=eur2m` | €412.12m | Euro, millions, 2 decimals |
+| `# currency=gbp1b` | £1.4b | Pound, billions, 1 decimal |
+
+#### Verbose Syntax (Advanced Options)
+
+For suffix format control, use verbose syntax:
+
+```malloy
+# currency { scale=m decimals=2 suffix=finance }  // $412.12MM
+# currency { scale=k suffix=none }                // $412 (no suffix)
+# currency { scale=auto }                         // auto-scale like number=big
+```
+
+**Scale Options:** `k` (thousands), `m` (millions), `b` (billions), `t` (trillions), `q` (quadrillions), `auto`
+
+**Suffix Format Options:**
+
+| Format | k | m | b | t | q |
+|--------|---|---|---|---|---|
+| `letter` | K | M | B | T | Q |
+| `lower` (shorthand default) | k | m | b | t | q |
+| `word` | Thousand | Million | Billion | Trillion | Quadrillion |
+| `short` | K | Mil | Bil | Tril | Quad |
+| `finance` | M | MM | B | T | Q |
+| `scientific` | ×10³ | ×10⁶ | ×10⁹ | ×10¹² | ×10¹⁵ |
+| `none` | (empty) | (empty) | (empty) | (empty) | (empty) |
+
+**Example:**
+
+```malloy
+source: financials extend {
+  # currency=usd
+  measure: total_revenue is sales.sum()
+
+  # currency=usd0m
+  measure: revenue_millions is sales.sum()
+
+  # currency=eur2k
+  measure: euro_thousands is eu_sales.sum()
+
+  # currency { scale=m suffix=finance decimals=2 }
+  measure: revenue_finance is sales.sum()  // $42.54MM
+}
+```
+
+### `# percent`
+
+Formats a numeric field as a percentage (value \* 100, adds %).
+
+**Example:**
+
+```
+measure: margin_pct is (revenue - cost) / revenue # percent
+```
+
+### `# number`
+
+Formats a numeric field. Supports **shorthand** syntax for scaling, **verbose** syntax for advanced options, and **ssf format strings** for custom formatting.
+
+#### Shorthand Syntax (Recommended)
+
+Pattern: `# number={decimals}{scale}` or `# number=auto`
+
+- `{decimals}`: Number of decimal places (0-4)
+- `{scale}`: Scale letter (`k`, `m`, `b`, `t`, `q`) - case insensitive
+
+| Tag | Output | Description |
+|-----|--------|-------------|
+| `# number=0` | 11 | 0 decimals |
+| `# number=1` | 11.2 | 1 decimal |
+| `# number=2` | 11.23 | 2 decimals |
+| `# number=0k` | 64k | thousands, 0 decimals |
+| `# number=1k` | 64.2k | thousands, 1 decimal |
+| `# number=0m` | 43m | millions, 0 decimals |
+| `# number=1m` | 42.5m | millions, 1 decimal |
+| `# number=0b` | 1b | billions, 0 decimals |
+| `# number=1t` | 1.4t | trillions, 1 decimal |
+| `# number=auto` | 1.2m | auto-scale (same as `number=big`) |
+| `# number=id` | 123456789 | identifier format (no commas) |
+
+#### Verbose Syntax (Advanced Options)
+
+For suffix format control, use verbose syntax:
+
+```malloy
+# number { scale=m decimals=2 suffix=word }      // 42.54 Million
+# number { scale=auto suffix=letter }            // 1.2M (uppercase)
+# number { scale=k suffix=none }                 // 64 (no suffix)
+```
+
+**Scale Options:** `k` (thousands), `m` (millions), `b` (billions), `t` (trillions), `q` (quadrillions), `auto`
+
+**Suffix Format Options:** Same as currency (see above)
+
+#### SSF Format String
+
+For custom formatting, use an ssf format string:
+
+```malloy
+# number="#,##0.00"    // 1,234.56
+# number="0.0%"        // percent format
+```
+
+**Example:**
+
+```malloy
+source: metrics extend {
+  # number=1m
+  measure: users_millions is users.count()
+
+  # number=auto
+  measure: auto_scaled is amount.sum()
+
+  # number { scale=m suffix=word }
+  measure: word_format is amount.sum()  // 1.2 Million
+
+  # number=id
+  measure: order_id is id.max()  // 123456789 (no commas)
+}
+```
+
+### `# duration`
+
+Formats a numeric field representing a duration into a human-readable string (e.g., "1h 2m", "30s").
+
+**Properties:**
+
+- `. [unit]`: Specifies the unit of the input number if not seconds (e.g., `nanoseconds`, `milliseconds`, `minutes`, `hours`, `days`). Default is `seconds`.
+  - Syntax: `# duration=milliseconds`
+- `.terse`\*\*: Uses abbreviated units (ns, µs, ms, s, m, h, d).
+  - Syntax: `# duration.terse` or `# duration { terse }`
+- `.number`: Apply an `ssf` format string to the numeric parts of the duration.
+  - Syntax: `# duration { number="0.0" }`
+
+**Example:**
+
+```
+measure: avg_session_time is session_length.avg() # duration=seconds
+measure: total_compute_time is compute_nanos.sum() # duration=nanoseconds terse
+```
+
+### `# image`
+
+Renders a string field value as an image (`<img>` tag). Assumes the field contains a valid image URL.
+
+**Properties:**
+
+- `.height`: Sets the image height (e.g., `40px`).
+  - Syntax: `# image { height=40px }`
+- `.width`: Sets the image width.
+  - Syntax: `# image { width=100px }`
+- `.alt`: Specifies alt text for the image.
+  - `.alt.[text]`: Sets literal alt text.
+    - Syntax: `# image { alt=Logo }`
+  - `.alt.field`: Uses the value of another field (specified by relative path like `brand_name` or `'../parent_field'`) for the alt text.
+    - Syntax: `# image { alt.field=brand_name }`
+
+**Example:**
+
+```
+dimension: product_image is image_url # image { height=50px alt.field=product_name }
+```
+
+### `# link`
+
+Renders a field value as a hyperlink (`<a>` tag).
+
+**Properties:**
+
+- `.url_template`: A template string where `$$` is replaced by the value (from this field or the `.field` property) to form the `href`. If `$$` isn't present, the value is appended.
+  - Syntax: `# link { url_template="https://example.com/products/$$" }`
+- `.field`: Use the value from a _different_ field (specified by relative path) to substitute into `url_template` or use as the `href`. The original field's value is still used as the link text.
+  - Syntax: `# link { url_template="https://.../$$" field=product_id }`
+
+**Example:**
+
+```
+dimension: product_page is product_name # link { url_template="[https://example.com/products/$$](https://example.com/products/$$)" field=product_id }
+dimension: product_id is ...
+```
+
+---
+
+## Utility Tags
+
+### `# hidden`
+
+Hides a field from being rendered in tables or dashboards, though it remains in the data.
+
+**Example:**
+
+```
+# hidden
+dimension: internal_id is id
+```
+
+### `# label`
+
+Overrides the default display name (label/title) for a field or dashboard item.
+
+**Example:**
+
+```
+# label="Total Sales ($)"
+measure: total_revenue is sales.sum()
+```
+
+### `# description`
+
+Adds a description to a field, shown as an info icon tooltip in `# big_value` cards.
+
+**Example:**
+
+```
+measure: total_revenue is sales.sum() # description="Total revenue from completed sales. Updated daily."
+```
+
+### `# break`
+
+Used within a `# dashboard` tag, applied to a `nest:`, to create a visual break (often forcing subsequent items onto a new line/section).
+
+**Example:**
+
+```
+# dashboard
+view: my_dashboard is {
+  nest: kpi1 is { ... }
+  nest: kpi2 is { ... }
+  # break // Next item will likely start on a new row
+  nest: main_chart is { ... }
+}
+```
+
+### `# tooltip`
+
+Marks a nested field/view to be included in the tooltip of its parent chart or visualization. Can also include rendering instructions for how the tooltip content itself should be rendered.
+
+**Example:**
+
+```
+view: sales_by_brand_chart is {
+  # bar_chart
+  group_by: brand
+  aggregate: total_sales
+
+// Show top 3 products in the tooltip for each brand bar
+nest: top_products is { # tooltip
+group_by: product
+aggregate: total_sales
+order_by: 2 desc
+limit: 3
+}
+
+// Show category count in tooltip, formatted as a tiny bar chart
+nest: category_breakdown is { # tooltip bar_chart.size=xs
+group_by: category
+aggregate: num_items is count()
+}
+}
+```
+
+---
+
+## Configuration Tags
+
+### `# size`
+
+_(Likely legacy, prefer `.size` property on specific renderer tags)_ Sets a preset size for some renderers (charts, tables) when applied at the view or nest level.
+
+- Values: `spark`, `xs`, `sm`, `md`, `lg`, `xl`, `2xl`.
+- Syntax: `# size=lg` (applied to a view or nest)
+
+**Example:**
+
+```
+view: big_chart is {
+  # size=lg // Apply large size to default renderer (likely table or chart)
+  ...
+}
+```
+
+### `# theme`
+
+_(Model/View Level)_ Applies theme overrides to control styling (colors, fonts, sizes). Can be applied at the model level (`## theme { ... }`) for defaults or at the view level (`# theme { ... }`) for specific overrides.
+
+**Properties:**
+
+- _(Various CSS-like properties)_ e.g., `tableBodyColor`, `tableHeaderColor`, `tableRowHeight`, `fontFamily`.
+
+**Example:**
+
+```
+## theme { tableBodyColor=blue } // Model-level default
+
+source: my_source is ... extend {
+view: my_view is {
+# theme { tableBodyColor=red } // Override for this view
+select: \*
+}
+}
+```
+
+### `# renderer_legacy`
+
+_(Model Level)_ Applied at the top of a `.malloy` file using `## renderer_legacy` to indicate that the _entire_ model should use the older HTML table/chart renderers instead of the newer web component-based renderer.
+
+**Example:**
+
+```
+## renderer_legacy
+
+source: my_source is ...
+```