Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update builtins.md #4050

Merged
merged 8 commits into from
Sep 12, 2023
Merged

Update builtins.md #4050

Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0bdfbd5
Update builtins.md
mirnawong1 Sep 8, 2023
efd22fb
Update builtins.md
mirnawong1 Sep 8, 2023
58ddf60
Merge branch 'current' into mirnawong1-patch-5
mirnawong1 Sep 11, 2023
4eea835
add jinja.ext.do
mirnawong1 Sep 11, 2023
fb08d60
add line break
mirnawong1 Sep 11, 2023
249d716
Merge branch 'current' into mirnawong1-patch-5
mirnawong1 Sep 11, 2023
421e633
address jerco's feedback
mirnawong1 Sep 11, 2023
25367e6
Merge branch 'current' into mirnawong1-patch-5
mirnawong1 Sep 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 37 additions & 2 deletions website/docs/reference/dbt-jinja-functions/builtins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,9 +15,43 @@ 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">
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved

From dbt v1.6 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>:

<br /><br />


```jinja2
jinja2.ext.do
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved

{% 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">
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The previous examples actually did something different — either updating or excluding the database component of the returned Relation — whereas the example above is just the same as default built-in ref.

return a Relation with the database name overridden to dev

I think we should update the example above to do the same:

-- call builtins.ref based on provided positional arguments
{% set rel = None %}
{% if packagename is not none %}
    {% set rel = return(builtins.ref(packagename, modelname, version=version)) %}
{% else %}
    {% set rel = return(builtins.ref(modelname, version=version)) %}
{% endif %}

-- finally, override the database name with "dev"
{% set newrel = rel.replace_path(database="dev") %}
{% do return(newrel) %}


From dbt v1.5 and lower, 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`:
mirnawong1 marked this conversation as resolved.
Show resolved Hide resolved

```jinja2

{% macro ref(model_name) %}

{% set rel = builtins.ref(model_name) %}
Expand All @@ -26,10 +60,11 @@ 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.

```
```jinja2
-- Macro to override ref and to render identifiers without a database.

{% macro ref(model_name) %}
Expand Down