Created new section called Parallel batch execution

website/docs/docs/build/incremental-microbatch.md

@@ -179,12 +179,15 @@ It does not matter whether the table already contains data for that day. Given t
 
 Several configurations are relevant to microbatch models, and some are required:
 
-| Config   | Type | Description   | Default |
-|----------|------|---------------|---------|
-| [`event_time`](/reference/resource-configs/event-time) | Column  (required)   | The column indicating "at what time did the row occur." Required for your microbatch model and any direct parents that should be filtered.          | N/A     |
-| [`begin`](/reference/resource-configs/begin) | Date (required)   | The "beginning of time" for the microbatch model. This is the starting point for any initial or full-refresh builds. For example, a daily-grain microbatch model run on `2024-10-01` with `begin = '2023-10-01` will process 366 batches (it's a leap year!) plus the batch for "today."        | N/A     |
-| [`batch_size`](/reference/resource-configs/batch-size) | String (required)  | The granularity of your batches. Supported values are `hour`, `day`, `month`, and `year`             | N/A     |
-| [`lookback`](/reference/resource-configs/lookback)   | Integer (optional) | Process X batches prior to the latest bookmark to capture late-arriving records.                                         | `1`     |
+
+| Config   |  Description   | Default | Type | Required  |
+|----------|---------------|---------|------|---------|
+| [`event_time`](/reference/resource-configs/event-time)  | The column indicating "at what time did the row occur." Required for your microbatch model and any direct parents that should be filtered.   | N/A     |  Column  |  Required |
+| `begin`      |  The "beginning of time" for the microbatch model. This is the starting point for any initial or full-refresh builds. For example, a daily-grain microbatch model run on `2024-10-01` with `begin = '2023-10-01` will process 366 batches (it's a leap year!) plus the batch for "today."        | N/A     | Date   | Required |
+| `batch_size` |  The granularity of your batches. Supported values are `hour`, `day`, `month`, and `year`    | N/A     | String  | Required |
+| `lookback`   | Process X batches prior to the latest bookmark to capture late-arriving records.    | `1`     | Integer | Optional |
+| `concurrent_batches` | An override for whether batches run concurrently (at the same time) or sequentially (one after the other). | `None` | Boolean | Optional |
+
 
 <Lightbox src="/img/docs/building-a-dbt-project/microbatch/event_time.png" title="The event_time column configures the real-world time of this record"/>
 
@@ -280,6 +283,125 @@ For now, dbt assumes that all values supplied are in UTC:
 
 While we may consider adding support for custom time zones in the future, we also believe that defining these values in UTC makes everyone's lives easier.
 
+## Parallel batch execution
+
+The microbatch strategy offers the benefit of updating a model in smaller, more manageable batches. 
+
+Parallel batch execution means that multiple batches are processed at the same time, instead of one after the other (sequentially) for faster processing of your microbatch models.  
+
+dbt automatically detects whether a batch can be run in parallel in most cases, which means you don’t need to configure this setting. However, the `concurrent_batches` config is available as an override (not a gate), allowing you to specify whether batches should or shouldn’t be run in parallel in specific cases.
+
+For example, if you have a microbatch model with 12 batches, you can execute those batches to run in parallel. Specifically they'll run in parallel limited by the number of [available threads](/docs/running-a-dbt-project/using-threads).
+
+### Prerequisites
+
+To enable parallel execution, you must meet the following conditions:
+
+- You use the following supported adapters:
+  - Snowflake
+  - Databricks
+  - More adapters coming soon!
+- You meet [additional conditions](#how-parallel-batch-execution-works) mentioned in the next section
+
+### How parallel batch execution works
+
+A batch can only run in parallel if:
+
+| Step | Condition     |  Parallel execution   | Sequential execution|
+| ---- | ---------------| :------------------: | :----------: |
+| 1.   | **Not** the first batch |  ✅         | -            |
+| 2.   | **Not** the last batch  |  ✅         | -            |
+| 3.   | [Adapter supports](#prerequisites) parallel batches | ✅  | -         |
+
+
+After checking for 1, 2, and 3 in the previous table &mdash; and if `concurrent_batches` value isn't set, dbt will intelligently auto-detect if the model invokes the [`{{ this }}`](/reference/dbt-jinja-functions/this) Jinja function. If it references `{{ this }}`, the batches will run sequentially since  `{{ this }}` represents the database of the current model and referencing the same relation causes conflict. 
+
+Otherwise, if the `concurrent_batches` value isn't set _and_ `{{ this }}` isn't detected (and other conditions are met), the batches will run in parallel.  
+### Parallel or sequential execution
+
+
+
+Choosing between parallel batch execution and sequential processing depends on the specific requirements of your use case. 
+
+- Parallel batch execution is faster but requires logic that's independent of batch execution order. For example, if you're developing a data pipeline for a system that processes user transactions in batches, each batch is executed in parallel for better performance. However, the logic used to process each transaction shouldn't depend on the order of how batches are executed or completed.
+- Sequential processing is slower but essential for calculations like [cumulative metrics](/docs/build/cumulative)  in microbatch models. It processes data in the correct order, allowing each step to build on the previous one.
+
+<!-- You can override the check for `this` by setting `concurrent_batches` to either `True` or `False`. If set to `False`, the batch will be run sequentially. If set to `True` the batch will be run in parallel (assuming [1], [2], and [3])
+To override the `this` check, use the `concurrent_batches` configuration:
+
+
+<File name='dbt_project.yml'>
+
+```yaml
+models:
+  +concurrent_batches: True
+```
+
+</File>
+
+or:
+
+<File name='models/my_model.sql'>
+
+```sql
+{{
+  config(
+    materialized='incremental',
+    concurrent_batches=True,
+    incremental_strategy='microbatch'
+
+    ...
+  )
+}}
+
+select ...
+```
+
+</File>
+-->
+
+### Configure `concurrent_batches` 
+
+By default, dbt auto-detects whether batches can run in parallel for microbatch models, and this works correctly in most cases. However, you can override dbt's detection by setting the `concurrent_batches` config in your `dbt_project.yml` or model `.sql` file to specify parallel or sequential execution, given you meet all the [conditions](#prerequisites):
+
+<Tabs>
+<TabItem value="yaml" label="dbt_project.yml">
+
+<File name='dbt_project.yml'>
+
+```yaml
+models:
+  +concurrent_batches: True # value set to True to run batches in parallel
+```
+
+</File>
+</TabItem>
+
+<TabItem value="sql" label="my_model.sql">
+
+<File name='models/my_model.sql'>
+
+```sql
+{{
+  config(
+    materialized='incremental',
+    incremental_strategy='microbatch',
+    event_time='session_start',
+    begin='2020-01-01',
+    batch_size='day
+    concurrent_batches=True, # value set to True to run batches in parallel
+    ...
+  )
+}}
+
+select ...
+```
+</File>
+</TabItem>
+</Tabs>
+
+Depending on your use case, configuring your microbatch models to run in parallel offer faster processing, in comparison to running batches sequentially.
+
 ## How `microbatch` compares to other incremental strategies?
 
 Most incremental models rely on the end user (you) to explicitly tell dbt what "new" means, in the context of each model, by writing a filter in an `{% if is_incremental() %}` conditional block. You are responsible for crafting this SQL in a way that queries [`{{ this }}`](/reference/dbt-jinja-functions/this) to check when the most recent record was last loaded, with an optional look-back window for late-arriving records.