Models
Full Example
contracts:
models:
- filter:
- path:
include:
- ^\w+\d+\s{1,3}$
- include[_-]this
exclude:
- ^\w+\d+\s{1,3}$
- exclude[_-]this
match_all: true
- meta:
meta:
key1: val1
key2:
- val2
- val3
- tag:
tags: tag1
validations:
- exists
- has_no_final_semicolon
- has_allowed_tags:
tags:
- tag1
- tag2
- has_contract
- has_required_meta_keys:
keys:
- key1
- key2
- has_description
generator:
exclude: columns
filename: config.yml
depth: 3
description:
overwrite: true
terminator: __END__
columns:
overwrite: true
add: false
remove: true
order: false
Filters
Filters (or Conditions) for reducing the scope of the contract. You may limit the number of models processed by the rules of this contract by defining one or more of the following filters.
name
Filter models based on their names.
Schema
name:
include:
default: []
description: Patterns to match against for values to include
items:
type: string
type: array
exclude:
default: []
description: Patterns to match against for values to exclude
items:
type: string
type: array
match_all:
default: false
description: When True, all given patterns must match to be considered a match
for either pattern type
type: boolean
Example
name:
include: .*i\s+am\s+a\s+regex\s+pattern.*
exclude: .*i\s+am\s+a\s+regex\s+pattern.*
match_all: true
You may also define the parameters for include directly on the definition like below.
name:
- ^\w+\d+\s{1,3}$
- include[_-]this
path
Filter models based on their paths. Paths must match patterns which are relative to the root directory of the dbt project.
Schema
path:
include:
default: []
description: Patterns to match against for values to include
items:
type: string
type: array
exclude:
default: []
description: Patterns to match against for values to exclude
items:
type: string
type: array
match_all:
default: false
description: When True, all given patterns must match to be considered a match
for either pattern type
type: boolean
Example
path:
include:
- ^\w+\d+\s{1,3}$
- include[_-]this
exclude: .*i\s+am\s+a\s+regex\s+pattern.*
match_all: false
You may define the paths as a list of lists where each part is a subdirectory within the path. These parts will then be unified by joining them with the os-specific path separator. This allows for you define os-independent configuration as needed.
include:
- ["path", "to", "folder1"]
- ["path", "to", "folder2"]
- ["path", "to", "folder3"]
exclude:
- ["path", "to", "another", "folder1"]
- ["path", "to", "another", "folder2"]
- ["path", "to", "another", "folder3"]
You may also define the parameters for include directly on the definition like below.
path: .*i\s+am\s+a\s+regex\s+pattern.*
tag
Filter models based on their tags.
Schema
tag:
tags:
default: []
description: The tags to match on
items:
type: string
type: array
Example
tag:
tags: tag1
You may also define the parameters for tags directly on the definition like below.
tag:
- tag1
- tag2
meta
Filter models based on their meta values.
Schema
meta:
meta:
additionalProperties:
items:
type: string
type: array
description: The mapping of meta keys to their allowed values
type: object
Example
meta:
meta:
key1: val1
key2:
- val2
- val3
is_materialized
Filter models taking only those which are not ephemeral.
Note
This condition does not need further configuration. Simply define the condition’s name as an item in your configuration.
Validations
Validations (or Terms) to apply to the resources of this contract. These enforce certain standards that must be followed in order for the contract to be fulfilled.
has_properties
Check whether the models have properties files defined.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_description
Check whether the models have descriptions defined in their properties.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_required_meta_keys
Check whether the models have the expected set of required meta keys set.
Schema
has_required_meta_keys:
keys:
default: []
description: The required meta keys
items:
type: string
type: array
Example
has_required_meta_keys:
keys: key1
You may also define the parameters for keys directly on the definition like below.
has_required_meta_keys:
- key1
- key2
has_allowed_meta_keys
Check whether the models have only meta keys set from a configured permitted list.
Schema
has_allowed_meta_keys:
keys:
default: []
description: The allowed meta keys
items:
type: string
type: array
Example
has_allowed_meta_keys:
keys:
- key1
- key2
You may also define the parameters for keys directly on the definition like below.
has_allowed_meta_keys: key1
has_allowed_meta_values
Check whether the models have only meta values set from a configured permitted mapping of keys to values.
Schema
has_allowed_meta_values:
meta:
additionalProperties:
items:
type: string
type: array
description: The mapping of meta keys to their allowed values
type: object
Example
has_allowed_meta_values:
meta:
key1: val1
key2:
- val2
- val3
exists
Check whether the models exist in the database.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_tests
Check whether models have an appropriate number of tests configured.
Schema
has_tests:
min_count:
default: 1
description: The minimum count allowed.
minimum: 1
type: integer
max_count:
anyOf:
- exclusiveMinimum: 0
type: integer
- type: 'null'
default: null
description: The maximum count allowed.
Example
has_tests:
min_count: 2
max_count: 5
You may also define the parameters for min_count directly on the definition like below.
has_tests: 1
has_all_columns
Check whether models have all columns set in their properties. Ensures that all columns present in the database are present in dbt project properties.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_expected_columns
Check whether models have the expected names of columns set in their properties. Also checks if those columns have the expected data types if configured to do so.
Schema
has_expected_columns:
columns:
anyOf:
- type: string
- items:
type: string
type: array
- additionalProperties:
type: string
type: object
default: []
description: A sequence of the names of the columns that should exist in the node,
or a mapping of the column names and their associated data types that should
exist.
Example
has_expected_columns:
columns:
column1: VARCHAR
column2: INT
You may also define the parameters for columns directly on the definition like below.
has_expected_columns:
- column1
- column2
- column3
has_matching_description
Check whether the descriptions configured in models’ properties match the descriptions in the database.
Schema
has_matching_description:
ignore_whitespace:
default: false
description: Ignore any whitespaces when comparing data type keys.
type: boolean
case_insensitive:
default: false
description: Ignore cases and compare data type keys only case-insensitively.
type: boolean
compare_start_only:
default: false
description: Match data type keys when the two values start with the same value.
Ignore the rest of the data type definition in this case.
type: boolean
Example
has_matching_description:
ignore_whitespace: true
case_insensitive: true
compare_start_only: false
You may also define the parameters for ignore_whitespace directly on the definition like below.
has_matching_description: true
has_contract
Check whether models have appropriate configuration for a contract in their properties.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_valid_ref_dependencies
Check whether models have an appropriate number of upstream dependencies i.e. the number of ref macros present in the query.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_valid_source_dependencies
Check whether models have an appropriate number of upstream dependencies for sources i.e. the number of source macros present in the query.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_valid_macro_dependencies
Check whether models have an appropriate number of upstream dependencies for macros i.e. the number of custom macros present in the query.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_no_final_semicolon
Check if models have a final semicolon present in their queries.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_no_hardcoded_refs
Check if models have any hardcoded references to database objects in their queries.
Note
This term does not need further configuration. Simply define the term’s name as an item in your configuration.
has_constraints
Check whether models have an appropriate number of constraints configured in their properties.
Schema
has_constraints:
min_count:
default: 1
description: The minimum count allowed.
minimum: 1
type: integer
max_count:
anyOf:
- exclusiveMinimum: 0
type: integer
- type: 'null'
default: null
description: The maximum count allowed.
Example
has_constraints:
min_count: 2
max_count: 6
You may also define the parameters for min_count directly on the definition like below.
has_constraints: 1
Generator
You may also configure a Generator for your contract. A Generator creates/updates properties files for models from the attributes found on the database resource.
Schema
generator:
exclude:
default: []
description: The fields to exclude from the generated properties.
items:
enum:
- description
- columns
type: string
type: array
filename:
default: _config.yml
description: The name to give to new properties files generated by this generator.
type: string
depth:
anyOf:
- minimum: 0
type: integer
- type: 'null'
default: null
description: The depth at which to place newly generated files within the resource
folder. e.g. 0 would place the file in the root of the resource folder, 1 would
place it in a subfolder of the root of the resource folder, etc. By default,
the file is placed in the same folder in which the resource is stored.
description:
$ref: '#/$defs/SetNodeDescription'
default:
overwrite: true
terminator: null
description: Configuration for setting the description
columns:
$ref: '#/$defs/SetNodeColumns'
default:
overwrite: true
add: true
remove: true
order: true
description: Configuration for setting the columns
defs
SetNodeColumns:
overwrite:
default: true
description: Whether to overwrite existing properties with properties from the
database. When false, keeps the values already present in the properties if
present.
type: boolean
add:
default: true
description: Add columns to the properties file which are in the database object
but missing from the properties.
type: boolean
remove:
default: true
description: Remove columns from the properties file which are in the properties
file but not in the database object.
type: boolean
order:
default: true
description: Reorder columns in the properties file to match the order found in
the database object.
type: boolean
SetNodeDescription:
overwrite:
default: true
description: Whether to overwrite existing properties with properties from the
database. When false, keeps the values already present in the properties if
present.
type: boolean
terminator:
anyOf:
- type: string
- type: 'null'
default: null
description: Only take the description up to this terminating string. e.g. if
you only want to take the first line of a multi-line description, set this to
'\n'
Example
generator:
exclude:
- description
- columns
filename: properties.yml
depth: 0
description:
overwrite: true
terminator: \n
columns:
overwrite: true
add: true
remove: false
order: false
You may also define the parameters for exclude directly on the definition like below.
generator:
- description
- columns
Columns
You may also define columns contracts as a child set of contracts on models. Refer to the columns reference for more info.