Nfiann-prehook-emptyflag

website/docs/reference/commands/build.md

@@ -31,32 +31,9 @@ In DAG order, for selected resources or an entire project.
 
 The `build` command supports the `--empty` flag for building schema-only dry runs. The `--empty` flag limits the refs and sources to zero rows. dbt will still execute the model SQL against the target data warehouse but will avoid expensive reads of input data. This validates dependencies and ensures your models will build properly.
 
-#### SQL compilation error when running the `--empty` flag on a model
-
-If you encounter the error: `SQL compilation error: syntax error line 1 at position 21 unexpected '('.` when running a model with the `--empty` flag, explicitly call the `.render()` method on that relation.
-
-
-<File name='models.sql'>
-
-```Jinja
-
--- models/staging/stg_sys__customers.sql
-{{ config(
-    pre_hook = [
-        "alter external table {{ source('sys', 'customers').render() }} refresh"
-    ]
-) }}
-
-with cus as (
-    select * from {{ source("sys", "customers") }} -- leave this as is!
-)
-
-select * from cus
-
-```
-
-</File>
+import SQLCompilationError from '/snippets/_render-method.md';
 
+<SQLCompilationError />
 
 ## Tests
 

website/docs/reference/resource-configs/pre-hook-post-hook.md

@@ -192,6 +192,10 @@ See: [Apache Spark docs on `ANALYZE TABLE`](https://spark.apache.org/docs/latest
 
 </File>
 
+import SQLCompilationError from '/snippets/_render-method.md';
+
+<SQLCompilationError />
+
 ### Additional examples
 We've compiled some more in-depth examples [here](/docs/build/hooks-operations#additional-examples).
 

website/snippets/_render-method.md

@@ -0,0 +1,27 @@
+#### The render method
+
+If you encounter a SQL compilation error when running a model with the `--empty` flag, explicitly call the `.render()` method on that relation. The error occurs because dbt processes certain parts of the workflow differently when the `--empty flag` is used, leading to confusion when it encounters the table reference (`{{ source(...) }}`) in the pre-hook. The error you're seeing is a result of dbt not handling the reference as you anticipated.
+
+The recommended solution is to explicitly instruct dbt on how to interpret the reference in the pre-hook by using the `.render()` method. This approach ensures that dbt properly prepares the reference before executing it.
+
+
+<File name='models.sql'>
+
+```Jinja
+
+-- models/staging/stg_sys__customers.sql
+{{ config(
+    pre_hook = [
+        "alter external table {{ source('sys', 'customers').render() }} refresh"
+    ]
+) }}
+
+with cus as (
+    select * from {{ source("sys", "customers") }} -- leave this as is!
+)
+
+select * from cus
+
+```
+
+</File>