arguments

macros/<filename>.yml

version: 2

macros:
  - name: <macro name>
    arguments:
      - name: <arg name>
        type: <string>
        description: <markdown_string>

Definition

The arguments property is used to define the parameters that a macro can accept. Each argument can have a name, type, and description. You can add arguments to a macro property, which helps in documenting the macro and understanding what inputs it requires.

You can validate your macro arguments using the validate_macro_args flag:

• If the flag is set to False (default), dbt will continue to permit any value for type and name.
• If flag is set to True (opt-in), dbt will raise a warning if the argument names you've added in YAML don't match the argument names you have in your macro or if the argument types aren't valid according to the supported types. Additionally, if no argument names are documented in YAML, dbt will infer them based on what you have in the macro and include them in the manifest.json file.

type

tip

From dbt Core v1.10, you can opt into validating the arguments you define in macro documentation using the validate_macro_args behavior change flag. When enabled, dbt will:

• Warn if documented argument names don’t match the macro definition.
• Warn if type fields don’t follow supported formats.

Learn more about macro argument validation.

macros/<filename>.yml

version: 2

macros:
  - name: <macro name>
    arguments:
      - name: <arg name>
        type: <string>

Supported types

From dbt Core v1.10, when you use the validate_macro_args flag, dbt supports the following types for macro arguments:

• string or str
• boolean or bool
• integer or int
• float
• any
• list[<Type>], for example, list[string]
• dict[<Type>, <Type>], for example, dict[str, list[int]]
• optional[<Type>], for example, optional[integer]
• relation
• column

Note that the types follow a Python-like style but are used for documentation and validation only. They are not Python types.

Examples

macros/cents_to_dollars.sql

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

macros/cents_to_dollars.yml

version: 2

macros:
  - name: cents_to_dollars
    arguments:
      - name: column_name
        type: column
        description: "The name of a column"
      - name: scale
        type: integer
        description: "The number of decimal places to round to. Default is 2."