dbt-labs / dbt-labs/docs.getdbt.com

`ref` and `source` functions both return a `Relation` object

Open
#6,331 0 comments 0 reactions 0 assignees View on GitHub
content improvement
Dominant language
JavaScript
Stars
215
Forks
1.2k
Avg merge
1d 15h
Merged PRs (30d)
130

Description

### Contributions

- [X] I have read the contribution docs, and understand what's expected of me.

### Link to the page on docs.getdbt.com requiring updates

It seems to me that there is an overarching concept that encompasses the [`ref`](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#ref-project-specific-models) and [`source`](https://docs.getdbt.com/reference/dbt-jinja-functions/source) functions. But we don't have a name for this concept or a page that covers it.

See the docs for the [`relation` config in snapshots](https://docs.getdbt.com/docs/build/snapshots#configuring-snapshots) as an example of a config that can take either a `ref` or a `source` as an argument. This same thing applies to [given inputs](https://docs.getdbt.com/reference/resource-properties/unit-test-input) in [unit tests](https://docs.getdbt.com/docs/build/unit-tests) (although we don't currently have any examples of using `source`). See also [`depends_on` for exposures](https://docs.getdbt.com/docs/build/exposures#available-properties).

Spitballing, maybe "relation functions" is a decent name? The docs for exposures call these "refable", but sources and metrics aren't in the[ list of refable node types](https://github.com/dbt-labs/dbt-core/blob/bdb79e8626b8da70c976398d527872c8c95d3716/core/dbt/node_types.py#L23-L27).

Here's a brainstorm of alternative names:

- reference
- dependency
- connector
- resolver
- binder
- link
- anchor
- bridge
- context
- map
- gateway
- lookup
- path
- access
- pointer
- relay
- fetch
- tether
- dependency link

### What part(s) of the page would you like to see updated?

The [`ref`](https://docs.getdbt.com/reference/dbt-jinja-functions/ref#ref-project-specific-models) and [`source`](https://docs.getdbt.com/reference/dbt-jinja-functions/source) functions have very similar behavior.

Here's a couple similarities:

- Both return a [Relation](https://docs.getdbt.com/reference/dbt-classes#relation)
- Both compile to the full object name in the database
- Both create dependencies between the referenced node and the current model, which is useful for documentation and [node selection](https://docs.getdbt.com/reference/node-selection/syntax)

Here's some differences:

- `ref` is for a [model](https://docs.getdbt.com/docs/build/models), [seed](https://docs.getdbt.com/docs/build/seeds), or [snapshot](https://docs.getdbt.com/docs/build/snapshots) whereas `source` is just for sources
- `ref` has a minimum of one argument has optional arguments for project/package and version whereas `source` always has exactly two arguments.
- `ref` get its `database` and `schema` from the [`generate_database_name`](https://docs.getdbt.com/docs/build/custom-databases) and [`generate_schema_name`](https://docs.getdbt.com/docs/build/custom-schemas) macros (which use `target.database` and `target.schema` from the [target variables](https://docs.getdbt.com/reference/dbt-jinja-functions/target)) whereas `source` has `database` and `schema` as part of its definition in YAML.

### Additional information

This issue is mainly inspired by the [`relation` config in snapshots](https://docs.getdbt.com/docs/build/snapshots#configuring-snapshots) that can be either `source` or `ref`:

```yaml
snapshots:
- name: string
relation: relation # source('my_source', 'my_table') or ref('my_model')
```

But could also help address this question: https://stackoverflow.com/questions/73784913/dbt-ref-vs-source

### Other tie-ins

- https://github.com/dbt-labs/docs.getdbt.com/pull/6345
- https://github.com/dbt-labs/dbt-core/issues/9599#issuecomment-1964742190
- https://github.com/dbt-labs/docs.getdbt.com/issues/6332

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the ref and source documentation, then compare the snapshot relation config, unit-test given inputs, and exposure depends_on pages mentioned in the issue. Review the related docs pull request and dbt-core discussion before choosing terminology; done means an agreed concept is documented consistently across these references.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.