Skip to main content

Metrics Config

Metric YAML​

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 (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​

Measure Proxy​

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.
metric: 
  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 
  type_params:
    measure: cancellations_usd # Specify the measure you are creating a proxy for. 
  constraint: | 
    value > 100 AND user__acquisition

Expression Metrics​

See Expression 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
metric:
  name: revenue_usd
  owners:
    - support@transformdata.io
  type: expr # Expression metrics allow you to pass in any valid SQL expression.
  type_params:
    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 
      - transaction_amount_usd
      - cancellations_usd
      - alterations_usd

Ratio Metrics​

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
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
  constraint: | # add optional constraint string. This applies to both the numerator and denominator
    is_internal = false

Cumulative Metrics​

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)
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

Further Configuration​

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​

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: cancellations_per_organic_user
locked_metadata:
  description: Locked description
  display_name: Locked display name
  tier: Locked tier
  value_format: Locked value format

Metric Tags​

Tags can help you organize and find relevant metrics to you or your teams in the Transform App. You can set tags as locked metadata in the YAML configs, or in the Transform App under metric settings. You can set one or multiple tags for each metric. Like any locked metadata in Transform, fields added in the YAML configuration are locked and cannot be changed in the user interface. Below is an example of a metric with "Finance" and "Reportin" tags tied to it.

metric:
  name: "revenue_mtd"
  description: "revenue mtd"
  owners:
    - support@transformdata.io
  type: cumulative
  locked_metadata:
    value_format: "$$,.2f"
    tags:
      - Finance
      - Reporting

Making a Metric Private under Locked Metadata​

Technical owners of the metric can set a metric as private in the locked metadata section of the metric YAML configuration file.

See the example below on how to set this option. If you don't want the metric to be private, you can simply omit this option.

  metric:
    name: revenue_mtd
    description: revenue mtd
    owners:
      - support@transformdata.io
    type: cumulative
    locked_metadata:
      value_format: "$$,.2f"
      private: true
note

You cannot change the privacy status (e.g. private or public) in the Transform App if a technical owner has set the privacy option in the locked metadata of the YAML configuration file.