Customizing views

Encode your data's representation in views.

Customizing views in Count Metrics

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.

Click here to see a full breakdown of schema details

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 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 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 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[*].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. 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.

---

Key customization options

Field labels & groups

You can customize the label for your fields to determine how they appear in the UI. By default, the label is set to the field name, but you can update it for improved readability, making it clearer and more user-friendly. Optionally add a group label to place the field within an expandable group of fields.

fields:
  - name: order_total
    label: Total Order Value
    group: Order metrics

Field descriptions

Adding descriptions to fields helps stakeholders understand what each field represents. These descriptions appear when users hover over a field in the UI, offering helpful context that ensures that even non-technical users can easily interpret the data.

fields:
  - name: customer_id
    description: A unique identifier assigned to each customer.

Timeframes: Flexible date breakouts

For date fields, you can provide multiple timeframe options directly within the View YAML. Instead of requiring stakeholders to manipulate dates manually, you can pre-define useful breakouts like year, month, or day.

fields:
  - name: order_date
    type: date
    timeframes: [year_trunc, quarter_trunc, month_trunc, week_trunc, day_trunc]

Aggregates: Pre-defined calculations

Instead of requiring users to write manual calculations every time, you can define a set of aggregations directly within your View YAML. This allows stakeholders to choose from multiple summary options—like sum, average, or count—with just a click.

fields:
  - name: number_of_employees
    type: integer
    aggregates: [sum, min, max, avg, count]

Expressions: Creating custom calculated fields

In addition to predefined fields, you can create custom calculated fields using the expression option. This allows you to define new fields based on existing ones, without modifying the original dataset.

fields:
  - name: events_per_user
    expression: count(distinct event_id) / count (distinct user_id)
    type: number