> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evidence.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Measure

> Add a measure to a table, including comparisons, sparklines, and more

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure value="sum(total_sales)" fmt="usd1m" /%}
    {% measure value="sum(quantity)" fmt="num0" /%}
{% /table %}
```

## Examples

### Table with Measures

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure value="sum(total_sales)" fmt="usd1m" /%}
    {% measure value="sum(quantity)" fmt="num0" /%}
{% /table %}
```

### Date Range Filtering

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        date_range={
            range="last 12 months"
            date="date"
        }
        fmt="usd1m"
    /%}
    {% measure
        value="sum(total_sales)"
        date_range={
            range="last 6 months"
            date="date"
        }
        fmt="usd1m"
    /%}
{% /table %}
```

### Prior Year Comparison

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        date_range={
            range="last 12 months"
            date="date"
        }
        comparison={
            compare_vs="prior year"
        }
    /%}
{% /table %}
```

### Calculated Measures

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales) / sum(transactions) as avg_price" 
        fmt="usd2"
    /%}
{% /table %}
```

### Viz: Color Scale

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        viz="color"
    /%}
{% /table %}
```

### Viz: Color Scale with Custom Colors

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        viz="color"
        color_options={
            color_scale=["#c0392b","#f4f4f4","#27ae60"]
        }
    /%}
{% /table %}
```

### Viz: Color Scale with Pinned Values

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd"
        viz="color"
        color_options={
            color_stops=[
                { value=5000 color="#e74c3c" },
                { value=10000 color="#f39c12" },
                { value=15000 color="#27ae60" }
            ]
        }
    /%}
{% /table %}
```

### Viz: Color with Conditional Colors

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        viz="color"
        color_options={
            conditional_colors="case when sum(total_sales) > 10000 then '#22c55e' when sum(total_sales) > 5000 then '#f59e0b' else '#ef4444' end"
        }
    /%}
{% /table %}
```

### Viz: Bar

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        viz="bar"
    /%}
{% /table %}
```

### Viz: Bar with Custom Colors

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        viz="bar"
        bar_options={
            bar_color="#2c7d00"
        }
    /%}
    {% measure
        value="sum(transactions)"
        viz="bar"
        bar_options={
            bar_color="#339e9c"
        }
    /%}
{% /table %}
```

### Viz: Delta

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        date_range={
            range="last 12 months"
            date="date"
        }
        comparison={
            compare_vs="prior year"
        }
        viz="delta"
    /%}
{% /table %}
```

### Viz: Sparkline

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        viz="sparkline"
        sparkline_options={
            x="date"
            type="area"
        }
    /%}
{% /table %}
```

### Column Info

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        info="Includes all product sales"
    /%}
{% /table %}
```

### Sorting

```liquid theme={null}
{% table data="demo.daily_orders" %}
    {% dimension value="category" /%}
    {% measure
        value="sum(total_sales)"
        fmt="usd1m"
        viz="color"
        sort="asc"
    /%}
{% /table %}
```

## Attributes

<ResponseField name="value" type="string" required />

<ResponseField name="fmt" type="string">
  Format for values. Can be a built-in format or a custom Excel-style format code. See [Value Formatting](/core-concepts/value-formatting) for available formats.
</ResponseField>

<ResponseField name="fmt_column" type="string">
  Column of format codes used to format values. The format code is pulled from this column for each row in the table.
</ResponseField>

<ResponseField name="viz" type="string">
  Visualization to show for this measure, including sparklines, bars, colors, and deltas.

  **Allowed values:**

  * `bar`
  * `color`
  * `delta`
  * `sparkline`
</ResponseField>

<ResponseField name="delta_options" type="options group">
  Delta visualization configuration. When present, enables delta visualization.

  **Example:**

  ```
  delta_options={
    down_is_good = true
    show_symbol = true
    symbol_position = "left"
    neutral_range = []
  }
  ```

  **Attributes:**

  * down\_is\_good: `boolean` - Whether a downward trend is considered positive
  * show\_symbol: `boolean` - Whether to show the delta symbol
  * symbol\_position: `string` - Position of the delta symbol relative to the value
    * **Allowed values:**
      * `left`
      * `right`
  * neutral\_range: `array` - Range \[min, max] for neutral values. Use null for infinity (e.g., \[null, 0] means anything ≤ 0 is neutral)
</ResponseField>

