We have several test-related study notes already published. But let’s recap:

Data tests are assumptions we make about resources in our project. For instance, we can configure a model to fail or issue a warning when certain preset requirements are not met.

They can broadly be divided into singular tests and generic tests. Generic tests can either be provided by dbt or defined/customised by users.

This post is dedicated specifically to custom generic tests, although we will touch on standard generic tests for differentiation purposes.

What are custom generic tests?

Before we go deep into custom generic tests, let’s zoom out for a second.

Within the realm of generic tests, we have:

Built-in generic tests:

• NotNull

• Unique

• Relationship

• Accepted Values

Custom generic tests:

• with standard arguments: tests that use the two standard arguments of model and column_name.

• with additional arguments: tests that, besides the two standard arguments, also use bespoke arguments in their assertions.

• optionally overriding a built-in generic test: the ability to modify the built-in tests above by adding them to a test block

Apologies if this is obvious for you, I find the naming convention dbt uses for tests quite confusing so I felt the need to redefine them here.

Generic tests can be stored in tests/generic/ or macros/. The latter can be convenient when the test depends on complex macro logic that you want to keep in the same file.

When documenting a custom generic test in a schema.yml file, use the test_ prefix when specifying the macro's name. For example, a test block named not_empty_string is documented as test_not_empty_string.

Recap on custom generic tests with standard arguments:

All custom generic tests are required to go inside a test block with the arguments below:

• model (required): the resource on which the test is defined. The argument is always named model, even when the resource is a source, seed, or snapshot.

• column_name: the column on which the test is defined - for those tests that do operate on the column level.

The final select should return records which fail the test. A generic data test passes when its query returns zero rows. Any rows returned represent records that violate the test condition and therefore cause the test to fail.

Also, the test can be reused for any model and column as long as it’s declared in the yaml file for the desired resources. Below, it’s being declared for the favorite_number column in the users model. But you could also declare it for other columns in the same or other resources.

Finally, in the example above, the test operates on a column and therefore is declared under the column: block. However, a test may operate on an entire model, in which case, it can be declared directly under the model: block.

Custom generic tests with additional arguments

Besides the standard arguments, you can also add bespoke arguments relevant to your test. For example, the test below is testing models for a minimum number of rows.

The additional argument is declared in the model.yml file where you can set the default value to be used by the test:

Customising built-in generic tests

Finally, another option you have with tests is to modify the out-of-the-box tests.

You can do that by simply adding a test block using the name of one of the built-in tests. dbt will favour your version over the default one.

Using the config( ) block inside a custom generic test

You can add config( ) blocks to a custom generic test definition. Values defined there will be applied for all instances of that generic test. For instance, below we’re configuring the warn_if_odd test to serve a warning in case it fails.

You can, however, override that config for specific columns or models. Like below where we are telling dbt to throw an error instead when the warn_if_odd test is applied specifically against the other_number column of the users model.

Sometimes, dbt changes existing behaviour to improve correctness, consistency, usability, or performance.

For instance, in v1.11, dbt introduced changes around how duplicate resource names are handled and how dbt determines whether resources are modified during state-aware execution.

These changes affect how your code is parsed, selected, or executed. If a behaviour change were implemented without a transition mechanism, projects that previously worked could behave differently or fail after a dbt upgrade.

That’s where behaviour flags come in: they provide a controlled transition from the old behaviour to the new behaviour, allowing projects to opt into the new behaviour before it becomes the default and the old behaviour is removed.

Behaviour flags are defined in dbt_project.yml so the chosen behaviour affects all resources in a version-controlled project rather than relying on individual developers passing configuration through the command line

Let’s look at an example:

The best way to understand this concept is to use one of the many behaviour change flags as an example: let’s pick require_unique_project_resource_names.

Starting in v1.11, dbt began enforcing that every resource in the project needs to have a unique name.

Previously, if a seed and a model in the same package were both named “customer” , dbt did not always reject the duplicate name. The project could therefore run, but a ref() or source() could potentially resolve to the wrong resource.

Now, the current behaviour depends on the stage of the flag and its set value.

Flag stages

Once dbt enforces a behaviour change, it goes through 3 stages:

1. Introduced: the new behaviour is disabled by default with require_unique_project_resource_names: false → the old behaviour remains the default.

2. Mature: the new behaviour is enabled by default

   require_unique_project_resource_names: true → You can still preserve the old behaviour by explicitly setting the flag to false, but you may see deprecation warnings.

3. Removed: the old behaviour is removed from the dbt codebase and the flag may eventually be removed. dbt provides significant advance warning if a flag is going to be removed.

Our example flag, require_unique_project_resource_names, is currently in the Mature stage, meaning the new behavior is the default. Projects containing duplicate resource names would encounter a DuplicateNameDistinctNodeTypesDeprecation warning.

Important: what isn’t a behaviour change

Not every change in dbt is considered a behaviour change. Behaviour change flags are specifically used when dbt intentionally changes how existing project code behaves and needs to provide a transition between the old and new behaviour.

The following are not considered behaviour changes:

• Fixing a bug where the previous behaviour was defective, undesirable, or undocumented.

• Adding a new warning where dbt previously did not raise one.

• Changing the wording of human-friendly messages in log events.

A behaviour change means dbt intentionally changes what your existing code does.

This is not another technical post with screenshots of code and complex terminology. However, the processes around creating and maintaining a data product is no less important.

The issue at hand

(I’m adding a bit of personal experience of 7+ years working in data teams)

Companies are growingly invested in developing a mature data environment from which they can drive productivity and ROI. However, in my experience, business may jump at the task without a full understanding of what it entails.

I always notice a strong focus on the technical suite. Which data warehouse should we use? What should we use for ingestion? What visualisation tool we are going to pick? Do we have personnel with the technical skills to deploy all this?

However, components that are essential for a mature data product are often overlooked. Governance, ownership, team processes. For me, these are the things that separate a data environment from a MATURE data environment.

The article mentions patchwork processes and this is a particular pet peeve of mine. When your team is constantly patching rather than sorting the issue at the souce, your data is creating more pointless work for you, rather than do what it is meant to do: enable productivity and free up analysts/scientists time to do more meaningful work.

