Skip to main content

Getting Started

After you define important metrics in MetricFlow, you can easily query metrics and test configurations using our command-line interface that executes MQL requests (MetricFlow Query Language).


  1. Run pip install transform in your terminal (pip3 if you're on Python 3).
  2. Create an API key in the Transform user interface or use an existing API key that you've saved (under Settings).
  3. Run mql setup -k <your api key>
  4. Upon success, you should receive a message indicating that you're ready to query metrics from your organization!

CLI Usage

Run help to see all commands.

mql --help

Note: See mql query for reference on how to query metrics and mql materialize for reference on how to materialize metrics.

Examples - Informational Commands


Use MQL identify to confirm what organization you're querying. This is useful if you have multiple Transform organizations.

mql identify

Expected Output

You are authenticated as Roy Kent within the AFC Richmond organization using model at transform/master:b3d5fcf682418cba3c8c12c22
Your MQL server is

List Metrics

List Metrics will provide all metrics in your Transform organization as well as a set of corresponding dimensions. Use the show-all-dims argument to get a full list of dimensions

mql list-metrics --show-all-dims

Expected Output A list of metrics with all dimensions associated with them

goal_differential_average: ds, federations__team
count_corner_kicks: ds, players__player_name

List Servers

List servers will list all MQL servers for your Transform Data Organization.

mql list-servers
🖨  We've found 1 MQL servers for the AFC Richmond organization. ⭐️ - Primary.
• ⭐️ primary:

List Queries

This command will provide JSON output of queries that have recently run on the MQL server.

mql list-queries

Expected Output

Example query JSON

{'queries': [{'id': '1632375498179_0000012', 'modelKey': {'branch': 'master', 'commit': 'b3d5fcf682418cba3c8c12c2278de513d6f7dbc1'}, 'metrics': ['goal_differential_average'], 'dimensions': ['ds'], 'status': 'SUCCESSFUL'}]},

List Materializations

This command will show all materializations defined in your organization

mql list-materializations

Expected Output

The materialization name metrics, dimensions, and associated destination of your materialization

• goal_differential_average_by_dimensions:
Metrics: goal_differential_average
Dimensions: ds, federation__team_name
destination table: goal_differential_by_ds_and_team


Show the current version of the MQL CLI.

mql version

Examples - Configuration Development

Pin and Unpin

Pin a model id from configs that are already committed to the MQL Server to use for querying

mql pin-model --model-id 1000

Unpin a model will unpin the currently pin model

mql unpin-model

Validate Configs

mql validate-configs /a/path/to/configs

Expected Output

If successful, you should receive the following output with additional information on your model:

🎉 Successfully validated configs for commit

Commit Configs

Commit Configurations to your Transform model. Optionally pin the model for local querying

mql commit-configs --config-dir /a/path/to/configs --pin true

Expected Output

✔ 🦄 Successfully committed configs id 1000 on branch led_tasso with commit 8374837843

Examples - Debugging

Health Report

MQL health report returns the health of the MQL server that you are querying. This will provide any errors or issues with your setup.

mql health-report

Expected Output

Checkboxes next to all MQL server ensuring health

🏥 Health Report for MQL Servers at AFC Richmond
• primary: running commit 79c1f99fe774b8817190fb2c89a5f34289b5ef9f
• ✅ snowflake No Errors


Ping the MQL server to make sure it's alive

mql ping

Expected Output A ping and confirmation that ping indicates a healthy response

 Received HTTP 200 code from MQL in 0.1656 seconds.
Healthily running commit: 79c1f99fe774b8817190fb2c89a5f

Stream Query Logs

You may be prompted to run Stream Query Logs after an error. Stream Query logs takes an ID argument.

mql stream-query-logs --query-id 100000

Expected Output

A log containing information on execution, errors, and other information from start to finish of the query. An example snippet is provided below.

[INFO][2021-09-23 16:50:41,626]: query: [SELECT annotations_created AS annotations_created , groupby_unalias_8d21d772.ds ...]
[INFO][2021-09-23 16:50:42,884]: query execution done
[INFO][2021-09-23 16:50:42,885]: fetching data done
[INFO][2021-09-23 16:50:42,888]: query: [ROLLBACK]
[INFO][2021-09-23 16:50:42,938]: query execution done
[INFO][2021-09-23 16:50:42,939]: Query took 1.31 seconds. Result contains 81 row(s)
[INFO][2021-09-23 16:50:42,947]: Query ID: 1632375498179_0000016 - Successful.

Drop Cache

Drop Cache should only be run if there is a corruption issue.

mql drop-cache --f