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. Checkout out our deployment docs if you have not completed this step.

info

It is helpful to understand some of the key concepts in Transform framework like measures, dimensions, and identifiers before creating your frist metric. You can learn more about these concepts in our Metrics Framework 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 identifers. 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  , ds_day --time dimesions  , country -- categorical dimension  , sum(revenue_usd) --measureFROM  snowflake.prod_transactions -- sql table
  1. Set the mutablility of your data source. 
mutability:  type: immutable

This tells Transfrom 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 seperate file for metrics. The metric type 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 properites. 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 commiting it to your Transform repo

Testing and uploading your metric#

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-config 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 Catalog#

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 annotions and ask questions on this page. This is where business owners can come and interact with your Transform metrics.