Finally, for the aspiring analysts out there, you’d be surprised how immature data environments can be even in big multi-million dollar companies. For the smaller start-ups, often the eagerness to innovate bring about lack of governance. I’d go as far as saying is epidemic and, for that reason, it is so important that data professionals understand what a mature, scalable data environments should look like.

Best practices for data product management

Goals, metrics and user-centered design

You data products should be aligned to business goals and aim to solve specific, quantifiable problems.

Teams should also monitor user engagement, adoption rate, and user satisfaction of the data products they create. I’d go one step further from the article and add maintanence cost to that list - not only in terms of money but resource too.

When designing a product, consider developing first a simplified version of it and gather feedback as the product evolves. Again, I’d make one addition here: be aware that a product is never 100% finished because needs and questions change and a good product evolves with the business.

Defining, documenting, and discovering data products

dbt recommends that a data product is always:

• Discoverable: maintain a central catalog or marketplace for the products.

• Addressable and Interoperable: use naming conventions and standardised formats.

• Self-describing: create well-defined metadata for your products with business logic, ownership, purpose, and update frequency.

• Secure: use role-based access controls in the warehouse and row-level security in reporting.

• Properly documented: foster understanding and trust with a thoughtful description of the purpose of the data, the transformations applied, and the intended decision context.

Data quality and governance

You can implement data governance by following the below principles.

• Testing and checks: automate tests to ensure products meet the standards and expectations they were built around. Uniqueness checks for primary keys and relationship tests prevent report breaking while not-null constraints ensure data quality of required fields. CI/CD tests can avoid data errors making it to production.

• Lineage and stewardship: maintain traceability to make errors easier to sort out and their impact clearer. Assign data stewards for each domain and a data owner to troubleshoot failed tests, update policies, and communicate with stakeholders.

Cross-team collaboration and roles

• Establish roles: data roles should be clear with no unnecessary overlapping and respecting each roles’ responsibilities.

• Build communication connections: implement communication networks between data teams and data-stakeholders. This can take the form of daily/weekly meetings, office hours, feedback surveys, etc.

• Use dbt’s collaboration tools: git integration, multi-environment deployment, and real-time slack notifications.

Agile iteration and prioritisation

dbt describes an agile mindset as taking into consideration:

• Early delivery: allow stakeholders to give you feedback and notice value with a small sample of the product before scaling. Use sprints and a prioritised backlog to make development organised and predictable.

• Feature flags: monitor usage of new functionality with feature flags or small-scale beta releases. Ensure even small changes undergo testing and adhere to governance criteria.

• Modular design: think modularly and implement an effective PR strategy.

Scalability, performance, and maintenance

Increase the sustainability of your data products by implementing:

• Performance tracking: observe query performance and resource utilisation to apply time and money saving fixes where needed.

• Domain ownership: create local expertise, balance workload out, and minimise dependency on a central team.

Monitoring, observability, and feedback

Keep data relevant and trusted by performing:

• Robust monitoring: set up alerts for test failures, sudden spikes in resource usage, or unexpected drops in data volume.

• User feedback: gather regular input through feedback tools or scheduled discussions to build trust and increase adoption.

Let’s combine two non-essential but helpful commands that make the life of the developer easier. We’ll focus on dbt Core funcionalities as the exam is based on that version of dbt.

About the dbt show command

The dbt show command is the closest equivalent to the Preview feature in dbt Cloud for dbt Core. Besides viewing query results in a readable format in the terminal, you can also use it to preview test failures, for instance.

It is a CLI command that compiles the SQL and executes it against the warehouse. You can only run it against a single node and it will query from the source, even if you already have the database relation materialised.

By default, only 5 rows will be displayed. You can use the limit or the inline flag to tweak that.

The limit flag

By using this flag, dbt will wrap your query in a CTE and call it with a limit n clause.

The inline flag

This flags allow you to literally write the query in-line which helps with quick, one-off investigations you don’t want to create a model file for. The results won’t be stored in any dbt files or materialisations, except for dbt logs.

Because the query is in-line, dbt can’t guarantee that the query is going to modify the warehouse, so it’s recommended to use it with a read-only profile.

The output json flag

This flag returns the results in JSON format. You can also set --log-format json for the full terminal output, including logs.

About the dbt retry command

This command re-executes the last invocation from the last point of failure, using the run_results.json file to determine which node to start from.

It works against nodes that have been executed against the warehouse. If a previous run failed due to database connection/permission errors, dbt retry will not work as there are no recorded nodes. In these cases check your run_results.json files and manually re-run the full job.

If the previous run did not fail, dbt retry will return no operation.

Supported commands

Retry works with: build, compile, clone, docs generate, seed, snapshot, test, run, and run-operation.

Supported flags

This command supports several flags in a local installation or in the IDE. For dbt Core, typically only --threads and --vars are supported. You can run dbt retry help for the full list of supported flags.

You can also use the standard --select, --exclude and --selector to limit nodes.

The --threads flag

Overrides the number of concurrent threads for the invocation.

The --vars flag

Passes project variables to the retried execution.

We have previously glossed over the 4 key dbt commands. Now, we will look at the most important command in more detail and understand how to control its behaviour with flags and methods.

What does it do?

It includes all key actions for resource execution: parsing, compilation, and running.

Resources are processed in DAG order and users have the ability to use selection flags (--select, --execute, --selector, --resource-type) to build selected resources.

The task generates a single manifest and a single run results artifact.

The --empty flag

The --empty flag is used for building schema-only dry runs. By adding this flag to dbt build, dbt will execute the models while limiting the refs and sources to zero rows.

This is useful if you only want to validate dependencies and ensure models build successfully without building the entire model in the data warehouse.

If you need certain ref( ) and source( ) functions to be executed in order to avoid compilation errors, you can use the .render( ) method in the file.

The --sample flag

Available for dbt run and dbt build, this flag is a step further from the --empty flag as it adds a sample of the data to your development schema. It’s time-based and uses the event_time config used for some types of incremental materialisations.

