Skip to content

Commit

Permalink
Explain which resource types the ref function applies to (#5804)
Browse files Browse the repository at this point in the history
Previews:
-
[ref](https://docs-getdbt-com-git-dbeatty10-patch-1-dbt-labs.vercel.app/reference/dbt-jinja-functions/ref)
-
[source](https://docs-getdbt-com-git-dbeatty10-patch-1-dbt-labs.vercel.app/reference/dbt-jinja-functions/source)

## What are you changing in this pull request and why?

This update is useful to understand some of the differences between
[`ref()`](https://docs.getdbt.com/reference/dbt-jinja-functions/ref) and
[`source()`](https://docs.getdbt.com/reference/dbt-jinja-functions/source).
In turn, that is useful context for issues like
dbt-labs/dbt-core#10433.

The
[`source()`](https://docs.getdbt.com/reference/dbt-jinja-functions/source)
and [`ref()`](https://docs.getdbt.com/reference/dbt-jinja-functions/ref)
functions are complementary:

`source()` applies to:
- [sources](https://docs.getdbt.com/docs/build/sources)

Whereas `ref()` applies to:
- [models](https://docs.getdbt.com/docs/build/models) (both [SQL
models](https://docs.getdbt.com/docs/build/sql-models) and [Python
models](https://docs.getdbt.com/docs/build/python-models))
- [seeds](https://docs.getdbt.com/docs/build/seeds)
- [snapshots](https://docs.getdbt.com/docs/build/snapshots)

`ref()` includes:
- [versioned
models](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#versioned-ref)
- [package-specific
nodes](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#ref-project-specific-models)
- [cross-project
nodes](https://docs.getdbt.com/docs/collaborate/govern/project-dependencies#how-to-write-cross-project-ref)

## 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.

---------

Co-authored-by: Mirna Wong <89008547+mirnawong1@users.noreply.github.com>
  • Loading branch information
dbeatty10 and mirnawong1 authored Jul 19, 2024
1 parent 10322bd commit a529ff4
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 4 deletions.
15 changes: 13 additions & 2 deletions website/docs/reference/dbt-jinja-functions/ref.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,21 @@
title: "About ref function"
sidebar_label: "ref"
id: "ref"
description: "Read this guide to understand the builtins Jinja function in dbt."
keyword: dbt mesh, project dependencies, ref, cross project ref, project dependencies
description: "Read this guide to understand the ref Jinja function in dbt."
keyword: dbt mesh, project dependencies, ref, cross project ref
---

```sql
select * from {{ ref("node_name") }}
```

## Definition

This function:
- Returns a [Relation](/reference/dbt-classes#relation) for a [model](/docs/build/models), [seed](/docs/build/seeds), or [snapshot](/docs/build/snapshots)
- Creates dependencies between the referenced node and the current model, which is useful for documentation and [node selection](/reference/node-selection/syntax)
- Compiles to the full object name in the database

The most important function in dbt is `ref()`; it's impossible to build even moderately complex models without it. `ref()` is how you reference one model within another. This is a very common behavior, as typically models are built to be "stacked" on top of one another. Here is how this looks in practice:

<File name='model_a.sql'>
Expand Down
4 changes: 2 additions & 2 deletions website/docs/reference/dbt-jinja-functions/source.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@ description: "Read this guide to understand the source Jinja function in dbt."
---

```sql
select * from {{ source(source_name, table_name) }}
select * from {{ source("source_name", "table_name") }}
```

## Definition

This function:
- Returns a [Relation](/reference/dbt-classes#relation) for a [source](/docs/build/sources)
- Creates dependencies between a source and the current model, which is useful for documentation and model selection
- Creates dependencies between a source and the current model, which is useful for documentation and [node selection](/reference/node-selection/syntax)
- Compiles to the full object name in the database


Expand Down

0 comments on commit a529ff4

Please sign in to comment.