From 3ad19b4a3ef8b12d6e9ebd68c3d9ee0e7e7f5dc1 Mon Sep 17 00:00:00 2001 From: Doug Beatty <44704949+dbeatty10@users.noreply.github.com> Date: Thu, 14 Dec 2023 13:17:06 -0700 Subject: [PATCH] Display supported incremental strategies in a tabular format (#4649) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit [Preview](https://docs-getdbt-com-git-dbeatty-tabular-incremental-326e95-dbt-labs.vercel.app/docs/build/incremental-models#supported-incremental-strategies-by-adapter) resolves #4634 ## What are you changing in this pull request and why? The main aim is to be able to easily answer each of these questions: - which adapters support the `delete+insert` strategy? - what are the names of the standard incremental strategies that are supported in at least one adapter? - what are the names of the standard incremental strategies that are supported most frequently? - what are the names of the standard incremental strategies that are supported least frequently? A tabular representation with one column per strategy is the easiest way to answer all of the above. ## Design decisions to be made 1. Style of the icons 1. Number of tables ### Style of the icons Any of these could work: ✅ - Green check mark ✔️ - Heavy check mark 🟢 - Green circle We probably wouldn't choose any of these: ☑️ - Ballot box with check 🆗 - OK button 👍 - Thumbs up etc. ### Number of tables We have several options: 1. Keep the status quo 1. Split into two tables: one for the available strategies, and another for the defaults 1. Keep a single table, keeping the "default strategy" column, but replacing the "additional supported strategies" with one column per strategy 1. Defer the default strategy information to each adapter-specific config page instead (see [dbt-bigquery](https://docs.getdbt.com/reference/resource-configs/bigquery-configs#merge-behavior-incremental-models) or [dbt-redshift](https://docs.getdbt.com/reference/resource-configs/redshift-configs#incremental-materialization-strategies) for examples) ### Trade-offs I strongly prefer not staying with the status quo, or I wouldn't have opened this issue 🤣 Splitting into two separate tables would solve the key problem, but at the cost of taking up more vertical space on the page. Keeping a single table but refactoring it would work for me. Completely moving the default strategy information into the adapter-specific pages might be the best of all worlds. It would solve the problem at hand while preserving documentation about the default strategy that is relevant for a particular adapter. dbt-postgres and dbt-redshift in particular have caveats related to the default -- it will change [depending if a `unique_key` is defined ](https://github.com/dbt-labs/docs.getdbt.com/issues/4651)or not. ## 🎩 [Preview](https://docs-getdbt-com-git-dbeatty-tabular-incremental-326e95-dbt-labs.vercel.app/docs/build/incremental-models#supported-incremental-strategies-by-adapter) ### v3 (final) image image ### v2 image ### v1 **Note:** I've since removed the 2nd table that has the defaults, but here's what it looked like with them: image image ## Checklist - [x] Review the [Content style guide](https://github.com/dbt-labs/docs.getdbt.com/blob/current/contributing/content-style-guide.md) so my content adheres to these guidelines. --------- Co-authored-by: Matt Shaver <60105315+matthewshaver@users.noreply.github.com> --- website/docs/docs/build/incremental-models.md | 38 +++++++++---------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/website/docs/docs/build/incremental-models.md b/website/docs/docs/build/incremental-models.md index 01a392c12fe..46788758ee6 100644 --- a/website/docs/docs/build/incremental-models.md +++ b/website/docs/docs/build/incremental-models.md @@ -249,31 +249,29 @@ The `merge` strategy is available in dbt-postgres and dbt-redshift beginning in - -| data platform adapter | default strategy | additional supported strategies | -| :-------------------| ---------------- | -------------------- | -| [dbt-postgres](/reference/resource-configs/postgres-configs#incremental-materialization-strategies) | `append` | `delete+insert` | -| [dbt-redshift](/reference/resource-configs/redshift-configs#incremental-materialization-strategies) | `append` | `delete+insert` | -| [dbt-bigquery](/reference/resource-configs/bigquery-configs#merge-behavior-incremental-models) | `merge` | `insert_overwrite` | -| [dbt-spark](/reference/resource-configs/spark-configs#incremental-models) | `append` | `merge`, `insert_overwrite` | -| [dbt-databricks](/reference/resource-configs/databricks-configs#incremental-models) | `merge` | `append`, `insert_overwrite` | -| [dbt-snowflake](/reference/resource-configs/snowflake-configs#merge-behavior-incremental-models) | `merge` | `append`, `delete+insert` | -| [dbt-trino](/reference/resource-configs/trino-configs#incremental) | `append` | `merge`, `delete+insert` | +| data platform adapter | `append` | `merge` | `delete+insert` | `insert_overwrite` | +|-----------------------------------------------------------------------------------------------------|:--------:|:-------:|:---------------:|:------------------:| +| [dbt-postgres](/reference/resource-configs/postgres-configs#incremental-materialization-strategies) | ✅ | | ✅ | | +| [dbt-redshift](/reference/resource-configs/redshift-configs#incremental-materialization-strategies) | ✅ | | ✅ | | +| [dbt-bigquery](/reference/resource-configs/bigquery-configs#merge-behavior-incremental-models) | | ✅ | | ✅ | +| [dbt-spark](/reference/resource-configs/spark-configs#incremental-models) | ✅ | ✅ | | ✅ | +| [dbt-databricks](/reference/resource-configs/databricks-configs#incremental-models) | ✅ | ✅ | | ✅ | +| [dbt-snowflake](/reference/resource-configs/snowflake-configs#merge-behavior-incremental-models) | ✅ | ✅ | ✅ | | +| [dbt-trino](/reference/resource-configs/trino-configs#incremental) | ✅ | ✅ | ✅ | | - -| data platform adapter | default strategy | additional supported strategies | -| :----------------- | :----------------| : ---------------------------------- | -| [dbt-postgres](/reference/resource-configs/postgres-configs#incremental-materialization-strategies) | `append` | `merge` , `delete+insert` | -| [dbt-redshift](/reference/resource-configs/redshift-configs#incremental-materialization-strategies) | `append` | `merge`, `delete+insert` | -| [dbt-bigquery](/reference/resource-configs/bigquery-configs#merge-behavior-incremental-models) | `merge` | `insert_overwrite` | -| [dbt-spark](/reference/resource-configs/spark-configs#incremental-models) | `append` | `merge`, `insert_overwrite` | -| [dbt-databricks](/reference/resource-configs/databricks-configs#incremental-models) | `merge` | `append`, `insert_overwrite` | -| [dbt-snowflake](/reference/resource-configs/snowflake-configs#merge-behavior-incremental-models) | `merge` | `append`, `delete+insert` | -| [dbt-trino](/reference/resource-configs/trino-configs#incremental) | `append` | `merge`, `delete+insert` | +| data platform adapter | `append` | `merge` | `delete+insert` | `insert_overwrite` | +|-----------------------------------------------------------------------------------------------------|:--------:|:-------:|:---------------:|:------------------:| +| [dbt-postgres](/reference/resource-configs/postgres-configs#incremental-materialization-strategies) | ✅ | ✅ | ✅ | | +| [dbt-redshift](/reference/resource-configs/redshift-configs#incremental-materialization-strategies) | ✅ | ✅ | ✅ | | +| [dbt-bigquery](/reference/resource-configs/bigquery-configs#merge-behavior-incremental-models) | | ✅ | | ✅ | +| [dbt-spark](/reference/resource-configs/spark-configs#incremental-models) | ✅ | ✅ | | ✅ | +| [dbt-databricks](/reference/resource-configs/databricks-configs#incremental-models) | ✅ | ✅ | | ✅ | +| [dbt-snowflake](/reference/resource-configs/snowflake-configs#merge-behavior-incremental-models) | ✅ | ✅ | ✅ | | +| [dbt-trino](/reference/resource-configs/trino-configs#incremental) | ✅ | ✅ | ✅ | |