Use this flag to reduce building times and warehouse spend when you only need enough data to validate the outputs.

You can limit the sample using hours, days, months, or years:

You can also set a start and end date:

Similarly to --empty, use .render( ) to prevent a ref from being sampled.

Lastly, this flag is not available for Python models. Also, Seeds referenced in the model are loaded in their entirety.

Building tests

When building a model with tests configured for it, a test failure will cause downstream resources to skip entirely.

In the tests configuration post, you can learn how to adjust configs like severity, warn_if, and error_if to control this behaviour.

Tests also have a running order: unit tests → model is materialized → data tests. This avoids materialising models that will go on to fail their unit tests.

User-defined functions

The newly released user-defined functions are also built with the dbt build command.

Analyses is a simple but very useful functionality dbt offers to help you keep exploratory sql organised, shareable across the team, and version controlled.

What are Analyses?

Whilst you’re modelling data, you might need to do an exploratory analysis, data validation or one-off investigations of your sources or models.

Rather than storing these queries in model files—or losing track of them in your SQL editor—dbt provides the analyses/ directory as a dedicated place to keep them under version control.

The special behaviour of this directory is: any sql files placed here will be compiled, but not executed.

This means that Jinja expressions such as ref() and source() are rendered into executable SQL. However, unlike models, analyses are not materialised in your data warehouse when you run them. You can execute the compiled SQL manually whenever you want to inspect the results.

Like with models, use dbt compile to compile the analysis into runnable sql. The generated sql file lives in the target directory.

Configuring Analyses

dbt recommends developers to have a .yml file in the analyses/ directory for proper configuration.

You can add documentation properties like file and column descriptions as well as assign tags to analyses.

Microbatch is one of the 5 incremental strategies available in dbt.

The basics of incremental refreshes have been covered previously, so this post will focus on this particular strategy and its relevant configs.

What is microbatch in dbt?

The keyword here is: time-series.

Microbatch allows you to define time-based ranges for filtering and reducing the amount of data to be refreshed.

In this strategy, every unit of time (by default, a single day of data) is considered a batch. This batch can be built or replaced on its own, unlike other strategies that simply differentiate “old” from “new” data.

Therefore, the microbatch strategy allows you to run batches separately, concurrently and retry them independently.

How microbatch works

This strategy requires an event-time column to be created in the model itself as well as all upstream models that need to be filtered. You can switch off filtering for time-based upstream models by specifying ref('upstream_model').render(), although this is not generally recommended.

Upstream models that do not have a reliable time-based column will undergo a full run with every refresh.

You also need to configure a batch_size, which tells dbt what unit of time you’d like your batches to be considered.

In the example below, sessions.sql is configured as a microbatch. It depends on the model customers.sql which is not time-based. Note that event_time was defined as the column session_start and the batch_size = day.

When sessions.sql is run on October 2 2024, the following sql is compiled:

Note how each batch generates a sql query that is run and loaded independently. dbt will take the result of each of batch and insert, update, or replace the contents of the sessions table, according to the most efficient mechanism of each operator.

The customers model, which doesn’t have a time-series, will be fully run each time.

Configurations

The microbatch strategy has 3 required configurations and 2 optional ones. Please note, specific adapters may require additional config.

1. Event_time (required)

Indicates the timestamp of the tracked event. Currently, only UTC is supported as a timezone.

As mentioned before, it’s wise to include this in every time-based upstream model to avoid full refreshes every time a downstream model is run.

2. Begin (required)

Useful for the initial build as well as any full refreshes. It determines the date from which the batches should be considered.

3. Batch_size (required)

The granularity of the batches. May be hour, day, month, or year.

4. Lookback (optional)

You can tell dbt to run X batches before the latest refresh to capture late-arriving records.

5. Concurrent_batches (optional - currently only available in Snowflake)

Set this to true if you want dbt to run batches in parallel or false if you want the batches to be run sequentially.

By default, dbt will auto-detect if batches can be run at the same time, according to the number of batches and available threads. Also, the first and the last batch will always be run on their own.

Parallel running offers faster processing but cannot be used in cases when the order in which the batches are processed matter. Cumulative metrics (like rolling totals) are an example of this.

Performing full refreshes on microbatch models

dbt recommends configuring full_refresh: false for these models to ensure --full-refresh flags are ignored.

If you do need a full refresh to be performed, specify the --event-time-start and --event-time-end:

Microbatch strategy vs. other incremental strategies

As mentioned above, microbatching does not fit every use case but it offers a clear advantage over other incremental materialisations.

Simpler configuration

While other incremental strategies requires you to write custom sql to define what “new” means, microbatch does it for you with 3 simple (potentially 5 for additional control) configs.

Personally, I see this as a blessing and a curse. It’s simpler but doesn’t accommodate more bespoke cases where you may need to slice the data further.

If you tuned into the dbt Coalesce in Oct 2025, you likely joined me in wondering when those new features would make their way into the dbt Analytics Engineering Certification Exam.

In late 2025, dbt released dbt Core v1.11, and, sure enough, as of 20th May 2026, the exam will begin targeting this version. Naturally, this impacted the new exam outline and what you should focus on while preparing for the exam.

In this post, I am going to outline these changes and what this means for our own updated Study Guide.

The new dbt Core v1.11: dbt wants to be more than a SQL transformation tool

More than just introducing new features, the new dbt Core is evolving from a mere SQL transformation framework to become a production analytics engineering platform.

The release article states that dbt is now catering to the needs of teams who want to:

• standardise logic across their data stack

• understand when they're adhering to the dbt standard and when they're doing something custom

• benefit from better debugging and performance optimisations

With this evolution, the exam naturally evolved as well.

Knowing how to use the standard features of dbt is no longer enough to get certified - those topics now sit mostly in the “fundamentals” layer.

Now, the expectation is that you understand how dbt behaves inside a real production pipeline: orchestration, state-aware execution, testing strategy, governance, incremental processing, failure handling, and operational troubleshooting.

The focus has shifted from “Can you build dbt models?” to “Can you operate dbt reliably as part of a larger data product?”

What’s changing in the exam outline?

