Edit concepts/models docs (#610)

Author: treysp

docs/concepts/models/model_kinds.md

@@ -1,19 +1,19 @@
 # Model kinds
 
-This page describes the supported kinds of [models](overview.md), which ultimately determines how the data for a model is loaded.
+This page describes the kinds of [models](./overview.md) SQLMesh supports, which determine how the data for a model is loaded.
 
 ## INCREMENTAL_BY_TIME_RANGE
 
-Specifies that the model should be computed incrementally based on a time range. This is an optimal choice for datasets in which records are of temporal nature and represent immutable facts such as events, logs, or transactions. Using this kind for datasets that fit the described traits typically results in significant cost and time savings.
+Models of the `INCREMENTAL_BY_TIME_RANGE` kind are computed incrementally based on a time range. This is an optimal choice for datasets in which records are captured over time and represent immutable facts such as events, logs, or transactions. Using this kind for appropriate datasets typically results in significant cost and time savings.
 
-As the name suggests, a model of this kind is computed incrementally, meaning only missing data intervals are processed during each evaluation. This is in contrast to the [FULL](#full) model kind, where the entire dataset is recomputed every time the model is evaluated.
+Only missing time intervals are processed during each execution for `INCREMENTAL_BY_TIME_RANGE` models. This is in contrast to the [FULL](#full) model kind, where the entire dataset is recomputed every time the model is executed.
 
-In order to take advantage of the incremental evaluation, the model query must contain an expression in its `WHERE` clause that filters the upstream records by time range. SQLMesh provides special macros that represent the start and end of the time range being processed: `@start_date` / `@end_date` and `@start_ds` / `@end_ds`. 
+An `INCREMENTAL_BY_TIME_RANGE` model query must contain an expression in its SQL `WHERE` clause that filters the upstream records by time range. SQLMesh provides special macros that represent the start and end of the time range being processed: `@start_date` / `@end_date` and `@start_ds` / `@end_ds`. 
 
-Refer to [Macros](../macros.md#predefined-variables) for more information on these.
+Refer to [Macros](../macros.md#predefined-variables) for more information.
 
-Below is an example of a definition that takes advantage of the model's incremental nature:
-```sql linenums="1"
+This example implements an `INCREMENTAL_BY_TIME_RANGE` model by specifying the `kind` in the `MODEL` ddl and including a SQL `WHERE` clause to filter records by time range:
+```sql linenums="1" hl_lines="3-5 12-13"
 MODEL (
   name db.events,
   kind INCREMENTAL_BY_TIME_RANGE (
@@ -30,7 +30,10 @@ WHERE
 ```
 
 ### Time column
-SQLMesh needs to know which column in the model's output represents a timestamp or date associated with each record. This column is used to determine which records will be overridden during data [restatement](../plans.md#restatement-plans), as well as a partition key for engines that support partitioning (such as Apache Spark).
+SQLMesh needs to know which column in the model's output represents the timestamp or date associated with each record. 
+
+The `time_column` is used to determine which records will be overridden during data [restatement](../plans.md#restatement-plans) and provides a partition key for engines that support partitioning (such as Apache Spark):
+
 ```sql linenums="1" hl_lines="4"
 MODEL (
   name db.events,
@@ -40,7 +43,7 @@ MODEL (
 );
 ```
 
-Additionally, the format in which the timestamp/date is stored is required. By default, SQLMesh uses the `%Y-%m-%d` format, but it can be overridden as follows:
+By default, SQLMesh assumes the time column is in the `%Y-%m-%d` format. For other formats, the default can be overridden as follows:
 ```sql linenums="1" hl_lines="4"
 MODEL (
   name db.events,
@@ -49,9 +52,9 @@ MODEL (
   )
 );
 ```
-**Note:** The time format should be defined using the same dialect as the one used to define the model's query.
+**Note:** The time format should be defined using the same SQL dialect as the one used to define the model's query.
 
-SQLMesh also uses the time column to automatically append a time range filter to the model's query at runtime, which prevents records that are not part of the target interval from being stored. This is a safety mechanism that prevents the unintended overriding of unrelated records when handling late-arriving data.
+SQLMesh also uses the time column to automatically append a time range filter to the model's query at runtime, which prevents records that are not part of the target interval from being stored. This is a safety mechanism that prevents unintentionally overriding unrelated records when handling late-arriving data.
 
 Consider the following model definition:
 ```sql linenums="1"
@@ -70,7 +73,7 @@ WHERE
   receipt_date BETWEEN @start_ds AND @end_ds;
 ```
 
-At runtime, SQLMesh will automatically modify the model's query to look as follows:
+At runtime, SQLMesh will automatically modify the model's query to look like this:
 ```sql linenums="1" hl_lines="7"
 SELECT
   event_date::TEXT as event_date,
@@ -82,9 +85,9 @@ WHERE
 ```
 
 ### Idempotency
-It is recommended to ensure that queries of models of this kind are [idempotent](../../glossary/#idempotency) to prevent unexpected results during data [restatement](../plans.md#restatement-plans). 
+It is recommended that queries of models of this kind are [idempotent](../glossary.md#idempotency) to prevent unexpected results during data [restatement](../plans.md#restatement-plans). 
 
- Note, however, that upstream models and tables can impact the extent to which the idempotency property can be guaranteed. For example, referencing an upstream model of kind [FULL](#full) in the model query automatically renders such a model as non-idempotent.
+Note, however, that upstream models and tables can impact a model's idempotency. For example, referencing an upstream model of kind [FULL](#full) in the model query automatically causes the model to be non-idempotent.
 
 ### Materialization strategy
 Depending on the target engine, models of the `INCREMENTAL_BY_TIME_RANGE` kind are materialized using the following strategies:
@@ -101,16 +104,18 @@ Depending on the target engine, models of the `INCREMENTAL_BY_TIME_RANGE` kind a
 
 ## INCREMENTAL_BY_UNIQUE_KEY
 
-This kind signifies that a model should be computed incrementally based on a unique key. If a key is missing in the model's table, the new row is inserted; otherwise the existing row associated with this key is updated with the new one. This kind is a good fit for datasets that have the following traits:
+Models of the `INCREMENTAL_BY_UNIQUE_KEY` kind are computed incrementally based on a unique key.
 
-* Each record has a key associated with it.
-* There should be at most one record associated with each unique key.
-* It is appropriate to upsert records, meaning existing records can be overridden by new arrivals when their keys match.
+If a key is missing in the model's table, the new data row is inserted; otherwise, the existing row associated with this key is updated with the new one. This kind is a good fit for datasets that have the following traits:
 
-A [Slowly Changing Dimension](../glossary.md#slowly-changing-dimension-scd) (SCD) is one example that fits this description well.
+* Each record has a unique key associated with it.
+* There is at most one record associated with each unique key.
+* It is appropriate to upsert records, so existing records can be overridden by new arrivals when their keys match.
 
-The name of the unique key column must be provided as part of the model definition, as in the following example:
-```sql linenums="1"
+A [Slowly Changing Dimension](../glossary.md#slowly-changing-dimension-scd) (SCD) is one approach that fits this description well.
+
+The name of the unique key column must be provided as part of the `MODEL` DDL, as in this example:
+```sql linenums="1" hl_lines="3-5"
 MODEL (
   name db.employees,
   kind INCREMENTAL_BY_UNIQUE_KEY (
@@ -126,7 +131,7 @@ FROM raw_employees;
 ```
 
 Composite keys are also supported:
-```sql linenums="1"
+```sql linenums="1" hl_lines-"4"
 MODEL (
   name db.employees,
   kind INCREMENTAL_BY_UNIQUE_KEY (
@@ -135,8 +140,8 @@ MODEL (
 );
 ```
 
-Similar to the [INCREMENTAL_BY_TIME_RANGE](#incremental_by_time_range) kind, the upstream records can be filtered by time range using the `@start_date`, `@end_date`, and so forth. Use [macros](../macros.md#predefined-variables) in order to process the input data incrementally:
-```sql linenums="1"
+`INCREMENTAL_BY_UNIQUE_KEY` model kinds can also filter upstream records by time range using a SQL `WHERE` clause and the `@start_date`, `@end_date` or other macros (similar to the [INCREMENTAL_BY_TIME_RANGE](#incremental_by_time_range) kind):
+```sql linenums="1" hl_lines="6-7"
 SELECT
   name::TEXT as name,
   title::TEXT as title,
@@ -146,7 +151,7 @@ WHERE
   event_date BETWEEN @start_date AND @end_date;
 ```
 
-**Note:** Models of this kind are inherently [non-idempotent](../../glossary/#idempotency), which should be taken into consideration during data [restatement](../plans.md#restatement-plans).
+**Note:** Models of the `INCREMENTAL_BY_UNIQUE_KEY` kind are inherently [non-idempotent](../glossary.md#idempotency), which should be taken into consideration during data [restatement](../plans.md#restatement-plans).
 
 ### Materialization strategy
 Depending on the target engine, models of the `INCREMENTAL_BY_UNIQUE_KEY` kind are materialized using the following strategies:
@@ -162,12 +167,14 @@ Depending on the target engine, models of the `INCREMENTAL_BY_UNIQUE_KEY` kind a
 | DuckDB     | not supported       |
 
 ## FULL
-As the name suggests, this kind causes the dataset associated with a model to be fully refreshed (rewritten) upon each model evaluation. It's somewhat easier to use than incremental kinds, due to the lack of any special settings or additional query considerations. This makes it suitable for smaller datasets, where recomputing data from scratch is relatively cheap and doesn't require preservation of processing history. However, using this kind with datasets that have a high volume of records will result in significant runtime and compute costs.
+Models of the `FULL` kind cause the dataset associated with a model to be fully refreshed (rewritten) upon each model evaluation. 
 
-This kind can be a good fit for aggregate tables that lack temporal dimension. For aggregate tables with temporal dimension, consider the [INCREMENTAL_BY_TIME_RANGE](#incremental_by_time_range) kind instead.
+The `FULL` model kind is somewhat easier to use than incremental kinds due to the lack of special settings or additional query considerations. This makes it suitable for smaller datasets, where recomputing data from scratch is relatively cheap and doesn't require preservation of processing history. However, using this kind with datasets containing a large volume of records will result in significant runtime and compute costs.
 
-Example:
-```sql linenums="1"
+This kind can be a good fit for aggregate tables that lack a temporal dimension. For aggregate tables with a temporal dimension, consider the [INCREMENTAL_BY_TIME_RANGE](#incremental_by_time_range) kind instead.
+
+This example specifies a `FULL` model kind:
+```sql linenums="1" hl_lines="3"
 MODEL (
   name db.salary_by_title_agg,
   kind FULL
@@ -194,14 +201,16 @@ Depending on the target engine, models of the `FULL` kind are materialized using
 | DuckDB     | CREATE OR REPLACE TABLE          |
 
 ## VIEW
-Other model kinds cause the output of a model query to be materialized and stored in a physical table. The `VIEW` kind is different, because no data actually gets written during model evaluation. Instead, a non-materialized view (or "virtual table") is created or replaced based on the model's query.
+The model kinds described so far cause the output of a model query to be materialized and stored in a physical table. 
 
-**Note:** With this kind, the model's query is evaluated every time the model is referenced in downstream queries. This may incur undesirable compute cost in cases where the model's query is compute-intensive, or when the model is referenced in many downstream queries.
+The `VIEW` kind is different, because no data is actually written during model execution. Instead, a non-materialized view (or "virtual table") is created or replaced based on the model's query.
 
-View is the default model kind if the kind is not specified.
+**Note:** View is the default model kind if kind is not specified.
 
-Example:
-```sql linenums="1"
+**Note:** With this kind, the model's query is evaluated every time the model is referenced in a downstream query. This may incur undesirable compute cost and time in cases where the model's query is compute-intensive, or when the model is referenced in many downstream queries.
+
+This example specifies a `VIEW` model kind:
+```sql linenums="1" hl_lines="3"
 MODEL (
   name db.highest_salary,
   kind VIEW
@@ -213,10 +222,12 @@ FROM db.employees;
 ```
 
 ## EMBEDDED
-Embedded models are a way to share common logic between different models of other kinds. This kind is similar to [VIEW](#view), except models of this kind are never evaluated, and therefore there are no data assets (tables or views) associated with them in the data warehouse. Instead, the embedded model's query gets injected directly into a query of each downstream model that references this model in its own query.
+Embedded models are a way to share common logic between different models of other kinds. 
 
-Example:
-```sql linenums="1"
+There are no data assets (tables or views) associated with `EMBEDDED` models in the data warehouse. Instead, an `EMBEDDED` model's query is injected directly into the query of each downstream model that references it.
+
+This example specifies a `EMBEDDED` model kind:
+```sql linenums="1" hl_lines="3"
 MODEL (
   name db.unique_employees,
   kind EMBEDDED
@@ -228,4 +239,4 @@ FROM db.employees;
 ```
 
 ## SEED
-This is a special kind reserved for [seed models](seed_models.md).
+The `SEED` model kind is used to specify [seed models](./seed_models.md) for using static CSV datasets in your SQLMesh project.