Skip to main content


Transform's Python Interface allows users to express MQL requests to query their metrics and dimensions in Python scripts and notebooks.


Our Python API is shipped with our command-line interface.

pip install transform

Before querying Transform, you must be authenticated by running the following on the cli:

mql setup

Examples of Querying Metrics

To pull this into a notebook or Python script, you can run the following, which shows an example of querying a metric called products with dimensions ds, and a where constraint.

from transform import mql
df = mql.query(metrics=["products"], dimensions=["ds"], where="is_active")
metric_time products
0 2022-03-24 00:00:00+00:00 23
1 2022-07-28 00:00:00+00:00 16
2 2022-06-12 00:00:00+00:00 21
3 2022-03-22 00:00:00+00:00 20
4 2022-06-24 00:00:00+00:00 20

You can optionally instantiate the object manually. This will allow you to pass an API key and authenticate, and you should use this mechanism if you are not already authenticated.

# Instantiating the object manually
from transform.mql import MQLClient

- api_key if you want to manually provide an api_key
- mql_server_url if you want to override the mql server

DEFAULT: values in ~/.transform/config.yml
mql = MQLClient(api_key: Optional[str], mql_server_url: Optional[str])

df = mql.query(metrics=["messages"], dimensions=["ds"], where="is_thread")

Python Interface Functions

The interface supports most commands that Tranform's MQL CLI supports.

Optional: if you instantiated the MQL client manually, you could declare it as a variable called mql such that mql = MQLClient().