Although the biggest new feature of dbt Core v1.11 is the UDFs, this has yet to make the exam outline. However, there are still substantial changes that all aspiring certified developers should be mindful of.

The Study Guide has been fully updated to reflect these changes.

1. The Fundamentals have expanded

What dbt considers as fundamental knowledge has changed.

Previously, the first Checkpoint was a deep-dive into the simplest parts of dbt, like sources and models - with a dedicated section to using SQL in business logic and git functionality.

Now, with the evolving state of data pipelines in the real world, dbt adds incremental materializations, snapshots and advanced flags to the Fundamentals.

Therefore, as a starting point, you should become very familiar with all the functionalities that dbt offers.

2. Increased focus on model governance and debugging

As dbt places itself as more than a SQL transformation tool, certified developers should know how to use its functionalities to prevent errors from happening and, when they do happen, to catch them early on.

Model access, versioning and contracts were already part of the previous exam. Debugging also had a light focus.

Now, besides covering these as functionalities, the new exam outline expects you to know of best practices and how to use flags to effectively catch errors before they hit production.

3. Testing on steroids: unit tests are now part of the exam

Testing has always been an important part of the dbt infrastructure and this has not changed.

In the new outline, unit testing is added as a topic. But not only that, certified developers should know how to create an efficient testing strategy that serves their data product.

4. Decreased focus on dbt docs and advanced deployment

While the topics above have become more important, dbt has decreased the focus on documentation and advanced deployment.

In the new outline, dbt docs is still mentioned as part of the long list of funcionalities under Fundamentals but with a much smaller focus than before.

As for advanced deployement, topics like environment variables, custom schema, and hooks have disappeared from the outline.

As dbt projects scale, running the entire DAG for every change quickly becomes inefficient—both in time and compute cost. To solve this, dbt offers state-based selection, which enables you to compare your current project against a previous state and run only the resources that have changed.

In order to attain this, it uses the manifest.json file and the --state method. Learn exactly how this works and how to customise state-based selection to your needs.

The manifest file

After executing a dbt command, a manifest.json file is created in the project’s target directory. Even if you’re only running specific nodes of the project, this file will contain a full description of your project’s resources and configurations.

The manifest file is used for analysing the project’s health, compiling the docs site, and allowing state comparison.

It’s important to remember that with every parsing, dbt overwrites the manifest file in the target directory. Therefore, you should never compare a project’s state to the target manifest, as it leads to incorrect or unreliable results (e.g., no changes detected or warnings about a missing manifest).

Instead, you can store artifacts from a previous run in a separate folder and use that path for state comparison.

State comparison

The state method enables you to select nodes according to a comparison with previous versions of the project.

The commands above are using state:new and state:modified, and dbt offers another two states.

• state:new will only select new nodes, that is, nodes whose unique_id are not already included in the comparison manifest. Bear in mind that a test is a resource, so new tests in existing models will also be selected.

• state:old is the opposite of new, that is, it will select nodes that already exist in the manifest.

• state:modified selects existing models that have been modified.

• state: unmodified is the opposite of modified and runs all nodes that had no changes.

Deep-dive into state:modified

Due to the complexity and diversity of dbt projects, there are aspects to consider when using state:modified to ensure it meets your specific needs.

Additional subselectors:

You can specify which aspect of the node needs to be compared against the manifest using the following subselectors:

• state:modified.body → changes to the node’s body like in a SQL model or seed values.

• state:modified.configs → selects resources whose configs have changed since the last manifest. These changes don’t include database, schema, and alias.

• state:modified.relation → changes to database, schema, and alias.

• state:modified.persisted_descriptions → changes to descriptions, but must have persist_docs enabled at each level.

• state:modified.macros → changes to upstream macros called directly or indirectly.

• state:modified.contract → resources whose contract has changed. In the case of breaking changes, an error will be thrown.

If no subselectors are used, dbt will enforce all of the above, plus other resource-specific criteria such as freshness, quoting, and maturity.

Impact of group changes:

While running on state:modified, dbt will track node-level config changes, including group definitions, access permissions, deprecation dates, and latest_version.

If a group definition changes, the models affected will be caught under the state:modified selection. However, as the group configuration can be used to control resource access, this may cause breakage downstream.

Even if you update the group everywhere, dbt still flags these nodes as modified, and any resulting access or reference issues are detected during parsing or execution.

Attention to partial parsing: with partial parsing enabled, dbt may not immediately detect downstream reference issues during parsing, but they will surface during execution (especially if downstream nodes are included in the run).

The “nothing to do” error and selecting downstream resources:

This error is thrown when dbt flags a node as modified, but nothing needs to be run (for instance, in the case of metadata-only changes).

The run will be successful, but things may still break downstream. That is why it is recommended to include downstream models using state:modified+.

Seed files behaviour:

State comparison differs for seed files according to their size:

• Small seeds (< 1 Mib): included only when the contents change,

• Large seeds (>= 1 Mib): included only when the seed file path changes.

In our last post dedicated to data tests, we are going to cover the test command and how to define how dbt handles tests in dependencies.

The dbt test command

Once tests were declared and configured, you need to run dbt test to apply them and identify potentially failing records.

You can use the --select flag to run specific tests according to their type (data, unit, generic, or singular) and/or the model name.

Defining how dbt tests dependencies

Unlike other resources, tests upstream or downstream can be selected indirectly. You can use modes to choose how dbt handles tests in other models.

Eager mode (default)

This is the most inclusive option and the default mode. Which tests will be built?

• Tests referencing the selected nodes as well as those of their upstream AND downstream models, even if they don’t directly reference the selected nodes.

Cautious mode

This is the most exclusive option. The tests that are built are:

• Only the tests that exclusively reference the selected nodes.

Buildable mode

This is a middle ground between Eager and Caution. Useful if you want to build a subset of your DAG without running into failures caused by unbuilt nodes in Eager mode. Includes the following:

• Tests that reference the current node as well as those of its ancestors, even if they don’t reference the selected nodes.

Empty mode

Ignores all tests.

