Macro Type Documentation (arguments)

[peterallenwebb]

Type Checking

We support documenting macros in yml files. Here is the standard example:

version: 2

macros:
  - name: cents_to_dollars
    description: A macro to convert cents to dollars
    arguments:
      - name: column_name
        type: string
        description: The name of the column you want to convert
      - name: precision
        type: integer
        description: Number of decimal places. Defaults to 2.

Note the type field, which is currently unvalidated and used only for the purpose of documentation. We will provide opt-in validation and functionality for this field.

The type field will now support any value given by the following rule.

<T> := 
    str
    string
    bool
    int
    integer
    float
    Any
    List[<T>]
    Dict[<T>, <T>]
    Optional[<T>]
    Relation
    Column

So, str, bool, List[str], and Dict[str, List[int]], would all be valid types. Although this naming convention follows Python style conventions, these types should not be confused with Python types. Note that string is a synonym for str and integer is a synonym for int. This flexibility will allow users to avoid revising existing documentation which may have used older, inconsistent conventions.

The type field is not currently validated, and we will continue to permit any value, unless --type-check flag is used. In that case, type names not explicitly allowed by the rule above will generate an error, and dbt will perform basic static type checking when the marco is called in order to detect coding errors.

SQL Syntax Hints

We will add another type to indicate a string is a specific SQL syntax. For example,

      - name: column_name
        type: string[ColumnName]
        description: The name of the column you want to convert

Other supported values supported in v1 will be string[Expr] (general expression) string[Cond] (general condition) or string[SqlExpr] (indicating that the expression should be valid SQL but is otherwise unrestricted).

Changes to the Manifest

The type field should be included in the manifest so that downstream systems can use type information to support new features.