From 6ba5fda70a9a53dc59ab42337cbea6e14d53f673 Mon Sep 17 00:00:00 2001
From: Mirna Wong <89008547+mirnawong1@users.noreply.github.com>
Date: Thu, 18 Jul 2024 10:28:48 +0100
Subject: [PATCH] clarify builtin macros aren't overridden via package (#5792)

this pr clarifies that builtin macros can't be overridden because they
aren't deferred and are context properties defined in python.

Resolves #971
---
 website/docs/reference/dbt-jinja-functions/builtins.md | 4 +++-
 website/docs/reference/dbt-jinja-functions/dispatch.md | 4 ++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/website/docs/reference/dbt-jinja-functions/builtins.md b/website/docs/reference/dbt-jinja-functions/builtins.md
index 0da7c6536a8..d3241ab849a 100644
--- a/website/docs/reference/dbt-jinja-functions/builtins.md
+++ b/website/docs/reference/dbt-jinja-functions/builtins.md
@@ -27,7 +27,9 @@ From dbt v1.5 and higher, use the following macro to override the `ref` method a
 
 It includes logic to extract user-provided arguments, including <code>version</code>, and call the <code>builtins.ref()</code> function with either a single <code>modelname</code> argument or both <code>packagename</code> and <code>modelname</code> arguments, based on the number of positional arguments in <code>varargs</code>.
 
-<br /><br />
+Note that the `ref`, `source`, and `config` functions can't be overridden with a package. This is because `ref`, `source`, and `config` are context properties within dbt and are not dispatched as global macros. Refer to [this GitHub discussion](https://github.com/dbt-labs/dbt-core/issues/4491#issuecomment-994709916) for more context.
+
+<br />
 
   
 ```
diff --git a/website/docs/reference/dbt-jinja-functions/dispatch.md b/website/docs/reference/dbt-jinja-functions/dispatch.md
index 5dff787219f..921731ccc84 100644
--- a/website/docs/reference/dbt-jinja-functions/dispatch.md
+++ b/website/docs/reference/dbt-jinja-functions/dispatch.md
@@ -145,6 +145,10 @@ As a package maintainer, this functionality enables users of my package to exten
 
 ### Overriding global macros
 
+:::tip
+Certain functions like [`ref`](/reference/dbt-jinja-functions/ref), [`source`](/reference/dbt-jinja-functions/source), and [`config`](/reference/dbt-jinja-functions/config) can't be overridden with a package using the dispatch config. This is because `ref`, `source`, and `config` are context properties within dbt and are not dispatched as global macros. Refer to [this GitHub discussion](https://github.com/dbt-labs/dbt-core/issues/4491#issuecomment-994709916) for more context.
+:::
+
 I maintain an internal utility package at my organization, named `my_org_dbt_helpers`. I use this package to reimplement built-in dbt macros on behalf of all my dbt-using colleagues, who work across a number of dbt projects.
 
 My package can define custom versions of any dispatched global macro I choose, from `generate_schema_name` to `test_unique`. I can define a new default version of that macro (e.g. `default__generate_schema_name`), or custom versions for specific <Term id="data-warehouse" /> adapters (e.g. `spark__generate_schema_name`).