Let’s cover the possibilities around configuring your tests and deep-dive into customisation options to handle large datasets and set default paths for stored failures.

Where to define data test configurations

Data tests can be configured in:

1. under the config: method nested inside properties - this is for generic tests only.

2. inside a config() block within the test’s SQL definition.

3. in the dbt_project.yml file.

The config inside the dbt_project.yml file is always the last precedence, however the hierarchy differs for singular and generic tests:

• Generic tests: (1) takes precedence over (2)

• Singular test: (2) takes precedence over (1)

Resource-specific configurations

The following configs are available specifically for data tests:

Let’s define each one of these configs:

fail_calc:

All tests return the set of records that fail the assertion. By default, dbt returns the count(*) of records.

This config allows you to change this calculation. For instance, for a test that checks for duplicate records, you can set fail_calc to "case when count(*) > 0 then sum(n_records) else 0 end".

If this calculation returns an error, like a data type error, the test won’t pass or fail, but it will return an error.

limit:

Limit the number of failures returned, specifically useful for large datasets and when failures are being stored in the database.

Example: “limit: 1000”

severity, error_if, warn_if:

By default, when even a single record fails the assertion, the tests will produce errors and prevent the model from running. This config allows you to add some leniency to your tests.

When you set up the severity: config to error, dbt will look for the error_if and warn_if configs, which will set up the conditions to bring an error or a warning:

If severity: is set to warn, then dbt skips the error_if config and only considers warn_if. As with warnings of any nature, dbt will not fail the run, but you can promote warnings to errors using the --warn-error flag when running the models.

store_failures:

Optionally set a test to always or never store failures in the database. By default, the failed results will be stored in a schema named _dbt_test__audit, but this can be customised.

Ensure you have the correct permissions to create schemas in the database.

where:

Allows you to limit the records being tested. For instance, you can tell dbt to only test the assertion on records for which column A is not null.

This configuration generates a macro called get_where_subquery that will replace the source reference with a subquery:

For this config, you have access to {{ var( ) }} and {{ env_var( ) }} but not custom macros. This is because configs are evaluated before custom macros are compiled.

To use custom macros in the where: config, you can override the default get_where_subquery.

For instance, say you want to test only the latest partition:

Create the custom macro latest_partition.sql that identifies records of the latest partition:

Now, create a macro named get_where_subquery to override the default macro and call the custom macro you just created. Don’t forget to specify the test name this should refer to if you don’t want the get_where_subquery to be modified for all tests.

General configurations

• enabled: if set to False, dbt does not consider this resource part of the project.

• tags: add common tags to resources to apply commands to all in one go using the “tag:” method.

• meta: adds custom metadata for the resource to the manifest.json file and documentation.

• database, schema, alias: relevant for store_failures only to set a custom path for failed records.

We’ve learned what data tests are and how to implement them logically in your DAG. Now, we are going to understand how to declare the properties for data tests.

These properties allow you to correctly set up your tests and apply them to multiple columns.

dbt also offers some options in terms of naming these tests, which can make logs, artifacts, and database table names more logical.

Description

Use the data_tests property to define assertions about a column, table, or view. It can be used to define generic data tests, including the 4 built-in tests.

It can also be optionally used for singular data tests for documentation purposes using the “description” parameter.

Test-specific properties

Out-of-the-box generic tests require specific arguments for the column it’s being applied to. It’s also possible to test using expressions involving multiple columns.

Built-in generic tests:

These tests have to be applied at column level.

Not_null

This test only requires the data_tests property to declare the test and no further arguments are needed.

Unique

Similar to not_null, unique only has to be declared. However, it takes an optional “where” config to filter the rows this is applied to.

Accepted_values

This test requires no further configuration for strings. However, if you want your accepted values to be non-string values (like integers or booleans), you need an additional “quote” argument to be set to false.

Relationships

This test takes an argument “to” and a “field” that define which child table it should look for corresponding values from the parent table.

Please note that this test excludes null values from validation. If you want nulls to cause failures, use the not_null test.

Testing an expression:

When a data test involves multiple columns, it doesn’t make sense to place it under the “columns” key. In these cases, you apply the test to the model.

For instance, when using the dbt_utils.expression_is_true:

Custom test names: the “name” property

dbt will define the test names in the artifacts by concatenating the test name, the resource name and, if relevant, column name and arguments.

You may want to define a custom name for your tests to obtain a more recognisable name in the artifacts. For that, you can use the “name” property.

Besides showing in artifacts and logs, this custom name can be used by the “select” method to run only a specific data test.

You cannot have duplicate custom names for the same column. However, you can repeat them across different columns or models. In this case, the “select” method will run all tests under the same custom name.

You can also use custom names when you need to apply the same data test type to one column. By giving them custom names, dbt will know how to differentiate them.

Alias for “store_failures” database table

When switching “store_failures” on, dbt will store test results in a database object. By default, it takes the name of the test, or the custom name if defined, as the name of the database table.

If you’d like the database table to have a different name, you can set an alias for the test.

Using “test_name” to flatten config

dbt offers the option to define test properties using the “test_name” property to make your file easier to read. The result is the same.

Data tests are assumptions we make about resources in our project. For instance, we can configure a model to fail or issue a warning when certain preset requirements are not met.

dbt offers a few out-of-the-box solutions, but it is also possible to create custom tests to reflect specific business logic.

In this post, we will cover the reasons why you should add tests to your project and suggest a gradual implementation of data testing. Finally, we’ll go into the nitty-gritty of adding data tests to your DAG.

In the next posts, we will cover data test properties, configurations, and the dbt test command.

The importance of data testing

Whether you deal with internal or external stakeholders, trust in the data is fundamental to getting buy-in and support. Therefore, data professionals cannot afford the risk of sharing incorrect data.

When we are engineering a complex project, we could end up running countless models successfully without ever noticing that something is off.

Data testing helps us ensure that certain assumptions are met before models are built successfully - or at least throw a warning for less critical issues.

The built-in data testing tools in dbt enable you to check if:

• The SQL code is doing what it’s meant to do

• Assumptions about your source data are correct

• Anything changed in your source data that is impacting your assumptions

