> ## 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.

# Benchmark Comparison

> Define a custom benchmark comparison option for a comparison_selector

```liquid theme={null}
{% benchmark_comparison 
    name="vs Franchisees" 
    agg="avg" 
    subject="store_id"
    where="ownership_type = 'franchise'"
/%}
```

## Examples

### Compare vs Franchisees

```liquid theme={null}
{% benchmark_comparison 
    name="vs Franchisees" 
    agg="avg" 
    subject="store_id"
    where="ownership_type = 'franchise'"
/%}
```

### Compare vs Full Network

```liquid theme={null}
{% benchmark_comparison 
    name="vs Full Network" 
    agg="avg" 
    subject="store_id"
/%}
```

### Compare vs Region Average

```liquid theme={null}
{% benchmark_comparison 
    name="vs Region Avg" 
    agg="avg" 
    subject="store_id"
    within=["region"]
/%}
```

## Attributes

<ResponseField name="name" type="string" required>
  Display name shown in the dropdown (e.g., "vs Franchisees")
</ResponseField>

<ResponseField name="agg" type="string" required>
  Aggregation function to apply across benchmark entities. Options: avg, median, min, max, sum, count, count\_distinct

  **Allowed values:**

  * `avg`
  * `median`
  * `min`
  * `max`
  * `sum`
  * `count`
  * `count_distinct`
</ResponseField>

<ResponseField name="subject" type="string" required>
  Column that defines individual entities (e.g., "store\_id", "customer\_id"). Required for benchmark calculations.
</ResponseField>

<ResponseField name="value" type="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.
</ResponseField>

<ResponseField name="where" type="string">
  SQL WHERE clause to filter which entities are included in the benchmark (e.g., "ownership\_type = 'franchise'")
</ResponseField>

<ResponseField name="within" type="array">
  Dimension columns to group the benchmark by (e.g., \["region"]). Leave empty for dataset-wide benchmark.
</ResponseField>

<ResponseField name="exclude_self" type="boolean" default="false">
  Exclude the current row from its own benchmark calculation (table context only). Default: false
</ResponseField>

<ResponseField name="display_type" type="string">
  Default display type for this comparison. Options: pct (percentage change), abs (absolute change), compared\_value (benchmark value)

  **Allowed values:**

  * `pct`
  * `abs`
  * `compared_value`
</ResponseField>

<ResponseField name="text" type="string">
  Custom comparison label text (overrides default "vs {name}")
</ResponseField>

<ResponseField name="pct_fmt" type="string">
  Format code for percentage values. See [Value Formatting](/core-concepts/value-formatting) for available formats.
</ResponseField>

<ResponseField name="abs_fmt" type="string">
  Format code for absolute values. See [Value Formatting](/core-concepts/value-formatting) for available formats.
</ResponseField>

<ResponseField name="down_is_good" type="boolean" default="false">
  If true, negative changes are shown as positive (green)
</ResponseField>

## Allowed Parents

* [comparison\_selector](/components/comparison_selector)