From 0bdfbd5b29b75da4ea3acbbc1d7e0aac866bba90 Mon Sep 17 00:00:00 2001
From: mirnawong1 <89008547+mirnawong1@users.noreply.github.com>
Date: Fri, 8 Sep 2023 16:37:45 +0100
Subject: [PATCH] Update builtins.md

adding 1.5+ and <=v1.5 versioning and macro explaining for ref maco
---
 .../reference/dbt-jinja-functions/builtins.md | 34 ++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/website/docs/reference/dbt-jinja-functions/builtins.md b/website/docs/reference/dbt-jinja-functions/builtins.md
index 40848705dc4..c37a46365d6 100644
--- a/website/docs/reference/dbt-jinja-functions/builtins.md
+++ b/website/docs/reference/dbt-jinja-functions/builtins.md
@@ -15,7 +15,38 @@ The `builtins` variable is a dictionary containing the following keys:
 
 ## Usage
 
-The following macro overrides the `ref` method available in the model compilation context to return a [Relation](/reference/dbt-classes#relation) with the database name overriden to `dev`.
+<VersionBlock firstVersion="1.6">
+  
+The following macro extracts user-provided arguments, including `version`, and calls the `builtins.ref()` function with either a single `modelname` argument or both `packagename` and `modelname` arguments, based on the number of positional arguments in `varargs`:
+  
+```
+{% macro ref() %}
+
+-- extract user-provided positional and keyword arguments
+{% set version = kwargs.get('version') %}
+{% set packagename = none %}
+{%- if (varargs | length) == 1 -%}
+    {% set modelname = varargs[0] %}
+{%- else -%}
+    {% set packagename = varargs[0] %}
+    {% set modelname = varargs[1] %}
+{% endif %}
+
+-- call builtins.ref based on provided positional arguments
+{% if packagename is not none %}
+    {% do return(builtins.ref(packagename, modelname, version=version)) %}
+{% else %}
+    {% do return(builtins.ref(modelname, version=version)) %}
+{% endif %}
+
+{% endmacro %}
+```
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.5">
+
+The following macro overrides the `ref` method available in the model compilation context to return a [Relation](/reference/dbt-classes#relation) with the database name overriden to `dev`:
 
 ```
 {% macro ref(model_name) %}
@@ -26,6 +57,7 @@ The following macro overrides the `ref` method available in the model compilatio
 
 {% endmacro %}
 ```
+</VersionBlock>
 
 The ref macro can also be used to control which elements of the model path are rendered when run, for example the following macro overrides the `ref` method to render only the schema and object identifier, but not the database reference i.e. `my_schema.my_model` rather than `my_database.my_schema.my_model`. This is especially useful when using snowflake as a warehouse, if you intend to change the name of the database post-build and wish the references to remain accurate.