Introducing data tests gradually and sustainably

You don’t need to set up every data test under the sun just because they are available. dbt’s general rule of thumb goes for data testing too: don’t make your project unnecessarily complex.

dbt suggests the gradual introduction of tests following the phases below:

1) Simple test use cases

Initially, you might not be testing your data.

However, if you’re consistently running into data quality issues or you’re preparing to enhance your project’s complexity, it’s time to consider adding tests.

• Primary Keys: Unique & not_null tests help you identify values that mess with filters, joins, or aggregate calculations.

• Accepted values or relationship tests: for columns with predictable values, this test flags any new values that appear in the source data.

2) Preempting issues

As your project grows, you might want to start preparing for outliers or lack of freshness.

Here you can go beyond dbt’s out-of-the-box tests and into custom testing to spot and treat these corner cases in your data.

You can also consider configuring freshness so dbt alerts you when a source is stale. Source freshness was addressed in Checkpoint 2.

3) Tackle workflow testing

Once you’ve safeguarded your project, it’s time to expand testing into the pull requests with CI/CD jobs. These will be discussed further in this Checkpoint.

dbt also recommends creating a testing culture within the team with data tests consistently being added to new code and processes in place to debug test failures. I’d also add the usage of a good PR template to ensure data quality, another aspect that will be discussed later in this Checkpoint.

4) Avoid over-testing

At this stage, you could potentially find yourself drowning in warnings and errors generated by data tests.

Consider removing those warnings that you are consistently ignoring so your project only flags those that really deserve your attention. A periodic audit for deprecated fields or tests can be a good tactic.

You can also evaluate switching errors to warnings if you find that your project is delayed over failures that are not that severe.

Finally, consider the value for money of your tests: data testing may incur computing and development costs.

Adding tests to your DAG

What are data tests in dbt?

Firstly, it’s important to understand that, like most things in dbt, data tests are SQL queries. Their statement will pull a list of records that fail the test you set up.

There are two types of data tests in dbt:

Singular data tests

Singular tests are a custom SQL query that returns failing rows saved in a .sql file in your test directory. These are useful to test assumptions that involve specific business logic.

The SQL query should return the list of failing records and their relevant attributes. Remember to omit semicolons at the end of the statement.

You can use Jinja in singular testing, as shown in the ref( ) function above. The name of the file becomes the test name.

Any singular tests included in the test directory will automatically be summoned by the dbt test command.

They don’t need to be referenced or configured in .yml files. However, you may want to document them under the data_test block with a description:

Generic data tests

These are parameterised queries defined by a test block, like a macro, that can be referenced throughout your project. dbt comes with four generic tests out of the box.

Once defined and saved in the tests directory, this test has to be defined as a property of a given resource in their respective yml file.

The example above is simply checking a column for nulls. However, dbt already includes this type of testing and three others as a native feature.

The out-of-the-box generic tests assert that:

• unique: a column (or combination of columns) contains no duplicate values.

• not_null: a column contains no null values.

• accepted_values: all values in a column are in a set of possible values.

• relationships: each value in a given column exists in another table.

There are additional configurations available for tests, which will be covered later in this Checkpoint.

Besides the native data tests, dbt also offers the ability to write custom generic tests and import them from Packages.

We’ve arrived at the final part of our Practice Project - Checkpoint 4. This was definitely a heavy checkpoint, but at the end of this post you’ll see how mature our project looks now.

The next Checkpoint will cover data tests and deployment - lighter in content but no less important!

Python Models

Let’s create a simple Python model that calculates the lifetime value of each employee.

In real life, you wouldn’t use Python for such a banal calculation. SQL is always preferred on dbt. However, my Python skills are a bit rusty, so I’ll keep it simple.

The next step is to configure the newly created model. We are going to materialise it as a table.

Now, we are going to run the model. As usual, because I have billing disabled in BigQuery, I’m not able to run it successfully. There would be ways to run this locally, but it would involve more advanced features.

The important thing is that we understand the minimal requirements of Python model configuration, how to use the “model” function, and test the ability to reference sql models.

Exposures

We’re modeling all this data for our B2B company so that the end-users can access clean, consistent data via a visualisation tool such as Power BI or Tableau.

Creating the actual dashboard is out of scope here, but we can practice configuring a dashboard as an Exposure.

The first step is to configure our Exposure in an exposure.yml file:

Not all these configs are required and you can make it as robust or simple as you’d like.

Finally, we are going to run our new Exposure so it becomes a node in the DAG.

Please note I have a deprecation flag on, as dbt recently started requiring the docs config to be under a “config:” block.

After a successful run, you should now see the Exposure as part of your DAG. I’ll add a small detail: fact tables should be in a single layer, as per dbt’s best practices, so do what I say and not what I do!

Documentation

The last step of this very long Checkpoint is to add and configure documentation in our project.

Throughout our project, we’ve been adding descriptions to sources and other resources:

However, our fct_orders model is quite an important one and includes complex discount and VAT logic. Therefore, for that model, we’re going to include a doc block for a more thorough description.

For that, we need to create a docs.md (optionally in a docs folder within models), where we can store all doc blocks we may need.

In the fct_orders model, let’s replace the standard description we had in the properties.yml file with our doc bloc.

Finally, we can generate the docs (compile all the descriptions, metadata, and doc blocks) and then serve them to a bespoke webpage.

I’m using the IDE, so I don’t need to serve the docs. The next step is to click the docs button to see our docs website:

And there we have our brand new docs page. There are other ways to customise it, by creating an overview.md doc block to replace the text in the homepage, but we’ll keep it simple for now.

We can also see our doc block for fct_orders in action:

And finally, a complete visualisation of our DAG with colour-coded nodes.

Yes, yet another part of the Practice Project Checkpoint 4! And it’s not the last one.

I just started a new job and the time I have available for this Study Guide has drastically shrunk. So, forgive me for the multiple parts. I’m just glad I’ve been able to stay consistent.

In Part 4, we’ll tackle Grants and Snapshots. Next part, hopefully the last one, we’ll add Exposures, Python models, and documentation to the project.

Grants

