Skip to content

Commit

Permalink
Update example for overriding the ref macro (#5052)
Browse files Browse the repository at this point in the history
## What are you changing in this pull request and why?

While working on #5051,
I saw some other opportunities for improvement and split them into their
own stand-alone PR.

## Checklist
- [x] Review the [Content style
guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md)
so my content adheres to these guidelines.
  • Loading branch information
mirnawong1 authored Mar 11, 2024
2 parents ef0fc40 + 548999b commit da08e43
Showing 1 changed file with 12 additions and 12 deletions.
24 changes: 12 additions & 12 deletions website/docs/reference/dbt-jinja-functions/builtins.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,23 +22,27 @@ Using the `builtins` variable in this way is an advanced development workflow. U
:::

<VersionBlock firstVersion="1.5">

From dbt v1.5 and higher, use the following macro 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>:

From dbt v1.5 and higher, use the following macro to override the `ref` method available in the model compilation context to return a [Relation](/reference/dbt-classes#relation) with the database name overriden to `dev`.

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 />


```
{% macro ref() %}
-- extract user-provided positional and keyword arguments
{% set version = kwargs.get('version') or kwargs.get('v') %}
{% set packagename = none %}
{%- if (varargs | length) == 1 -%}
{% set version = kwargs.get('version') or kwargs.get('v') %}
{% 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
{% set rel = None %}
{% if packagename is not none %}
Expand Down Expand Up @@ -71,14 +75,10 @@ From dbt v1.4 and lower, use the following macro to override the `ref` method av
```
</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.
Logic within the ref macro can also be used to control which elements of the model path are rendered when run, for example the following logic renders 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.

```
-- Macro to override ref and to render identifiers without a database.
{% macro ref(model_name) %}
{% do return(builtins.ref(model_name).include(database=false)) %}
{% endmacro %}
-- render identifiers without a database
{% do return(rel.include(database=false)) %}
```

0 comments on commit da08e43

Please sign in to comment.