Examples
Basic Usage
Attributes
string
Table or view to query. Omit when using
metric.string
Semantic metric name to display, from metrics/*.yaml. Use instead of the raw data/value/x/y attributes.
string
SQL expression to insert into the SELECT part of the query (e.g., “COUNT(*)”, “SUM(sales)”). Omit when using
metric.string
CSS class to apply to the value
string
Format code for the value (e.g., “num”, “usd”, “pct”). See formatValue documentation for available formats. See Value Formatting for available formats.
string
CSS color to apply to the value (e.g., “red”, “#ff0000”, “rgb(255,0,0)”)
boolean
When true, negative values will be displayed in red (rgb(220 38 38))
string
Information tooltip text (can only be used with title)
string
URL to link the info text to (can only be used with info)
string
Create a custom link title for the info link, placed after the info text (can only be used with info_link)
options group
Comparison configuration objectExample: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 yearprior periodtargetbenchmark
- Allowed values:
- 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_valueabspct
- Allowed values:
- 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:
avgmedianminmaxsumcountcount_distinct
- Allowed values:
- 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
- agg:
- Options:
- 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
array
IDs of filters to apply to the query
number
Time in seconds between automatic data refreshes (minimum 30). Overrides the page-level auto-refresh setting for this component.
string
Custom SQL WHERE condition to apply to the query. For date filters, use date_range instead.
string
Custom SQL HAVING condition to apply to the query after GROUP BY
number
Maximum number of rows to return from the query. Note: When used with tables, limit will disable subtotals to prevent incomplete subtotal rows.
string
Column name(s) with optional direction (e.g. “column_name”, “column_name desc”)
string
Custom SQL QUALIFY condition to filter windowed results
options group
Filter data to a time period. Attributes:
date_range is an OBJECT with range (the period) and optionally date (which column to filter on when the table has more than one). Shape: date_range={ range="last 12 months" date="order_date" }. range accepts predefined values (last 7 days, month to date), dynamic patterns (Last 90 days), custom windows (2020-01-01 to 2023-03-01), or partial ranges (from 2020-01-01, until 2023-03-01). Pass a plain string for range — the whole object is NOT a string.Example:- 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:
todayyesterdaylast 7 dayslast 30 dayslast 3 monthslast 6 monthslast 12 monthsprevious weekprevious monthprevious quarterprevious yearthis weekthis monththis quarterthis yearnext weeknext monthnext quarternext yearweek to datemonth to datequarter to dateyear to dateall time
- Allowed values:
- date:
string- Date column to filter on. Required when the data has multiple date columns.
number
Set the width of this component (in percent) relative to the page width