From ce769b3798774f63631e3252aaf2a5372dbf3146 Mon Sep 17 00:00:00 2001 From: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> Date: Wed, 30 Sep 2026 10:49:27 +0200 Subject: [PATCH 1/4] doc(concepts-managed-models): reduce repetition, clarify automatic updates, standardize capitalization, and fix typos Signed-off-by: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> --- docs/concepts/models/managed_models.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/concepts/models/managed_models.md b/docs/concepts/models/managed_models.md index 786c6aa89d..e16e690ce0 100644 --- a/docs/concepts/models/managed_models.md +++ b/docs/concepts/models/managed_models.md @@ -1,15 +1,13 @@ # Managed models -Unlike normal tables where the user is responsible for managing the data within the table, some database engines have a concept of a table where the engine itself ensures that the data within the table is up to date. These tables are typically based on a query that reads from other tables within the database. Each time these other tables are updated, the database will ensure that the managed table reflects the changes without the user having to do anything special (such as issue a `REFRESH` command). +Some database engines support tables whose data is kept up to date by the engine itself, rather than by the user. These tables are typically defined by a query that reads from other tables in the database. When the source tables are updated, the engine automatically updates the managed table to reflect the changes, without requiring the user to issue a `REFRESH` command. -Under the hood, each supported database engine achieves this in a slightly different way but most of them have background processes that run and automatically keep the tables up to date, within the parameters you define when you create the table. +Each supported database engine handles these updates differently, but most use background processes to keep the tables up to date according to the parameters you specify when creating the table. -For supported engines, we expose this functionality through Managed models. This indicates to SQLMesh that the underlying database engine will ensure that the data remains up to date and all SQLMesh needs to do is maintain the schema. - -Due to this, managed models would typically be built off an [External Model](./external_models.md) rather than another SQLMesh model. Since SQLMesh already ensures that models it's tracking are kept up to date, the main benefit of managed models comes when they read from external tables that arent tracked by SQLMesh. +SQLMesh exposes this functionality through managed models for supported engines. Setting a model's kind to `MANAGED` tells SQLMesh that the database engine is responsible for keeping the data up to date and that SQLMesh only needs to maintain the schema. Managed models are therefore typically built on an [external model](./external_models.md) rather than another SQLMesh model. !!! warning "Not supported in Python models" - Python models do not support the `MANAGED` [model kind](./model_kinds.md) - use a SQL model isntead. + Python models do not support the `MANAGED` [model kind](./model_kinds.md). Use a SQL model instead. ## Difference from materialized views The difference between an Managed model and a materialized view is down to semantics and in some engines there is no difference. From 8df20c9efb9aec29e186b2e500bc6a3c14933c07 Mon Sep 17 00:00:00 2001 From: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> Date: Wed, 30 Sep 2026 11:49:18 +0200 Subject: [PATCH 2/4] doc(guides-models): remove unneeded graphviz dependency, extend DAG description Signed-off-by: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> --- docs/guides/models.md | 22 ++++------------------ 1 file changed, 4 insertions(+), 18 deletions(-) diff --git a/docs/guides/models.md b/docs/guides/models.md index 074e581937..04e12c4866 100644 --- a/docs/guides/models.md +++ b/docs/guides/models.md @@ -234,26 +234,12 @@ To delete a model: ## Viewing the DAG of a project's models ---- - -Before generating a DAG, ensure that you have already installed the graphviz package. - -To install the package with `pip`, enter the following command: - -```bash -pip install graphviz -``` +A directed acyclic graph (DAG) shows the dependencies between your project's models. Each node represents a model, and arrows point from upstream models to the downstream models that depend on them. SQLMesh can generate an HTML file showing your project's DAG. -Alternatively, enter the following command to install graphviz with `apt-get`: +To generate the DAG, run the following command from the root of your SQLMesh project: ```bash -sudo apt-get install graphviz +sqlmesh dag FILE ``` ---- - -To view the DAG, enter the following command: - -`sqlmesh dag FILE` - -An html file containing your project's DAG will be placed at the root of your project folder. The DAG can then be viewed by opening this file in your browser. \ No newline at end of file +Replace `FILE` with an output filename, such as `dag.html`. Open the generated HTML file in a browser to view the DAG. \ No newline at end of file From 547ac6a9d88f5da747cddb3455b50b2e3fab8b90 Mon Sep 17 00:00:00 2001 From: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> Date: Wed, 30 Sep 2026 13:39:33 +0200 Subject: [PATCH 3/4] doc(concepts-testing): clarify sections Intro and Running tests. Signed-off-by: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> --- docs/concepts/tests.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/concepts/tests.md b/docs/concepts/tests.md index 8bf0fe0cbf..e679cca0c2 100644 --- a/docs/concepts/tests.md +++ b/docs/concepts/tests.md @@ -1,12 +1,12 @@ # Testing -Testing allows you to protect your project from regression by continuously verifying that the output of each model matches your expectations. Unlike [audits](audits.md), tests are executed either on demand (for example, as part of a CI/CD job or via [`sqlmesh test`](../reference/cli.md#test)) or when a new [plan](plans.md) is created. +Testing helps protect your project from regressions by verifying that model transformations produce the expected outputs for specified inputs. -By default, `sqlmesh plan` runs all unit tests. Use `--test-changed-only` to run tests only for models included in the plan (added, modified, or restated), or `--skip-tests` to run none. With both `--select-model` and `--test-changed-only`, tests run only for selected models that changed. +As in software unit testing, each test specifies a model, example inputs, and expected outputs. SQLMesh executes the model's logic using these inputs, compares the results with the expected outputs, and reports any discrepancies. -Similar to unit testing in software development, SQLMesh evaluates the model's logic against predefined inputs and then compares the output to expected outcomes provided as part of each test. +A comprehensive test suite helps data practitioners make changes with confidence by checking that models continue to behave as expected. -A comprehensive suite of tests can empower data practitioners to work with confidence, as it allows them to ensure models behave as expected after changes have been applied to them. +Unlike [audits](./audits.md), which validate model outputs against data quality expectations, tests verify transformation logic using predefined inputs and expected outputs, often with small, synthetic datasets. ## Creating tests @@ -414,7 +414,9 @@ test_example_full_model: ## Running tests -Tests run automatically every time a new [plan](plans.md) is created, but they can also be executed on demand as described in the following sections. +Tests can be run directly with [`sqlmesh test`](../reference/cli.md#test) (as described in the following sections) or as part of `sqlmesh plan` (see [plans](plans.md)), which runs tests automatically before creating a new plan. + +By default, `sqlmesh plan` runs all unit tests. Use `--test-changed-only` to run tests only for models included in the plan (added, modified, or restated), or `--skip-tests` to run none. With both options `--select-model` and `--test-changed-only` specified, tests run only for selected models that changed. ### Testing using the CLI From e71a703d488f2acd3ed30e2d9384d738535aab22 Mon Sep 17 00:00:00 2001 From: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> Date: Wed, 30 Sep 2026 14:02:51 +0200 Subject: [PATCH 4/4] doc(concepts-auditing): clarify the intro Signed-off-by: Sergiy Kolesnikov <6048022+SergiyKolesnikov@users.noreply.github.com> --- docs/concepts/audits.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/concepts/audits.md b/docs/concepts/audits.md index c7c7cbd190..4f14a57c4d 100644 --- a/docs/concepts/audits.md +++ b/docs/concepts/audits.md @@ -1,11 +1,12 @@ # Auditing -Audits are one of the tools SQLMesh provides to validate your models. Along with [tests](tests.md), they are a great way to ensure the quality of your data and to build trust in it across your organization. -Unlike tests, audits are used to validate the output of a model after every run. When you apply a [plan](./plans.md), SQLMesh will automatically run each model's audits. +Audits validate model outputs against predefined data quality expectations. Along with [tests](tests.md), they help ensure data quality and build trust in your data across your organization. -By default, SQLMesh will halt plan application when an audit fails so potentially invalid data does not propagate further downstream. This behavior can be changed for individual audits - refer to [Non-blocking audits](#non-blocking-audits). +Unlike tests, which verify a model's transformation logic using predefined inputs and expected outputs, audits check that the model's actual output data meets the specified quality criteria. -A comprehensive suite of audits can identify data issues upstream, whether they are from your vendors or other teams. Audits also empower your data engineers and analysts to work with confidence by catching problems early as they work on new features or make updates to your models. +When you apply a [plan](./plans.md), SQLMesh automatically runs each model's audits. By default, SQLMesh halts plan application when an audit fails so potentially invalid data does not propagate further downstream. This behavior can be changed for individual audits; refer to [Non-blocking audits](#non-blocking-audits). + +A comprehensive suite of audits can identify data issues upstream, whether they originate with vendors or other teams. Audits also empower your data practitioners to work with confidence by catching data quality issues early as they work on new features or make updates to your models. **NOTE**: For incremental by time range models, audits are only applied to intervals being processed - not for the entire underlying table.