Safe subtract (#748)

* Add macro definition

* Add seed file for tests

* Add integration test

* Update readme

* Update exception message

* Correct docs for safe_add and safe_subtract

Author: dchess

README.md

@@ -49,6 +49,7 @@ Check [dbt Hub](https://hub.getdbt.com/dbt-labs/dbt_utils/latest/) for the lates
   - [generate_surrogate_key](#generate_surrogate_key-source)
   - [safe_add](#safe_add-source)
   - [safe_divide](#safe_divide-source)
+  - [safe_subtract](#safe_subtract-source)
   - [pivot](#pivot-source)
   - [unpivot](#unpivot-source)
   - [width_bucket](#width_bucket-source)
@@ -1055,7 +1056,7 @@ This macro implements a cross-database way to sum nullable fields using the fiel
 **Usage:**
 
 ```
-{{ dbt_utils.safe_add('field_a', 'field_b'[,...]) }}
+{{ dbt_utils.safe_add(['field_a', 'field_b', ...]) }}
 ```
 
 #### safe_divide ([source](macros/cross_db_utils/safe_divide.sql))
@@ -1073,6 +1074,16 @@ This macro performs division but returns null if the denominator is 0.
 {{ dbt_utils.safe_divide('numerator', 'denominator') }}
 ```
 
+#### safe_subtract ([source](macros/sql/safe_subtract.sql))
+
+This macro implements a cross-database way to take the difference of nullable fields using the fields specified.
+
+**Usage:**
+
+```
+{{ dbt_utils.safe_subtract(['field_a', 'field_b', ...]) }}
+```
+
 #### pivot ([source](macros/sql/pivot.sql))
 
 This macro pivots values from rows to columns.

integration_tests/data/sql/data_safe_subtract.csv

@@ -0,0 +1,5 @@
+field_1,field_2,field_3,expected
+3,2,1,0
+4,,3,1
+,,2,-2
+,,,0

integration_tests/models/sql/schema.yml

@@ -120,6 +120,12 @@ models:
       - assert_equal:
           actual: actual
           expected: expected
+  
+  - name: test_safe_subtract
+    tests:
+      - assert_equal:
+          actual: actual
+          expected: expected
 
   - name: test_safe_divide
     tests:

integration_tests/models/sql/test_safe_subtract.sql

@@ -0,0 +1,12 @@
+
+with data as (
+
+    select * from {{ ref('data_safe_subtract') }}
+
+)
+
+select
+    {{ dbt_utils.safe_subtract(['field_1', 'field_2', 'field_3']) }} as actual,
+    expected
+
+from data

macros/sql/safe_subtract.sql

@@ -0,0 +1,28 @@
+{%- macro safe_subtract(field_list) -%}
+    {{ return(adapter.dispatch('safe_subtract', 'dbt_utils')(field_list)) }}
+{% endmacro %}
+
+{%- macro default__safe_subtract(field_list) -%}
+
+{%- if field_list is not iterable or field_list is string or field_list is mapping -%}
+
+{%- set error_message = '
+Warning: the `safe_subtract` macro takes a single list argument instead of \
+string arguments. The {}.{} model triggered this warning. \
+'.format(model.package_name, model.name) -%}
+
+{%- do exceptions.raise_compiler_error(error_message) -%}
+
+{%- endif -%}
+
+{% set fields = [] %}
+
+{%- for field in field_list -%}
+
+    {% do fields.append("coalesce(" ~ field ~ ", 0)") %}
+
+{%- endfor -%}
+
+{{ fields|join(' -\n  ') }}
+
+{%- endmacro -%}