Improved lifecycle details

Author: anuunchin

docs/uv.lock

@@ -157,20 +157,24 @@ Downstream of the transformation layer, we may want to know which columns origin
 
 ## Lifecycle of a SQL transformation
 
-Just like regular dlt resources, dlt transformations go through the three stages of extract, normalize, and load when a pipeline is run.
+In this section, we focus on the lifecycle of transformations that yield a `Relation` object, which we call SQL transformations here. This is in contrast to Python-based transformations that yield dataframes or arrow tables, which go through the regular extract, normalize, and load lifecycle of a `dlt` resource.
 
 ### Extract
 
 In the extract stage, a `Relation` yielded by a transformation is converted into a SQL string and saved as a `.model` file along with its source SQL dialect.
-At this stage, the SQL string is just the user's original query — either the string that was explicitly provided or the one generated by `Relation.to_sql()`. No dlt-specific columns like `_dlt_id` or `_dlt_load_id` are added yet.
+At this stage, the SQL string is just the user's original query — either the string that was explicitly provided or the one generated by `Relation.to_sql()`. No `dlt`-specific columns like `_dlt_id` or `_dlt_load_id` are added yet.
 
 ### Normalize
 
-In the normalize stage, `.model` files are read and processed. This is where the main transformation logic happens.
+In the normalize stage, `.model` files are read and processed. The normalization process modifies your SQL queries to ensure they execute correctly and integrate with `dlt`'s features.
 
-#### `dlt` columns
+:::info
+The normalization described here applies only to SQL-based transformations. Python-based transformations, such as those using dataframes or arrow tables, follow the [regular normalization process](../../../reference/explainers/how-dlt-works.md#normalize).
+:::
+
+#### Adding `dlt` columns
 
-During normalization, `dlt` will add internal dlt columns to your SQL queries depending on the configuration:
+During normalization, `dlt` adds internal `dlt` columns to your SQL queries depending on the configuration:
 
 - `_dlt_load_id`, which tracks which load operation created or modified each row, is **added by default**. Even if present in your query, the `_dlt_load_id` column will be **replaced with a constant value** corresponding to the current load ID. To disable this behavior, set:
     ```toml
@@ -190,35 +194,45 @@ During normalization, `dlt` will add internal dlt columns to your SQL queries de
      - In **Redshift**, `_dlt_id` is generated using an `MD5` hash of the load ID and row number.
      - In **SQLite**, `_dlt_id` is simulated using `lower(hex(randomblob(16)))`.
 
-Additionally, column names are normalized according to the naming schema selected and the identifier capabilities of the destinations. This ensures compatibility and consistent naming conventions across different data sources and destination systems.
-
-This allows `dlt` to maintain data lineage and enables features like incremental loading and merging, even when working with raw SQL queries.
-
-:::info
-The normalization described here, including automatic injection or replacement of dlt columns, applies only to SQL-based transformations. Python-based transformations, such as those using dataframes or arrow tables, follow the [regular normalization process](../../../reference/explainers/how-dlt-works.md#normalize).
-:::
 
-#### Query Processing
+#### Query transformations
 
-Additionally, the normalization process in `dlt` takes care of several important steps to ensure your queries are executed smoothly and correctly on the input dataset:
+The normalization process also applies the following transformations to ensure your queries work correctly:
 
-1. Adds special dlt columns (see above for details).
-2. Fully qualifies all identifiers by adding database and dataset prefixes, so tables are always referenced unambiguously during query execution.
-3. Properly quotes and, if necessary, adjusts the case of your identifiers to match the destination’s requirements.
-4. Handles differences in naming conventions by aliasing columns and tables as needed, so names always match those in the destination.
-5. Reorders columns to match the expected order in the destination table.
-6. Fills in default `NULL` values for any columns that exist in the destination table but are not selected in your query.
+1. Fully qualifies all identifiers with database and dataset prefixes
+2. Quotes and adjusts identifier casing to match destination requirements
+3. Normalizes column names according to the selected naming convention
+4. Aliases columns and tables to handle naming convention differences
+5. Reorders columns to match the destination table schema
+6. Fills in `NULL` values for columns that exist in the destination but aren't in your query
 
 ### Load
 
-In the load stage, the normalized SELECT queries from `.model` files are wrapped in INSERT statements and executed on the destination.
+In the load stage, the normalized queries from `.model` files are wrapped in INSERT statements and executed on the destination.
 For example, given this query from the extract stage:
 
 ```sql
 SELECT id, value FROM table
 ```
 
-After the normalize stage processes it (adding dlt columns, wrapping in subquery, etc.), the load stage executes:
+After the normalize stage processes it (adding dlt columns, wrapping in subquery, etc.) and results in:
+
+```sql
+SELECT
+    _dlt_subquery."id" AS "id",
+    _dlt_subquery."value" AS "value",
+    '1749134128.17655' AS "_dlt_load_id",
+    UUID() AS "_dlt_id"
+FROM (
+    SELECT
+        "my_table"."id" AS "id",
+        "my_table"."value" AS "value"
+    FROM "my_pipeline_dataset"."my_table" AS "my_table"
+    )
+AS _dlt_subquery
+```
+
+The load stage executes:
 
 ```sql
 INSERT INTO
@@ -237,7 +251,7 @@ FROM (
 AS _dlt_subquery
 ```
 
-The SELECT portion is what was produced during the normalize stage. In the load stage, this query is executed via the destination's SQL client, materializing the transformation result directly in the database.
+The query is executed via the destination's SQL client, materializing the transformation result directly in the database.
 
 ## Examples