<ResponseField name="sparkline_options" type="options group">
  Sparkline visualization configuration. When present, enables sparkline visualization.

  **Example:**

  ```
  sparkline_options={
    type = "line"
    x = "string"
    color = "string"
    fit_to_data = true
    date_grain = "year"
    date_range = {
      range = "last 7 days"
      date = "order_date"
    }
  }
  ```

  **Attributes:**

  * type: `string`
    * **Allowed values:**
      * `line`
      * `area`
      * `bar`
  * x: `string` - X-axis column (time/category column for sparkline) - required when viz type is sparkline
  * color: `string` - Color for the sparkline
  * fit\_to\_data: `boolean` - Whether to scale the y-axis to the data range
  * date\_grain: `string` - Date granularity for sparkline time series
    * **Allowed values:**
      * `year`
      * `quarter`
      * `month`
      * `week`
      * `day`
      * `hour`
      * `minute`
      * `second`
  * date\_range: `options group` - Date range configuration object with period, end, and date properties
    * **Options:**
      * range: `string` - Time period to filter. Use presets like 'last 7 days', dynamic patterns like 'Last 90 days', custom ranges like '2020-01-01 to 2023-03-01', or partial ranges like 'from 2020-01-01'.
        * **Allowed values:**
          * `today`
          * `yesterday`
          * `last 7 days`
          * `last 30 days`
          * `last 3 months`
          * `last 6 months`
          * `last 12 months`
          * `previous week`
          * `previous month`
          * `previous quarter`
          * `previous year`
          * `this week`
          * `this month`
          * `this quarter`
          * `this year`
          * `next week`
          * `next month`
          * `next quarter`
          * `next year`
          * `week to date`
          * `month to date`
          * `quarter to date`
          * `year to date`
          * `all time`
      * date: `string` - Date column to filter on. Required when the data has multiple date columns.
</ResponseField>

<ResponseField name="bar_options" type="options group">
  Bar visualization configuration. When present, enables bar visualization.

  **Attributes:**

  * bar\_color: `string` - Custom color for positive values. If not specified, uses default blue.
  * bar\_color\_negative: `string` - Custom color for negative values. If not specified, uses bar\_color if set, otherwise default red.
  * hide\_labels: `boolean` - When true, hides the text values and shows only the bar visualization.
  * fit\_to\_data: `boolean` - When true, scales bars to the data range instead of including zero. This makes bars use the full available width when all values are far from zero.
</ResponseField>

<ResponseField name="color_options" type="options group">
  Color scale visualization configuration. When present, enables color visualization.

  **Example:**

  ```
  color_options={
    color_scale = ["value1", "value2"]
    color_stops = []
    conditional_colors = "string"
    scale_column = "string"
    scale_mode = "individual"
  }
  ```

  **Attributes:**

  * color\_scale: `array of strings` - Custom color scale for type="color". Must be an array of colors (e.g., \["#ff0000", "#00ff00", "#0000ff"]).
  * color\_stops: `array` - Pin specific data values to specific colors for viz="color". Values beyond the first/last stop are clamped to the end colors. Takes precedence over color\_scale.
  * conditional\_colors: `string` - SQL expression that returns color values for each row. When specified, bypasses color\_scale and uses explicit colors (e.g., "case when sum(sales) > 1000 then '#22c55e' else '#ef4444' end").
  * scale\_column: `string` - Column or SQL expression to use for color scale calculations when type="color". Supports: simple columns (e.g., "sc"), aggregated columns (e.g., "sum(sc)"), or expressions (e.g., "case when sales > 100 then 1 else 0 end"). If not specified, the measure column itself is used for scaling.
  * scale\_mode: `string` - How to calculate min/max for color and bar visualizations. "individual" calculates range per column (default), "shared" calculates range across all related columns.
    * **Allowed values:**
      * `individual`
      * `shared`
</ResponseField>

<ResponseField name="viz_include_subtotals" type="boolean" default="false">
  Whether to apply visualizations (like color and bar charts) to subtotal rows. When false, subtotal rows will not have visualizations applied.
</ResponseField>

<ResponseField name="red_negatives" type="boolean" default="false">
  When true, negative values will be displayed in red (rgb(220 38 38))
</ResponseField>

<ResponseField name="title" type="string" />

<ResponseField name="align" type="string">
  **Allowed values:**

  * `left`
  * `center`
  * `right`
</ResponseField>

<ResponseField name="info" type="string" />

<ResponseField name="info_link" type="string">
  URL to link the info text to (can only be used with info)
</ResponseField>

<ResponseField name="info_link_title" type="string">
  Create a custom link title for the info link, placed after the info text (can only be used with info\_link)
</ResponseField>

