dbt-labs / dbt-labs/docs.getdbt.com
`ref` and `source` functions both return a `Relation` object
- 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