Declaring resource properties

Overview

While configurations tell dbt how to build something in your warehouse (for example, whether a model should be a table or view, or which SQL to use when running a snapshot), resource properties are used to declare things about your dbt project or data warehouse.

For example, you can use resource properties to:

  • Describe models, snapshots, seed files, and their columns
  • Assert "truths" about a model, in the form of tests, e.g. "this id column is unique"
  • Apply tags to resources
  • Define existing tables contains raw data as sources
  • Assert the expected "freshness" of this raw data

In dbt, these properties are declared in .yml files, in the same directory as your resources. There's a few quirks for backwards compatibility reasons:

ResourceDefault directoriesDefined by
modelsmodels/source-paths
sourcesmodels/source-paths
seedsdata/ or models/data-paths or source-paths
snapshotssnapshots/ or models/snapshot-paths or source-paths
analysesanalyses/ or models/analysis-paths or source-paths
macrosmacros/ or models/macro-paths or source-paths

You can name these files whatever_you_want.yml and nest them arbitrarily deeply in subfolders within each directory.

info

schema.yml files

Previous versions of the docs referred to these as schema.yml files — we've moved away from that terminology since the word schema is used to mean other things when talking about databases, and people often thought that you had to name these files schema.yml.

(Of course, you're still free to name your files schema.yml)

Example

Here's an example that defines both sources and models for a project:

models/jaffle_shop.yml
version: 2
sources:
- name: raw_jaffle_shop
description: A replica of the postgres database used to power the jaffle_shop app.
tables:
- name: customers
columns:
- name: id
description: Primary key of the table
tests:
- unique
- not_null
- name: orders
columns:
- name: id
description: Primary key of the table
tests:
- unique
- not_null
- name: user_id
description: Foreign key to customers
- name: status
tests:
- accepted_values:
values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']
models:
- name: stg_jaffle_shop__customers
columns:
- name: customer_id
tests:
- unique
- not_null
- name: stg_jaffle_shop__orders
columns:
- name: order_id
tests:
- unique
- not_null
- name: status
tests:
- accepted_values:
values: ['placed', 'shipped', 'completed', 'return_pending', 'returned']

Related documentation

You can find an exhaustive list of each property for a resource in the following docs:

FAQs

 Does my `.yml` file containing tests and descriptions need to be named `schema.yml`?
 If I can name these files whatever I'd like, what should I name them?
 Should I use separate files to declare resource properties, or one large file?
 Can I add tests and descriptions in a config block?
 Why do model and source yml files always start with `version: 2`?
 Can I use a yaml file extension?

Troubleshooting common errors

Invalid test config given in [model name]

This error occurs when your .yml file does not conform to the structure expected by dbt. A full error message might look like:

* Invalid test config given in models/schema.yml near {'namee': 'event', ...}
Invalid arguments passed to "UnparsedNodeUpdate" instance: 'name' is a required property, Additional properties are not allowed ('namee' was unexpected)

While verbose, an error like this should help you track down the issue. Here, the name field was provided as namee by accident. To fix this error, ensure that your .yml conforms to the expected structure described in this guide.

Invalid syntax in your schema.yml file

If your .yml file is not valid yaml, then dbt will show you an error like this:

Runtime Error
Syntax error near line 6
------------------------------
5 | - name: events
6 | description; "A table containing clickstream events from the marketing website"
7 |
Raw Error:
------------------------------
while scanning a simple key
in "<unicode string>", line 6, column 5:
description; "A table containing clickstream events from the marketing website"
^

This error occurred because a semicolon (;) was accidentally used instead of a colon (:) after the description field. To resolve issues like this, find the .yml file referenced in the error message and fix any syntax errors present in the file. There are online yaml validators that can be helpful here, but please be mindful of submitting sensitive information to third-party applications!