Config Development Workflow

MetricFlow

Config Validation

When locally editing data source and metric config yamls, use the CLI command mf validate-configs to validate changes before pushing those changes and creating a pull request. The changes do not need to be committed, just saved locally. While in the repository directory, call mf validate-configs:

~/git/metrics > mf validate-configs

This will run the validate script and return any known errors or inconsistencies. When the command succeeds, you'll see messages similar to the following:

~/git/metrics > mf validate-config
• WARNING: Identifier `transaction` only found in one data source `transactions` which means it will not be used in joins.
• WARNING: Identifier `id_order` only found in one data source `transactions` which means it will not be used in joins.
• WARNING: Identifier `customer_order` only found in one data source `transactions` which means it will not be used in joins.

Testing Configs

In MetricFlow, configs can be tested by running queries. For example, you could test new_dimension dimensions using the query below if you have a revenue metric:

~/git/metrics > mf query --metrics revenue --dimensions new_dimension --limit 10

Transform

Config Validation

Similarly, in Transform, you can validate configs using the mql CLI. While in the repository directory, call mql validate-configs and reference the directory with the configs in the --config-dir string. In the example below, the repository is called metrics and the config folder is called configs:

~/git/metrics > mql validate-configs --config-dir configs

This will run the validate script and return any known errors or inconsistencies. When the command succeeds, you'll see a messages similar to the following:

~/git/metrics > mql validate-configs --config-dir configs
Successfully validated model configs for commit (da500aa4f54cbf8f3eb47a1dc2c136715c9197b9-dirty) in repo (metrics), on branch (updating-revenue-dimensions)

Testing Configs

The mql commit-configs command allows for testing your models with the CLI and Transform App. This command will upload your model to our model server so your MQL query server can use it to run queries against your data warehouse.

Testing with the CLI

After running mql commit-configs command, you can use the updated local configs to run mql query commands by "pinning" your new model. "Pinning" a model tells mql which metric model to use for future mql queries.

Navigate to the appropriate directory and run mql commit-configs with an optional reference to the config folder. This will commit the changes so that they can be pinned to use with future mql query commands. In the example below, the repository is called metrics and the config folder is called configs:

~/git/metrics >  mql commit-configs --config-dir configs
✔ 🦄 Successfully committed model id 1234 on branch updating-revenue-dimensions with commit da500aa4f54cbf8f3eb47a1dc2c136715c9197b9-dirty
Would you like to pin this this model commit for future MQL queries? [y/N]: y
Success! You can make future queries against the model id 1234.

After committing the model, there will be a prompt following the next mql query request to "pin" to this new model.

~/git/metrics > mql query --metrics revenue --dimensions new_dimension --limit 10
📌 We've found a pinned model ID from a previous request, uploaded at 2021-02-01T02:24:36.067763+00:00, which does not match the primary model for the Demo organization.
Do you want to reuse this model for this request? If not, we will default you to the current model for Slack Demo. [y/N]: y

If you answer y to the prompt, you will use the new model configs in future mql commands

You will be prompted about your pinned model each mql query until you disable it by selecting n. You can pin the model again by running mql pin-model [model-id] or by running mql commit-configs again and selecting y in response to the prompt.

A simple shortcut to the above workflow is to point at your local configs in the query. You will not be prompted to pin, and instead you will commit and use the model for that query and revert to the production configs after.

~/git/metrics > mql query --metrics revenue --dimensions new_dimension --limit 10 --config-dir configs

To check if you have a model pinned, you can use:

~/git/metrics > mql identify

You can also reset your pinned model by running:

~/git/metrics > mql unpin-model

Testing with the Transform App

After running mql commit-configs command, you'll get a link to use your model in the Transform App:

▶ mql commit-configs
✔ 🦄 Successfully committed model id 1234 on branch updating-revenue-dimensions with commit da500aa4f54cbf8f3eb47a1dc2c136715c9197b9-dirty
📌 Would you like to pin this model commit for future MQL queries? [y/N]: n
💡 Pin these configs in the future:

    mql pin-model --model-id 1234

📊 Test the model in the Transform App:

    https://app.transformdata.io/model?model-id=1234

By clicking the link or pasting it in your browser, you can access a version of the Transform App targeting the development model. The "dev mode" Transform App works exactly the same as with a production model– you can build and run queries, create and view boards, examine your model definition, etc. The only difference is you'll be using the metrics and data sources defined in your development model.

When using Transform in dev mode, you'll see a banner at the top of the window indicating that you're using a development model:

To deactivate dev mode and return to the production model, click the link at the end of the banner.

As a shortcut, running mql commit-configs with the --dev-ui flag will automatically open dev mode in a new tab of your browser.

You can share dev mode links with other users in your organization and have multiple dev mode models open at a time.

caution

Transform models share metadata for different versions of your metrics and data sources; this lets us preserve and update these entities as your model evolves over time. However, this means that metadata changes you make in dev mode will affect your production model if the entity you are editing exists in both. We will likely add more guardrails to dev mode in the future, but for now, take caution. Dev mode is best used for running queries and viewing charts only.