Feature/scoped macros

[drewbanin]

Macros

Macros are snippets of SQL that can be called like functions in models. Macros make it possible to re-use SQL between models in keeping with the engineering principle of DRY (Don't Repeat Yourself). Moreover, packages can expose Macros that you can use in your own dbt project.

To use macros, add a macro-paths config entry to your dbt_project.yml file. Macro files must use the .sql file extension.

# dbt_project.yml
source-paths: ["models"] 
target-path: "target"
...
macro-paths: ['macros']    # look for macros in ./macros directory

Macro files can contain one or more macros. An example macro file looks like:

-- ./macros/my_macros.sql

{% macro times_two(n) %}

  {{ n }} * 2

{% endmacro %}

Here, we define a macro called times_two which takes a single argument, n. A model which uses this macro might look like:

-- models/my_model.sql

select {{ times_two(1) }}

which would be compiled to:

select 2

In the above example, we could reference the macro directly because it lives in our own project. If the macro was imported from the dbt_math_macros package via:

# dbt_project.yml
...
repositories:
  - "https://github.com/fishtown-analytics/dbt_math_macros.git"

then we would need to fully-qualify the macro:

-- models/my_model.sql

select {{ dbt_math_macros.times_two(1) }}

Here, dbt_math_macros is both the name of the repository, and the name specified in the (fictional) repo's dbt_project.yml file.