Skip to main content

Metrics Config

Metric YAML

Once data sources are defined, metrics can be created out of the measures!

You can put the metrics in the same .yaml files as the data sources, or split them apart into any sub-directories, as long as those sub-directories are in the same Transform Git directory.

Example

Comments provide descriptions of the YAML fields. See a field-by-field breakdown with different examples below.

---
#Measure Proxy - if you've defined the metrics with the create_metric: true parameter passed, you don't need to create measure proxies unless you want to include a constraint.
metric: # This section includes metadata on metrics.
name: cancellations # Define the reference name of the metric. This name must be unique amongst metrics and can include lowercase letters, numbers and underscores.
# This name is used to call the metric from the Transform API.
owners: # Define the list of owners of this metric. This owner is displayed in the “ownership” features of the UI and connects to the user’s Transform login.
# For now, this should be the user’s email address.
- support@transformdata.io
type: measure_proxy # Measure_proxies are pointers to a measure you created in a data source
type_params:
measure: cancellations_usd # The measure you are creating a proxy of.
---
# Ratio Metric
metric:
name: cancellation_rate
owners:
- support@transformdata.io
type: ratio # Ratio metrics create a ratio out of two measures. Define the measures from the data source as numerator or denominator
type_params:
numerator: cancellations_usd
denominator: transaction_amount_usd
---
# Expression Metric
metric:
name: revenue_usd
owners:
- support@transformdata.io
type: expr # Expression metrics allow you to pass in any valid SQL expression. Define all of the measures used in the metric in the "measures" field.
type_params:
expr: transaction_amount_usd - cancellations_usd + alterations_usd
measures:
- transaction_amount_usd
- cancellations_usd
- alterations_usd
---
# Cumulative metrics aggregate a measure over a given window. The he window is considered infinite if no window parameter is passed
metric:
name: wau_rolling_7
owners:
- support@transformdata.io
type: cumulative
type_params:
measures:
- distinct_users
# the default window is infinity - omitting window will accumulate the measure over all time
window: 7 days
---
# Metric with a constraint (Think of this like a 'where' clause)
metric:
name: cancelations_per_organic_user
type: measure_proxy
type_params:
measure: cancellations_usd
constraint: |
user__aquisition_source = "organic"

Metric Metadata

This section explains the available metadata you can configure for you metrics.

Name

Define the reference name of the metric. This name must be unique amongst metrics and can include lowercase letters, numbers and underscores. This name is used to call the metric from the Transform API.

Owners

Define the list of Technical Owners of this metric. This should be the email addresses of registered Transform users. Technical Owners will be displayed as “Technical Owners” in the UI and are responsible for the config files which define metrics.

Business Owners can be added (and removed) in the UI by Technical Owners and Organization Admins. However, technical ownership can only be edited in the config files. Teams of people can be added as Business Owners in the UI, as well.

Learn more about metric ownership in Transform [https://docs.transform.co/docs/catalog/govern/ownership].

Example:

owners:
- support@transformdata.io

Type and Type Params

Define the metric type - a pointer to a measure (measure_proxy), a ratio metric (ratio), or a SQL expression (expr). Depending on the type, include the appropriate type_params. For measure_proxy, the only necessary parameter is measures (this may be obvious, but you should only have a single measure for a "measure_proxy" metric). For ratio, include the numerator and the denominator. For expr metrics, include the expression as well as a list of the measures used in the expression.

Examples:

type: measure_proxy
type_params:
measures:
- cancellations_usd

OR

type: ratio
type_params:
numerator: cancellations_usd
denominator: transaction_amount_usd

OR

type: expr
type_params:
expr: transaction_amount_usd - cancellations_usd + alterations_usd
measures:
- transaction_amount_usd
- cancellations_usd
- alterations_usd

Constraint (optional)

For any metric optionally include a constraint string which applies a dimensional filter when computing the metric

# high value cancellations for organic users
type: measure_proxy
type_params:
measures:
- cancellations_usd
constraint: |
value > 100 AND user__aquisition_source = "organic"

Further Configuration:

Once a metric is successfully committed to the git repo, the owners listed in the config file should be able to see a pop up window when opening the Transform UI (https://app.transformdata.io/). The pop up window will guide you to further configure the metric and its metadata, to improve the user experience for anyone consuming the metric through the Transform UI. The fields include:

Display Name

Display name is displayed in the Transform UI and can include emojis 🥳

Example:

display_name: Revenue (USD) 📈

Description

Provide a detailed description of the metric. This description is surfaced in the main “definition” section of the metric page using rich markdown formatting in the Transform UI.

Tier (optional)

The tier is shown in the Transform UI on the metric page. A tier reflects different levels of hierarchy amongst metrics in Transform, with Tier 1 being the highest and Tier 3 being the lowest.

Value Format

The value format is used to properly render the value of the metrics in the Transform UI. We provide several common value formats for users to choose from (e.g., Currency, Decimal, Fixed-point, and Percent).

Increase Is Good

We want to provide users more semantic meaning when the chart value is going up or down. Users now can specify if the value increase is good or bad, and it will be used to render changes in metric value as good or bad, and associated with appropriate indicators such as arrows or colors.

Note: In some rare situations, the users may want to disable the function of directly editing these fields in the UI. In this case, these fields can be also specified in the config file under locked_metadata section. By doing this, the fields specified in the config file will be read-only in the UI.

metric:
name: cancelations_per_organic_user
locked_metadata:
description: Locked description
display_name: Locked display name
tier: Locked tier
value_format: Locked value format