refactors; improve error handling and messages; update docs

Author: themisvaltinos

docs/guides/model_selection.md

@@ -2,7 +2,7 @@
 
 This guide describes how to select specific models to include in a SQLMesh plan, which can be useful when modifying a subset of the models in a SQLMesh project.
 
-Note: the selector syntax described below is also used for the SQLMesh `plan` [`--allow-destructive-model` selector](../concepts/plans.md#destructive-changes).
+Note: the selector syntax described below is also used for the SQLMesh `plan` [`--allow-destructive-model` selector](../concepts/plans.md#destructive-changes) and for the `table_diff` command to [diff a selection of models](./tablediff.md#diffing-multiple-models-across-environments).
 
 ## Background
 

docs/guides/tablediff.md

@@ -122,6 +122,77 @@ Under the hood, SQLMesh stores temporary data in the database to perform the com
 The default schema for these temporary tables is `sqlmesh_temp` but can be changed with the `--temp-schema` option.
 The schema can be specified as a `CATALOG.SCHEMA` or `SCHEMA`.
 
+
+## Diffing multiple models across environments
+
+SQLMesh allows you to compare multiple models across environments at once using model selection expressions. This is useful when you want to validate changes across a set of related models or the entire project.
+
+To diff multiple models, use the `--select-model` (or `-m` for short) option with the table diff command:
+
+```bash
+sqlmesh table_diff prod:dev --select-model "sqlmesh_example.*"
+```
+
+When diffing multiple models, SQLMesh will:
+
+1. Show which models exist only in the source environment
+2. Show which models exist only in the target environment
+3. Show which models exist in both environments but have no differences
+4. Compare the models that have differences and display them
+
+The `--select-model` option supports a powerful selection syntax that lets you choose models using patterns, tags, dependencies and git status. For complete details, see the [model selection guide](./model_selection.md).
+
+Here are some common patterns you can use:
+
+### Wildcard Patterns
+- `*` - All models in the project
+- `sqlmesh_example.*` - All models in the sqlmesh_example schema
+
+### Upstream/Downstream Selection
+- `+model_name` - Select the model and its upstream dependencies
+- `model_name+` - Select the model and its downstream dependencies
+- `+model_name+` - Select the model and both its upstream and downstream dependencies
+
+### Tag-based Selection
+- `tag:finance` - All models with the "finance" tag
+- `tag:reporting*` - All models with tags starting with "reporting"
+
+### Git-based Selection
+- `git:feature` - Select models whose files have changed compared to main branch, including:
+  - Untracked files (new files not in git)
+  - Uncommitted changes in working directory
+  - Committed changes different from main branch
+- `+git:feature` - Select changed models and their upstream dependencies
+- `git:feature+` - Select changed models and their downstream dependencies
+
+> Note: Git-based selection excludes deleted files and respects your `.gitignore` settings.
+
+### Logical Operators
+You can combine multiple selectors using logical operators:
+- `&` (AND): Both conditions must be true
+- `|` (OR): Either condition must be true
+- `^` (NOT): Negates a condition
+
+#### Complex Selection Examples
+- `(tag:finance & ^tag:deprecated)` - Models with finance tag that don't have deprecated tag
+- `(+model_a | model_b+)` - Model A and its upstream deps OR model B and its downstream deps
+- `(tag:finance & git:main)` - Changed models that also have the finance tag
+- `^(tag:test) & metrics.*` - Models in metrics schema that don't have the test tag
+
+### Multiple selectors
+
+You can also combine multiple selectors in a single command:
+
+```bash
+sqlmesh table_diff prod:dev -m "tag:finance" -m "metrics.*_daily"
+```
+
+When multiple selectors are provided, they are combined with OR logic, meaning a model matching any of the selectors will be included.
+
+All the standard table diff options like `--show-sample` work with multiple model diffing. The comparisons are executed concurrently for better performance when dealing with a large of project or many models.
+
+> Note: All models being compared must have their `grain` defined, as this is used to perform the join between the tables in the two environments.
+
 ## Diffing tables or views
 
 Compare specific tables or views with the SQLMesh CLI interface by using the command `sqlmesh table_diff [source table]:[target table]`.

docs/reference/cli.md

@@ -529,7 +529,7 @@ Options:
 ```
 Usage: sqlmesh table_diff [OPTIONS] SOURCE:TARGET [MODEL]
 
-  Show the diff between two tables.
+  Show the diff between two tables or multiple models across two environments.
 
 Options:
   -o, --on TEXT            The column to join on. Can be specified multiple
@@ -548,6 +548,7 @@ Options:
   --temp-schema TEXT       Schema used for temporary tables. It can be
                            `CATALOG.SCHEMA` or `SCHEMA`. Default:
                            `sqlmesh_temp`
+  -m, --select-model TEXT  Select specific models to table diff.
   --help                   Show this message and exit.
 ```
 

docs/reference/notebook.md

@@ -293,7 +293,7 @@ Create a schema file containing external model schemas.
 %table_diff [--on [ON ...]] [--skip-columns [SKIP_COLUMNS ...]]
                 [--model MODEL] [--where WHERE] [--limit LIMIT]
                 [--show-sample] [--decimals DECIMALS] [--skip-grain-check]
-                [--temp-schema SCHEMA]
+                [--temp-schema SCHEMA] [--select-model [SELECT_MODEL ...]]
                 SOURCE:TARGET
 
 Show the diff between two tables.
@@ -320,6 +320,8 @@ options:
   --skip-grain-check    Disable the check for a primary key (grain) that is
                         missing or is not unique.
   --temp-schema SCHEMA  The schema to use for temporary tables.
+  --select-model <[SELECT_MODEL ...]>
+                        Select specific models to diff using a pattern.
 ```
 
 #### model

sqlmesh/cli/main.py

@@ -897,7 +897,7 @@ def create_external_models(obj: Context, **kwargs: t.Any) -> None:
     "-m",
     type=str,
     multiple=True,
-    help="Select specific model that should be diffed.",
+    help="Specify one or more models to data diff. Use wildcards to diff multiple models. Ex: '*' (all models with applied plan diffs), 'demo.model+' (this and downstream models), 'git:feature_branch' (models with direct modifications in this branch only)",
 )
 @click.pass_obj
 @error_handler

sqlmesh/core/console.py

@@ -244,7 +244,7 @@ def start_table_diff_model_progress(self, model: str) -> None:
         """Start table diff model progress"""
 
     @abc.abstractmethod
-    def stop_table_diff_progress(self) -> None:
+    def stop_table_diff_progress(self, success: bool) -> None:
         """Stop table diff progress bar"""
 
     @abc.abstractmethod
@@ -714,7 +714,7 @@ def start_table_diff_progress(self, models_to_diff: int) -> None:
     def start_table_diff_model_progress(self, model: str) -> None:
         pass
 
-    def stop_table_diff_progress(self) -> None:
+    def stop_table_diff_progress(self, success: bool) -> None:
         pass
 
     def show_table_diff_details(
@@ -2056,12 +2056,17 @@ def update_table_diff_progress(self, model: str) -> None:
             model_task_id = self.table_diff_model_tasks[model]
             self.table_diff_model_progress.remove_task(model_task_id)
 
-    def stop_table_diff_progress(self) -> None:
+    def stop_table_diff_progress(self, success: bool) -> None:
         if self.table_diff_progress_live:
             self.table_diff_progress_live.stop()
             self.table_diff_progress_live = None
             self.log_status_update("")
-            self.log_success(f"{GREEN_CHECK_MARK} Table diff completed")
+
+            if success:
+                self.log_success(f"Table diff completed successfully!")
+            else:
+                self.log_error("Table diff failed!")
+
         self.table_diff_progress = None
         self.table_diff_model_progress = None
         self.table_diff_model_tasks = {}
@@ -2292,6 +2297,8 @@ def show_table_diff(
             fully_matched = []
             for table_diff in table_diffs:
                 if (
+                    table_diff.schema_diff().source_schema == table_diff.schema_diff().target_schema
+                ) and (
                     table_diff.row_diff(
                         temp_schema=temp_schema, skip_grain_check=skip_grain_check
                     ).full_match_pct

sqlmesh/core/context.py

@@ -1612,7 +1612,16 @@ def table_diff(
             if not target_env:
                 raise SQLMeshError(f"Could not find environment '{target}'")
 
-            selected_models = self._new_selector().expand_model_selections(select_models)
+            try:
+                selected_models = self._new_selector().expand_model_selections(select_models)
+                if not selected_models:
+                    criteria = ", ".join(f"'{c}'" for c in select_models)
+                    self.console.log_status_update(
+                        f"No models matched the selection criteria: {criteria}"
+                    )
+            except Exception as e:
+                raise SQLMeshError(e)
+
             models_to_diff: t.List[
                 t.Tuple[Model, EngineAdapter, str, str, t.Optional[t.List[str] | exp.Condition]]
             ] = []
@@ -1638,7 +1647,10 @@ def table_diff(
                 elif target_snapshot is None and source_snapshot:
                     models_in_target.append(model_fqn)
                 elif target_snapshot and source_snapshot:
-                    if source_snapshot.fingerprint != target_snapshot.fingerprint:
+                    if (
+                        source_snapshot.fingerprint.data_hash
+                        != target_snapshot.fingerprint.data_hash
+                    ):
                         # Compare the virtual layer instead of the physical layer because the virtual layer is guaranteed to point
                         # to the correct/active snapshot for the model in the specified environment, taking into account things like dev previews
                         source = source_snapshot.qualified_view_name.for_environment(
@@ -1668,32 +1680,37 @@ def table_diff(
                     )
                     raise SQLMeshError(
                         f"SQLMesh doesn't know how to join the tables for the following models:\n{model_names}\n"
-                        "\nPlease specify the `grains` in each model definition."
+                        "\nPlease specify the `grain` in each model definition. Must be unique and not null."
                     )
 
                 self.console.start_table_diff_progress(len(models_to_diff))
-                tasks_num = min(len(models_to_diff), self.concurrent_tasks)
-                table_diffs = concurrent_apply_to_values(
-                    list(models_to_diff),
-                    lambda model_info: self._model_diff(
-                        model=model_info[0],
-                        adapter=model_info[1],
-                        source=model_info[2],
-                        target=model_info[3],
-                        on=model_info[4],
-                        source_alias=source_env.name,
-                        target_alias=target_env.name,
-                        limit=limit,
-                        decimals=decimals,
-                        skip_columns=skip_columns,
-                        where=where,
-                        show=show,
-                        temp_schema=temp_schema,
-                        skip_grain_check=skip_grain_check,
-                    ),
-                    tasks_num=tasks_num,
-                )
-                self.console.stop_table_diff_progress()
+                try:
+                    tasks_num = min(len(models_to_diff), self.concurrent_tasks)
+                    table_diffs = concurrent_apply_to_values(
+                        list(models_to_diff),
+                        lambda model_info: self._model_diff(
+                            model=model_info[0],
+                            adapter=model_info[1],
+                            source=model_info[2],
+                            target=model_info[3],
+                            on=model_info[4],
+                            source_alias=source_env.name,
+                            target_alias=target_env.name,
+                            limit=limit,
+                            decimals=decimals,
+                            skip_columns=skip_columns,
+                            where=where,
+                            show=show,
+                            temp_schema=temp_schema,
+                            skip_grain_check=skip_grain_check,
+                        ),
+                        tasks_num=tasks_num,
+                    )
+                    self.console.stop_table_diff_progress(success=True)
+                except:
+                    self.console.stop_table_diff_progress(success=False)
+                    raise
+
         else:
             table_diffs = [
                 self._table_diff(

sqlmesh/magics.py

@@ -690,7 +690,7 @@ def create_external_models(self, context: Context, line: str) -> None:
         "--select-model",
         type=str,
         nargs="*",
-        help="Select specific model changes that should be included in the plan.",
+        help="Specify one or more models to data diff. Use wildcards to diff multiple models. Ex: '*' (all models with applied plan diffs), 'demo.model+' (this and downstream models), 'git:feature_branch' (models with direct modifications in this branch only)",
     )
     @argument(
         "--skip-grain-check",

sqlmesh/utils/git.py

@@ -27,7 +27,23 @@ def _execute_list_output(self, commands: t.List[str], base_path: Path) -> t.List
         return [(base_path / o).absolute() for o in self._execute(commands).split("\n") if o]
 
     def _execute(self, commands: t.List[str]) -> str:
-        result = subprocess.run(["git"] + commands, cwd=self._work_dir, stdout=subprocess.PIPE)
+        result = subprocess.run(
+            ["git"] + commands,
+            cwd=self._work_dir,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            check=False,
+        )
+
+        # If the Git command failed, extract and raise the error message in the console
+        if result.returncode != 0:
+            stderr_output = result.stderr.decode("utf-8").strip()
+            error_message = next(
+                (line for line in stderr_output.splitlines() if line.lower().startswith("fatal:")),
+                stderr_output,
+            )
+            raise RuntimeError(f"Git error: {error_message}")
+
         return result.stdout.decode("utf-8").strip()
 
     @cached_property