For this Practice Project, we will define grant permissions in YAML files.

Let’s think of this scenario: we need to limit access to the “dim_employee” model as it shows confidential information on the employees.

Before we get started, it’s important to understand that each adapter will have specific terminology that needs to be used. For instance, in Big Query, which is the adapter I am using, the “select” role is called “roles/bigquery.dataViewer”.

Setting up grants

We’ll first set up the grant config for the “dim_employee” model in the dbt_project.yml file.

Below, I gave a fictitious user permission to query my table in BigQuery.

Conditional grant with Jinja

We can also use Jinja to set conditional permissions.

Even though the model was built successfully for both grants, when I queried the object privileges for “dim_employee” on BigQuery, I couldn’t get any data to return. I could not get this user to come up under my IAM permissions either. Not sure what this means, but I had to move on.

Snapshots

We are using a dataset created by Leo Godin on Medium, and I’m not entirely sure whether company or employee details change over time.

However, for the sake of our example, we are going to create 2 Snapshots to record changes to company and employee data.

Adding live employee and company data

First things first, we are going to connect our employee and company data to the live public database that Godin set up - so far, we’ve been keeping that data static. Don’t forget to run these models and their downstreams once done.

Defining Snapshot strategy

We don’t have an “updated_at” field we can go by in our data, so we’ll adopt the “check” strategy.

It is recommended to store your snapshots in a different schema, as once dropped, you cannot recover the historical changes lost. So we will define it to be built in our prod schema.

Also, dbt recommends basing snapshots on staging models that have already been cleaned rather than the raw data.

Run the “dbt snapshot” command and check that the two tables were created on dbt and in the warehouse.

Verifying Snapshots

Upon running the command, you will see the tables being created in the warehouse. On the first run, dbt simply copies the existing records and adds accessory columns like “dbt_scd_id”, “dbt_updated_at”, and “dbt_valid_from”.

Upon subsequent runs, dbt will check which records have changed or if any new records have been created. The updated record and any new records will be inserted into the snapshot table.

Frequent jobs for Snapshots

In a real-life scenario, you’d need to have a frequent, scheduled job to run the snapshots to ensure you’re capturing all changes.

In my case, since I don’t have billing enabled on BigQuery, the Snapshots wouldn’t quite work the way they’re supposed to, so I’ll skip this step for this Practice Project.

Some configurations look straightforward in the documentation but when you actually try to implement them in a complex project, you run into all sorts of bugs.

This was the case with Model Governance features. I had some trouble setting up the access modifier correctly and, unfortunately, could not implement model versioning (I explained the bugs below).

This goes to show the importance of practising. Running into bugs is very frustrating, but they help us really grasp the workings behind dbt.

Model Governance

For this practice step, we will add some model governance features to our project.

Here, we will add all features for practice, but in a real-life scenario, you would only add these features as needed. In data modelling, we always strive to reduce unnecessary complexity.

Model access

This is the ability to make models public or private to control who can ref them.

First, we need to define a group. We already have some groups defined by department, like the “customer_success” group, which holds the “fct_company” and “fct_company_trend” models.

By default, all groups are protected, so let’s change this group to private and try to ref one of its models from outside the group.

I then created a new model and tried to reference one of the models. Upon compiling, I got the expected error.

Model contracts

They restrict the shape of a model in terms of column names, data types, and constraints.

Following dbt’s recommendation, we will enforce some contracts in our fact tables. For instance, fct_orders could use some contracts, as we started feeding it with live data in the Practice Project 4 - Step 2.

Firstly, let’s add the contract and constraints to the dbt_project.yml file. Please note that I’m using BigQuery and, while it enforces schema contracts, it doesn’t enforce constraints.

I modified the fct_orders table by selecting only two of its columns to see it fail.

Upon building the model, I get the model contract error:

Model namespaces

Delineate ownership boundaries and responsibilities through naming structures.

We’ve been working with namespaces throughout the Practice Project. For instance, when we added groups and access modifiers to the customer_success subdirectories above, we were using namespaces.

Also, when we use the source function, we are declaring the source namespace. In the example below, it would be “dbt_fake_live”.

Model versions

Versioning for the models, allowing for adjustments to be made without breaking access for the end user.

Now, for this one, I must be honest: I could not get it to work.

I tried versioning fct_orders and set up the configuration as per the documentation. However, dbt refused to read “fct_orders” as the v1 model. I tried using the defined_in optional parameter, renaming fct_orders to fct_orders_v1. Nothing worked.

Upon trying to compile the v1 (dbt compile -s fct_orders:v1), dbt seemed to see two “fct_orders” models, one versioned and one unversioned.

Also, interestingly, as soon as I created the fct_orders_v2 file, I got a server status error. But when I edited the file name to fct_orders__v2 (with double underscore), the server status went back to Ready. Go figure.

I will revisit this eventually, but I needed to move on with the Practice Project. I wanted to be honest and show you how, even after reviewing documentation thoroughly, some configurations are tricky to set up in a real-life environment.

If anyone’s got any clue as to what could be causing this issue, send me a message or leave a comment!

Incremental materialisation is one of the trickier configurations of dbt. It requires attention to detail as the placement of the configs affects how and when the incremental rows will be processed.

I covered only the essentials in incremental materialisations in this post due to a limitation of my adapter’s free tier. I think a real-life scenario would present more challenges than I was able to replicate here.

Still, this is good practice to understand the intricacies of this type of materialisation and the many ways in which it can be configured.

Incorporating live data into our project:

So far, we have been working with static data in our Practice Project. Now, thanks to Leo Godin’s efforts in setting this fake database up, we are going to add live data.

Our project will now receive new orders every day. We will assume no new employees, products, or companies are added. Only new orders.

Setting up the new connection:

Godin’s data is hosted in a public BigQuery dataset that we can directly add as a source to our project. You can view documentation on the full dataset here.

Replacing the source of our orders table:

Now, we are going to replace the orders source in the “stg_orders” model. Optionally, you can also remove the static orders table from the source.yml file or use the “enable: false” property to remove it from the project.

Configuring the incremental materialisation:

