ref and source functions both return a Relation object

[dbeatty10]

Contributions

• 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 and 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 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 in unit tests (although we don't currently have any examples of using source). See also depends_on for exposures.

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.

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 and source functions have very similar behavior.

Here's a couple similarities:

• Both return a 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

Here's some differences:

• ref is for a model, seed, or snapshot 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 and generate_schema_name macros (which use target.database and target.schema from the target variables) 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 that can be either source or ref:

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

• Updates for unit testing docs #6345
• [Feature] Be able to --favor-state for sources dbt-core#9599 (comment)
• Rephrase the two criteria for resolving ref calls with the --defer flag #6332