Once data sources are defined, metrics can be created out of measures!
Metrics can be defined in the same .yaml files as your data sources, or split into separate .yaml files into any other subdirectories (provided that these subdirectories are also within the same Transform git repo directory)
Parameters that are associated with metrics include:
name: Provide the reference name for the metric. This name must be unique amongst all metrics.
owners: Define the list of Technical Owners of this metric via email. 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 here about metric ownership in Transform.
type: Define the type of metric, which can be a measure (
measure_proxy), ratio (
ratio), SQL expression (
expr), or cumulative (
constraint: For any type of metric, you may optionally include a constraint string, which applies a dimensional filter when computing the metric. You may think of this as your WHERE clause.
Example configuration YAML files for metrics
See Measure Proxy for further details.
Measure proxies are metrics that point directly to a measure (you may think of the measure proxy as a function that takes only one measure as the input).
Note that if a measure has already been defined in a data source with the
create_metric: True parameter, you do not need to re-define a metric for the measure, and you can simply use the measure itself. However, if you would like to include a constraint on top of the measure, you will need to create a measure proxy.
#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.
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.
measure: cancellations_usd # Specify the measure you are creating a proxy for.
value > 100 AND user__acquisition
See Measure Proxy Metrics for further details.
When you are building a metric that involves a SQL expression of multiple measures, you can use an expression metric.
# Expression Metric
type: expr # Expression metrics allow you to pass in any valid SQL expression.
expr: transaction_amount_usd - cancellations_usd + alterations_usd # Define the SQL expression
measures: # Define all the measures that are to be used in this expression metric
See Ratio Metrics for further details.
Ratio metrics involve a numerator measure and a denominator measure. Note that if an optional
constraint string is applied, the constraint is applied to both the numerator and denominator.
# Ratio Metric
type: ratio # Ratio metrics create a ratio out of two measures. Define the measures from the data source as numerator or denominator
constraint: | # add optional constraint string. This applies to both the numerator and denominator
is_internal = false
See Cumulative Metrics for further details.
Cumulative metrics aggregate a measure over a given window. Note that if no window is specified, the window would accumulate the measure over all time.
# Cumulative metrics aggregate a measure over a given window. The window is considered infinite if no window parameter is passed (accumulate the measure over all time)
# the default window is infinity - omitting window will accumulate the measure over all time
window: 7 days
Below are extra configurations that are available to Transform customers.
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 is displayed in the Transform UI and can include emojis 🥳
display_name: Revenue (USD) 📈
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.
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.
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.
description: Locked description
display_name: Locked display name
tier: Locked tier
value_format: Locked value format