You want to add the incremental strategy in the layer where the heaviest transformations take place. This way, these costly operations will only be applied to new rows at each run.

In our case, the optimal model is int_orders_detail. We are also going to implement a merge strategy and limit the scan of new records to orders from 2025. We are taking the assumption that orders from previous years never change.

Please note that I’m working on BigQuery’s free tier in this project, which doesn’t support DML queries. Therefore, even with the correct configurations, the “dbt build” command will still fail. However, the logs will show us that dbt tried to implement the incremental materialisation.

dbt_project.yml configuration

According to the documentation, you can add the incremental configurations to the dbt_project.yml or the model itself.

Upon trying to build the models, the command fails and the logs show that dbt tried to run a DML query, but my adapter has billing disabled.

In-model configuration

Using a config block, we can set all the configs for the incremental materialisation in the block itself. Remember that this block can be placed strategically in the code (for example, after the data has been filtered).

The logs are even more detailed in this case. You can see dbt tried to merge the new records, applied our predicates, and only searched for new records within orders from 2025.

We can also apply a simpler configuration to your incremental materialisation using the is_incremental macro:

While incremental_predicates filter the rows that the warehouse will consider during the MERGE step, is_incremental( ) filters the rows selected from your source before the merge happens.

The past 2 weeks have been hectic as I started a new job AND moved flats in the same week - I do not recommend it!

I did slow down with the posts a bit, but I have no intention of abandoning this project. With a full-time job, I’ll obviously need to adapt my schedule, but I aim to post at least once a week.

Speaking of the new job, in addition to the study notes from the past two weeks, I've included some valuable tips for landing a job in the age of AI recruiting below. Next week, I’ll share more about my new job itself.

Study notes added:

We finished the topics for Checkpoint 4 and began applying our learnings to the Practice Project. We covered a lot of topics in this Checkpoint, so the Practice posts will be broken into a few different parts.

A full list of the study notes is available in the study guide.

Here’s how to land a job in the age of AI recruiting

TL;DR: Work on side projects (like this dbt Study Guide) and talk about them on LinkedIn to increase your profile visibility.

I quit my data job in July 2024 to freelance and upskill. A year later, I felt the need to put my new skills into practice, so I began job hunting.

I started searching while in Europe, but the market was flat. After months of insisting, I made the tough call to return to Brazil—where I got hired in under a month.

However, even though the Brazilian tech market was booming, I never landed an interview for the dozens of jobs I proactively applied for. But every week, recruiters kept approaching me on LinkedIn. One of those messages led to the job I just started.

Sure, my 10-year on-and-off experience in data and a recent Big 4 contract helped to attract the recruiters. But it’s also worth noting that since launching my Study Guide, my LinkedIn visibility increased 9×.

The first big spike came when I announced the dbt Study Guide on 30th July (23.5k impressions). The next jump happened when I posted about speaking at the dbt Labs HQ in Dublin.

During this period, I gained 699 new connections—loads of aspiring data pros, but over half were senior professionals and people in IT services and consulting. LinkedIn won’t show how many recruiters follow me, but they definitely sit within these groups.

The bottom line:

AI has transformed job hunting. Candidates can now blast tailored CVs at scale, and HR teams use AI to filter the flood. Speaking to a human about your skills is harder than ever.

So, you need to let the recruiters come to you.

Show your work publicly. Share your learning, your projects, your Zoomcamps—whatever you’re building while you’re job searching.

Don’t stand still during your job search, applying mindlessly. Stand out and show yourself.

(Speaking of which, DataTalks Club has a new cohort for their Data Engineering zoomcamp coming up soon!)

Does this make sense to you? I would love to hear from you here or on LinkedIn!

XX

Incremental materialisation:

• add live data

• configure with incremental_predicates, unique_id

• testing the different incremental strategies

• on_schema_change

We have covered macros in the context of Packages in a previous post. For this post, we will touch on how to create custom macros using Jinja.

We’ll also take the opportunity to understand how Jinja works in the dbt context and some best practices for using Jinja & Macros.

What is Jinja?

Jinja is a templating language that enhances the capabilities of SQL. dbt uses it in native functions like {{ config() }} and {{ ref() }}. But you can also use it to create bespoke macros or within the models.

These are some examples of what Jinja enables you to do:

• Using if statements and for loops

• Using environment variables for production deployments

• Change the build according to the target

• Pivot tables

• Abstract SQL codes into reusable macros

If you need support using Jinja, you can check out its own documentation and the dbt-specific functions, like ref and source. But the general syntax for Jinja is below:

• Expressions {{ … }} : when you want to output a string.

• Statements {{% … %}} : used for if statements, for loops, or variable control.

• Comments {{# … #}} : used for comments.

• You can also use a minus sign to remove unwanted whitespace in the compiled code, for example {{- … -}} or {{%- … -%}}

Jinja within models

Within models, you can use Jinja for injecting variables, environment-based logic, and references, before dbt runs the model. Jinja is processed at compile time, so you can use “dbt compile” to ensure that your code is compiling correctly.

Jinja within macros

Macros are the dbt equivalent of functions. Macros are defined in SQL files stored in the “macros” directory or any other directory defined in “macros-paths”.

They use Jinja to create reusable code to be used across multiple models.

Defining and using macros

This is how a macro would be defined. A file can contain more than one macro:

You can then use it as a function in the SQL model, entering any necessary arguments:

Finally, this is what the compiled code would look like:

Macros properties

Macros are not a resource like models, seeds, and snapshots. However, dbt allows them certain properties for documentation purposes.

Macro properties can only be defined in a properties.yml file stored within the “macros” subdirectory.

• name (required): must match the name of the macro file.

• description (optional): a string that describes the macro for dbt Docs

• docs (optional): shows or hides macros from dbt Docs

• arguments (optional): defines the arguments the macro accepts - again, for documentation purposes only, it does not affect how the macro runs.

Best practices for Jinja & Macros

Readability vs. reusability

It’s important to strike a balance between reusable code and readability. Too much Jinja in the model can make it hard for others to read.

Variables

Set the variables at the top of the macro/model.