preserve the semantics of the 'creating' runtime stage

Author: izeigerman

docs/concepts/macros/macro_variables.md

@@ -130,8 +130,8 @@ SQLMesh provides additional predefined variables used to modify model behavior b
 
 * @runtime_stage - A string value denoting the current stage of the SQLMesh runtime. Typically used in models to conditionally execute pre/post-statements (learn more [here](../models/sql_models.md#optional-prepost-statements)). It returns one of these values:
     * 'loading' - The project is being loaded into SQLMesh's runtime context.
-    * 'creating' - The model tables are being created without inserting data.
-    * 'evaluating' - The model query logic is being evaluated.
+    * 'creating' - The model tables are being created for the first time. The data may be inserted during table creation.
+    * 'evaluating' - The model query logic is evaluated, and the data is inserted into the existing model table.
     * 'promoting' - The model is being promoted in the target environment (view created during virtual layer update).
     * 'demoting' - The model is being demoted in the target environment (view dropped during virtual layer update).
     * 'auditing' - The audit is being run.

sqlmesh/core/snapshot/evaluator.py

@@ -707,12 +707,15 @@ def _evaluate_snapshot(
             not _intervals(snapshot, deployability_index) or not target_table_exists
         ) and batch_index == 0
 
+        # Use the 'creating' stage if the table doesn't exist yet to preserve backwards compatibility with existing projects
+        # that depend on a separate physical table creation stage.
+        runtime_stage = RuntimeStage.EVALUATING if target_table_exists else RuntimeStage.CREATING
         common_render_kwargs = dict(
             start=start,
             end=end,
             execution_time=execution_time,
             snapshot=snapshot,
-            runtime_stage=RuntimeStage.EVALUATING,
+            runtime_stage=runtime_stage,
             **kwargs,
         )
         create_render_kwargs = dict(

tests/core/test_context.py

@@ -1776,14 +1776,14 @@ def test_plan_environment_statements(tmp_path: pathlib.Path):
 );
 
 @IF(
-  @runtime_stage = 'evaluating',
+  @runtime_stage IN ('evaluating', 'creating'),
   SET VARIABLE stats_model_start = now()
 );
 
 SELECT 1 AS cola;
 
 @IF(
-  @runtime_stage = 'evaluating',
+  @runtime_stage IN ('evaluating', 'creating'),
   INSERT INTO analytic_stats (physical_table, evaluation_start, evaluation_end, evaluation_time)
   VALUES (@resolve_template('@{schema_name}.@{table_name}'), getvariable('stats_model_start'), now(), now() - getvariable('stats_model_start'))
 );
@@ -1849,11 +1849,11 @@ def access_adapter(evaluator):
 
     assert (
         model.pre_statements[0].sql()
-        == "@IF(@runtime_stage = 'evaluating', SET VARIABLE stats_model_start = NOW())"
+        == "@IF(@runtime_stage IN ('evaluating', 'creating'), SET VARIABLE stats_model_start = NOW())"
     )
     assert (
         model.post_statements[0].sql()
-        == "@IF(@runtime_stage = 'evaluating', INSERT INTO analytic_stats (physical_table, evaluation_start, evaluation_end, evaluation_time) VALUES (@resolve_template('@{schema_name}.@{table_name}'), GETVARIABLE('stats_model_start'), NOW(), NOW() - GETVARIABLE('stats_model_start')))"
+        == "@IF(@runtime_stage IN ('evaluating', 'creating'), INSERT INTO analytic_stats (physical_table, evaluation_start, evaluation_end, evaluation_time) VALUES (@resolve_template('@{schema_name}.@{table_name}'), GETVARIABLE('stats_model_start'), NOW(), NOW() - GETVARIABLE('stats_model_start')))"
     )
 
     stats_table = context.fetchdf("select * from memory.analytic_stats").to_dict()

tests/core/test_integration.py

@@ -6207,7 +6207,7 @@ def test_plan_production_environment_statements(tmp_path: Path):
     );
 
     @IF(
-        @runtime_stage = 'evaluating',
+        @runtime_stage IN ('evaluating', 'creating'),
         INSERT INTO schema_names_for_prod (physical_schema_name) VALUES (@resolve_template('@{schema_name}'))
     );