<ResponseField name="hide" type="boolean" default="false">
  Whether to hide this column from the table display. Hidden columns are still included in queries and can be referenced by other columns.
</ResponseField>

<ResponseField name="sort" type="string">
  Sort direction for this measure column. When specified, the table will be sorted by this column.

  **Allowed values:**

  * `asc`
  * `desc`
</ResponseField>

<ResponseField name="column_group" type="string">
  Group name for this column. Columns with matching group names will be visually grouped under a shared header.
</ResponseField>

<ResponseField name="comparison" type="options group">
  Comparison configuration object

  **Example:**

  ```
  comparison={
    compare_vs = "prior year"
    display_type = "compared_value"
    target = "string"
    benchmark = {
      agg = "avg"
      subject = "store_name"
      within = ["region"]
    }
    hide_pct = true
    pct_fmt = "string"
    abs_fmt = "string"
  }
  ```

  **Attributes:**

  * compare\_vs: `string` - Type of comparison to perform. Options: prior year (same period last year), prior period (previous period of same duration), target (compare against a target value), benchmark (compare against group average/aggregate)
    * **Allowed values:**
      * `prior year`
      * `prior period`
      * `target`
      * `benchmark`
  * display\_type: `string` - What to display for comparison. Options: compared\_value (comparison period value), abs (absolute change), pct (percentage change). Default: pct
    * **Allowed values:**
      * `compared_value`
      * `abs`
      * `pct`
  * target: `string` - Target value for target comparison. Can be a column name, aggregation (e.g., "sum(target\_sales)"), or literal value.
  * benchmark: `options group`
    * **Options:**
      * agg: `string` - Aggregation function to apply across benchmark group. Options: avg (average), median, min, max, sum, count, count\_distinct
        * **Allowed values:**
          * `avg`
          * `median`
          * `min`
          * `max`
          * `sum`
          * `count`
          * `count_distinct`
      * subject: `string` - Column or expression that defines individual entities in the benchmark (e.g., "store\_name", "customer\_id"). Required for single-value components.
      * value: `string` - Optional column or expression to use for benchmark calculation. If not specified, uses the main value column. Useful if you have a pre-aggregated benchmark table for RLS reasons.
      * within: `array of strings` - Dimension columns to group the benchmark by (e.g., \["region"]). Leave empty for dataset-wide benchmark.
      * where: `string` - SQL WHERE clause to filter which entities are included in the benchmark
      * exclude\_self: `boolean` - Exclude the current row from its own benchmark calculation (table context only). Default: false
  * hide\_pct: `boolean` - Hide the percentage change line in comparison tooltips
  * pct\_fmt: `string` - Format code for percentage values in comparison tooltips
  * abs\_fmt: `string` - Format code for absolute values in comparison tooltips
</ResponseField>

<ResponseField name="hide_column_totals" type="boolean">
  Whether to hide this measure in column total/subtotal calculations. When undefined, auto-detection determines if totals should be hidden based on temporal comparison context.
</ResponseField>

<ResponseField name="hide_row_totals" type="boolean">
  Whether to hide this measure in row total/subtotal calculations. When undefined, auto-detection determines if totals should be hidden based on temporal comparison context.
</ResponseField>

<ResponseField name="date_range" type="options group">
  Use date\_range to filter data for specific time periods. Accepts predefined ranges (e.g., "last 12 months"), dynamic ranges (e.g., "Last 90 days"), custom date ranges (e.g., "2020-01-01 to 2023-03-01"), or partial ranges (e.g., "from 2020-01-01", "until 2023-03-01")

  **Example:**

  ```
  date_range={
    range = "today"
    date = "string"
  }
  ```

  **Attributes:**

  * range: `string` - Time period to filter. Use presets like 'last 7 days', dynamic patterns like 'Last 90 days', custom ranges like '2020-01-01 to 2023-03-01', or partial ranges like 'from 2020-01-01'.
    * **Allowed values:**
      * `today`
      * `yesterday`
      * `last 7 days`
      * `last 30 days`
      * `last 3 months`
      * `last 6 months`
      * `last 12 months`
      * `previous week`
      * `previous month`
      * `previous quarter`
      * `previous year`
      * `this week`
      * `this month`
      * `this quarter`
      * `this year`
      * `next week`
      * `next month`
      * `next quarter`
      * `next year`
      * `week to date`
      * `month to date`
      * `quarter to date`
      * `year to date`
      * `all time`
  * date: `string` - Date column to filter on. Required when the data has multiple date columns.
</ResponseField>

## Allowed Parents

* [table](/components/table)