Skip to main content

Creating Your First Metric

This is a short guide on how to create your first metric with Transform. This guide is for new users and assumes that you have Transform set up and deployed. Check out our deployment docs if you have not completed this step.

info

It is helpful to understand some key concepts in MetricFlow like measures, dimensions, and identifiers before creating your first metric. You can learn more about these concepts in our MetricFlow Guide

Create your Data Source​

Conceptually, there are two main objects in Transform, Data Sources and Metrics. This step shows you how to set up your Data Sources. Data Sources are made up of identifiers, dimensions and measures.

  1. Name your data source, fill in appropriate metadata and map it to a table in your warehouse. You can also specify a custom query instead of a table by using the sql_query field.
data_source:
  name: transactions
  description: |
    This table captures every transaction starting July 02, 2014. Each row represents one transaction
  owners:
    - support@transformdata.io
  sql_table: snowflake.prod_transactions.
  1. Define your identifiers. These are the keys in your table that Transform will use to join to other data sources. These are usually columns like customer_id, transaction_id, etc.
  identifiers:
    - name: transaction
      type: primary
      expr: id_transaction
    - name: customer
      type: foreign
      expr: id_customer
  1. Define your dimensions and measures. Dimensions are properties of the records in your table that are non-aggregatable. They provide categorical or time-based context to enrich metrics. Measures are the building block for creating metrics. They are the numerical columns that Transform will perform some aggregate function on.
measures:
    - name: transaction_amount_usd
      description: The total USD value of the transaction.
      agg: sum
  dimensions:
    - name: is_large
      type: categorical
      expr: CASE WHEN transaction_amount_usd >= 30 THEN TRUE ELSE FALSE END
tip

A useful mental model for people used to writing SQL is to think of dimensions as the columns you would group by and measures as the columns you would aggregate.

SELECT
  , metric_time_day --time dimensions
  , country -- categorical dimension
  , sum(revenue_usd) --measure
FROM
  snowflake.prod_transactions -- sql table
  1. Set the mutability of your data source.
mutability:
  type: immutable

This tells Transform how often the underlying data changes. You can learn more about the different mutability options here

Create your metric​

Now that you've created your first data source, let's define your first metric. You can add your metric to the same yaml file, or create a separate file for metrics. The metric types Transform supports are measure proxy, ratio, expression, and cumulative.

This example metric is a measure proxy, it is generated from the measure transaction_amount_usd without any additional properties. This will be implemented as a sum() function in the generated SQL.

---
metric:
  name: transaction_amount_usd
  type: measure_proxy
  type_params:
    measure: transaction_amount_usd

You can interact and test your metric through the CLI before committing it to your Transform repository

Testing and uploading your metric (MetricFlow)​

To test your metric

  1. Make sure you have the metricflow CLI package installed. Run mf version to see your CLI version. If you do not have the CLI installed run pip install --upgrade metricflow
  2. Save your files and run mf validate-configs to validate the changes before committing them
  3. If your validation passes, run mf commit-configs and pin the model to use your local changes
  4. Run mf query --metrics <metric_name> --dimensions <dimension_name> to query the metrics and dimensions you want to see in the CLI.
  5. Once you've verified that the metric is correct, commit your changes and push them up to your git repo.

Testing and uploading your metric (Transform)​

To test your metric

  1. Make sure you have the transform CLI package installed. Run mql version to see your CLI version. If you do not have the CLI installed run pip install --upgrade transform
  2. Save your files and run mql validate-configs to validate the changes before committing them
  3. If your validation passes, run mql commit-configs and pin the model to have your MQL server use your local changes
  4. Run mql query --metrics <metric_name> --dimensions <dimension_name> to query the metrics and dimensions you want to see in the CLI.
  5. Once you've verified that the metric is correct, commit your changes and push them up to your git repo.

View your metrics in the Transform App​

Your metrics should now be live! Log into Transform and search for the metric you just created. As the metric owner, you can configure additional details about the metric like a description, tier and what an increase in this metric means.

You can also add annotations and ask questions on this page. This is where business owners can come and interact with your Transform metrics.