Customizing Views
Views provide a structured way to organize and manage data, but they are also highly customizable. Within the Catalog Builder, the Schema on the right-hand side offers a range of options to edit and refine your View YAML.
These customizations allow you to improve usability, enhance data clarity, and provide stakeholders with flexible analysis options—all without writing additional SQL.
Schema
The schema displays a list of available customization options you can use in the view YAML file. We've broken these down into:
- Descriptive fields
- Source configuration
- Caching
- Fields and field formatting
Descriptive fields
See descriptive field YAML examples here.
| Field name | Description |
|---|---|
| name | The name of the view. This must be unique within the catalog. Defaults to the file name. Optional. |
| label | A user-friendly label for the view. This is what is displayed in the UI, and defaults to the name. Optional. |
| description | A description of the view. Optional. |
Source configuration
See source configuration YAML examples here.
| Field name | Description |
|---|---|
| source | This details the query or queries that need to be run in order to populate the view. |
| source.connection | The connection key to use when running the query (or null to use DuckDB). This must be a connection that is available in the catalog. |
| source.query | The SQL query to run in order to populate the view. This is defined in the dialect of the database. |
| source.dependencies | A list of cells that are dependencies of this view. Optional. |
| source.dependencies[*].name | The name of the cell. Must be unique with the dependency list. |
| source.dependencies[*].query | The SQL or Python query that is run in order to populate the cell. |
| source.dependencies[*].language | The type of the cell. This can be one of sql or python. Optional. |
| source.dependencies[*].connection | The connection key to use when running the query (or null to use DuckDB). This must be a connection that is available in the catalog. This is ignored for Python cells. Defaults to the connection of the view. Optional. |
Caching
See caching YAML examples here.
| Field name | Description |
|---|---|
| caching | Caching settings for source dependencies attached to a connection. Optional. |
| caching.duration | How long source dependency results are cached (in seconds). |
| caching.schedule | A cron expression for the source dependency refresh schedule. This value may need to be enclosed in single quotation marks. Optional. |
Fields formatting
See fields and field formatting YAML examples here.
| Field name | Description |
|---|---|
| fields | A list of fields that are available in the view. |
| fields[*].name | The name of the field. Must be unique within this view. |
| fields[*].label | A user-friendly label for the field. This is what is displayed in the UI, and defaults to the name. Optional. |
| fields[*].description | A description of the field. This is shown in the UI when the field is hovered over. Optional. |
| fields[*].expression | The SQL expression that defines the field, defined in the dialect detailed here. Defaults to the name of the field. Optional. |
| fields[*].type | The type of the field. This can be one of string, number, integer, date, or boolean. If unspecified, this defaults to string. Optional. |
| fields[*].group | Places the field within a group of this name in the UI. Optional. |
| fields[*].primary_key | Whether or not the field is a primary key. Optional. |
| fields[*].hidden | Whether or not the field is hidden. Useful for joining keys you don't want to expose in the UI. Optional. |
| fields[*].aggregates | A list of aggregates to apply to the field: count, count_distinct, sum, avg, median, mode, max, min, stddev_pop, stddev_samp, var_pop, var_samp, null (where null means no function is applied). These will appear as a collapsible group in the UI. Optional. |
| fields[*].timeframes | A list of timeframes by which to group the field: year_trunc, quarter_trunc, month_trunc, week_trunc, day_trunc, hour_trunc, minute_trunc, second_trunc, year, quarter, month, week, day_of_year, day_of_month, day_of_week, hour, minute, second, null (where null means no function is applied). These will appear as a collapsible group in the UI. Optional. |
| fields[*].format | The default format for this field when used in visualizations. Optional. |
| fields[*].format.type | The format type. This can be one of raw, currency, number, percentage, scientific, long_date, short_date, or custom_date. |
| fields[*].format.currency | Specifies the currency to use when formatting numbers as currency (e.g., USD, EUR, GBP, AUD, CAD, CHF, JPY, CNY). For a full list of currency codes see here. Optional. |
| fields[*].format.display_units | Allows display units like thousands, millions, billions, or trillions. Optional. |
| fields[*].format.negative_values | Defines the style for negative numbers, either accounting or standard. Optional. |
| fields[*].format.thousand_separator | A boolean indicating whether to use a thousand separator. Optional. |
| fields[*].format.decimals | Sets the number of decimal places for numeric values. Optional. |
| fields[*].format.prefix | Adds a prefix to the formatted value. Optional. |
| fields[*].format.suffix | Adds a suffix to the formatted value. Optional. |
| fields[*].format.year | Determines the year format, either numeric or 2-digit. Optional. |
| fields[*].format.quarter | Specifies the quarter format, which can be long, short, or numeric. Optional. |
| fields[*].format.month | Defines the format for month, options include numeric, 2-digit, long, short, or narrow. Optional. |
| fields[*].format.day | Determines the format for day, either numeric or 2-digit. Optional. |
| fields[*].format.weekday | Defines the weekday format, either long, short, or narrow. Optional. |
| fields[*].format.hour | Sets the hour format, either numeric or 2-digit. Optional. |
| fields[*].format.minute | Specifies the minute format, either numeric or 2-digit. Optional. |
| fields[*].format.second | Sets the second format, either numeric or 2-digit. Optional. |
| fields[*].format.fractional_second_digits | Specifies the number of fractional seconds (1, 2, or 3). Optional. |