Type Annotations for Jinja Macros

[peterallenwebb]

This holiday season, the Core Team is working to improve the experience of working with jinja macros in dbt. Specifically, we want to provide folks with better guardrails (more rigorous development / validation) for their dbt macros - to improve stability and usability.

As a first step, we are adding experimental type annotations to jinja macro parameters. Our type system will feel familiar, since the syntax is the same as Python and the available types are a subset of Python types, but it will start out much simpler. Like type annotations in Python, ours will have no effect at runtime, but will be checked and enforced before execution when you invoke dbt with the --type-check flag. By using this flag, you can create a reassuring quality gate, not unlike checking Python code with mypy before you run it.

Here's a quick sample of what a typed macro might look like:

{% macro cents_to_dollars(column_name: str, scale: int = 2) %}
	({{ column_name }} / 100)::numeric(16, {{ scale }})
{% endmacro %}

Note that there is not yet support for return value types, since return values are a more nebulous concept for macros than for Python functions. We're thinking about this and invite suggestions.

Typed macros will benefit for a wide variety of people in the dbt-core ecosystem, including end users, package maintainers, adapter maintainers, and dbt-core contributors. End users will benefit from faster development and debugging, as they identify bugs earlier, and are alerted when they are using macros in an unintended way which might break later. Everyone will benefit from the clearer interfaces and better documentation expressed by types, which we think will be especially important as dbt projects continue to grow and change over time.