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

@@ -151,6 +151,10 @@ Pre- and post-hooks can also call macros that return SQL statements. If your mac
 
 dbt aims to provide all the boilerplate SQL you need (DDL, DML, and DCL) via out-of-the-box functionality, which you can configure quickly and concisely. In some cases, there may be SQL that you want or need to run, specific to functionality in your data platform, which dbt does not (yet) offer as a built-in feature. In those cases, you can write the exact SQL you need, using dbt's compilation context, and pass it into a `pre-` or `post-` hook to run before or after your model, seed, or snapshot.
 
+import SQLCompilationError from '/snippets/_render-method.md';
+
+<SQLCompilationError />
+
 ## Examples
 
 <Snippet path="hooks-to-grants" />

website/snippets/_render-method.md

@@ -0,0 +1,17 @@
+#### The render method
+
+The `.render()` method is generally used to resolve or evaluate Jinja expressions (such as `{{ source(...) }}`) during runtime. When a pre-hook or post-hook contains a dynamic reference, such as a table or column, dbt might not automatically resolve the reference correctly, particularly when certain flags (such as `--empty`) are applied.
+
+When using the `--empty flag`, dbt may skip processing `ref()` or `source()` for optimization. To avoid compilation errors and to explicitly tell dbt to process a specific relation (`ref()` or `source()`), use the `.render()` method in your model file. For example:
+
+
+<File name='models.sql'>
+
+```Jinja
+{{ config(
+    pre_hook = [
+        "alter external table {{ source('sys', 'customers').render() }} refresh"
+    ]
+```
+
+</File>