docs/passthrough-explanation

CHANGELOG.md

@@ -1,3 +1,9 @@
+# dbt_salesforce_source version.version
+
+## Documentation
+- Minor README updates
+- Updated macro comments to provide clearer and more detailed explanations of the workflow.
+
 # dbt_salesforce_source v1.1.0
 [PR #48](https://github.com/fivetran/dbt_salesforce_source/pull/48) includes the following updates:
 

README.md

@@ -1,4 +1,6 @@
-<p align="center">
+# Salesforce Source dbt Package ([Docs](https://fivetran.github.io/dbt_salesforce_source/))
+
+<p align="left">
     <a alt="License"
         href="https://github.com/fivetran/dbt_salesforce_source/blob/main/LICENSE">
         <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" /></a>
@@ -13,7 +15,6 @@
         <img src="https://img.shields.io/badge/Fivetran_Quickstart_Compatible%3F-yes-green.svg" /></a>
 </p>
 
-# Salesforce Source dbt Package ([Docs](https://fivetran.github.io/dbt_salesforce_source/))
 ## What does this dbt package do?
 <!--section="salesforce_source_model"-->
 - Cleans, tests, and prepares your Salesforce data from [Fivetran's connector](https://fivetran.com/docs/applications/salesforce) for analysis.

macros/add_renamed_columns.sql

@@ -1,5 +1,17 @@
 {% macro add_renamed_columns(column_list) %}
-{# This macro determines the original names for each column and adds them to the list generated within each `get_*_columns` macro. By default, this macro processes column names by removing underscores and capitalizing each part that follows an underscore. This ensures all necessary columns are available for use in the `coalesce_rename` macro. Additionally, this macro tags each column with its renamed version to maintain tracking. #}
+{# 
+    This macro is a step in a workflow applied across models. It appends camelCase spellings to the list of snake_case spellings generated by the `get_*_columns` macro.  
+    By default, it transforms column names by removing underscores and capitalizing each segment following an underscore.  
+    Additionally, it tags each column with its renamed version to facilitate tracking and consistency.  
+
+    Overview:
+    1. `get_*_columns`: Creates list of snake_case columns for a given source table.  
+        1a. `add_renamed_columns`: Appends camelCase spellings of columns to the list.  
+        1b. `add_pass_through_columns`: Appends columns specified in the passthrough variable to the list.  
+    2. `column_list_to_dict`: Converts the list of columns generated in Step 1 into a dictionary, simplifying subsequent operations.  
+    3. `fill_staging_columns`: Ensures all columns from Step 1 are present in the source table by filling `null` values for any missing columns. For columns with multiple spellings, a `null` column is created for the unused spelling.  
+    4. `coalesce_rename`: Uses the dictionary from `column_list_to_dict` to coalesce a column with its renamed counterpart. This step generates the final column and supports custom arguments for renamed spelling, data type, and alias to override default values.  
+#}
 
 {%- set renamed_columns = [] %}
 

macros/coalesce_rename.sql

@@ -7,8 +7,18 @@
     renamed_column_name=column_dict[column_key]["renamed_column_name"]
     ) %}
 
-{# This macro accomodates Fivetran connectors that keep the original salesforce field naming conventions without underscores #}
-{# Utilizes the dictionary generated by `column_list_to_dict` to coalesce a column with its renamed counterpart, producing the final column. This macro also allows for the passing of a custom renamed spelling, datatype, and alias as arguments to override default values. #}
+{#
+    This macro is the final step in a workflow applied across models. It accommodates Fivetran connectors that retain Salesforce's original field naming conventions, which are camelCase instead of snake_case.
+
+    Overview:
+    1. `get_*_columns`: Creates list of snake_case columns for a given source table.  
+        1a. `add_renamed_columns`: Appends camelCase spellings of columns to the list.  
+        1b. `add_pass_through_columns`: Appends columns specified in the passthrough variable to the list.  
+    2. `column_list_to_dict`: Converts the list of columns generated in Step 1 into a dictionary, simplifying subsequent operations.  
+    3. `fill_staging_columns`: Ensures all columns from Step 1 are present in the source table by filling `null` values for any missing columns. For columns with multiple spellings, a `null` column is created for the unused spelling.  
+    4. `coalesce_rename`: Uses the dictionary from `column_list_to_dict` to coalesce a column with its renamed counterpart. This step generates the final column and supports custom arguments for renamed spelling, data type, and alias to override default values.  
+#}
+
 {%- if original_column_name|lower == renamed_column_name|lower %}
     cast({{ renamed_column_name }} as {{ datatype }}) as {{ alias }}
 

macros/column_list_to_dict.sql

@@ -1,5 +1,17 @@
 {% macro column_list_to_dict(column_list) %}
-{# This macro converts the list of dictionaries generated by the `get_*_columns` macros into a dictionary of dictionaries for use in the `coalesce_rename` macro. This conversion is necessary so that each column dictionary entry can be accessed by a key, rather than iterating through a list. #}
+
+{# 
+    This macro is a step in a workflow applied across models. It converts the list of dictionaries generated by the `get_*_columns` macros into a dictionary of dictionaries for use in the `coalesce_rename` macro. This conversion is necessary so that each column dictionary entry can be accessed by a key, rather than iterating through a list. 
+
+    Overview:
+    1. `get_*_columns`: Creates list of snake_case columns for a given source table.  
+        1a. `add_renamed_columns`: Appends camelCase spellings of columns to the list.  
+        1b. `add_pass_through_columns`: Appends columns specified in the passthrough variable to the list.  
+    2. `column_list_to_dict`: Converts the list of columns generated in Step 1 into a dictionary, simplifying subsequent operations.  
+    3. `fill_staging_columns`: Ensures all columns from Step 1 are present in the source table by filling `null` values for any missing columns. For columns with multiple spellings, a `null` column is created for the unused spelling.  
+    4. `coalesce_rename`: Uses the dictionary from `column_list_to_dict` to coalesce a column with its renamed counterpart. This step generates the final column and supports custom arguments for renamed spelling, data type, and alias to override default values.  
+#}
+
     {%- set column_dict = {} -%}
     {%- for col in column_list -%}
         {%- do column_dict.update({col.name: col}) if not col.is_rename -%}