move unique_key page under general configs (#6636)

dbt-labs · Dec 10, 2024 · db2d160 · db2d160
2 parents 2f77437 + 492a11b
commit db2d160
Show file tree

Hide file tree

Showing 3 changed files with 151 additions and 10 deletions.
diff --git a/website/docs/reference/model-configs.md b/website/docs/reference/model-configs.md
@@ -36,9 +36,11 @@ models:
     [+](/reference/resource-configs/plus-prefix)[materialized](/reference/resource-configs/materialized): <materialization_name>
     [+](/reference/resource-configs/plus-prefix)[sql_header](/reference/resource-configs/sql_header): <string>
     [+](/reference/resource-configs/plus-prefix)[on_configuration_change](/reference/resource-configs/on_configuration_change): apply | continue | fail #only for materialized views on supported adapters
+    [+](/reference/resource-configs/plus-prefix)[unique_key](/reference/resource-configs/unique_key): <column_name_or_expression>
 
 ```
 
+
 </File>
 
 </TabItem>
@@ -57,6 +59,7 @@ models:
       [materialized](/reference/resource-configs/materialized): <materialization_name>
       [sql_header](/reference/resource-configs/sql_header): <string>
       [on_configuration_change](/reference/resource-configs/on_configuration_change): apply | continue | fail #only for materialized views on supported adapters
+      [unique_key](/reference/resource-configs/unique_key): <column_name_or_expression>
 
 ```
 
@@ -69,12 +72,13 @@ models:
 
 <File name='models/<model_name>.sql'>
 
-```jinja
+```sql
 
 {{ config(
     [materialized](/reference/resource-configs/materialized)="<materialization_name>",
     [sql_header](/reference/resource-configs/sql_header)="<string>"
     [on_configuration_change](/reference/resource-configs/on_configuration_change): apply | continue | fail #only for materialized views for supported adapters
+    [unique_key](/reference/resource-configs/unique_key)='column_name_or_expression'
 ) }}
 
 ```
@@ -212,7 +216,7 @@ models:
 
 <VersionBlock lastVersion="1.8">
 
-```jinja
+```sql
 
 {{ config(
     [enabled](/reference/resource-configs/enabled)=true | false,
@@ -233,7 +237,7 @@ models:
 
 <VersionBlock firstVersion="1.9">
 
-```jinja
+```sql
 
 {{ config(
     [enabled](/reference/resource-configs/enabled)=true | false,
@@ -246,8 +250,9 @@ models:
     [persist_docs](/reference/resource-configs/persist_docs)={<dict>},
     [meta](/reference/resource-configs/meta)={<dict>},
     [grants](/reference/resource-configs/grants)={<dict>},
-    [contract](/reference/resource-configs/contract)={<dictionary>}
-    [event_time](/reference/resource-configs/event-time): my_time_field
+    [contract](/reference/resource-configs/contract)={<dictionary>},
+    [event_time](/reference/resource-configs/event-time)='my_time_field',
+
 ) }}
 
 ```

diff --git a/website/docs/reference/resource-configs/unique_key.md b/website/docs/reference/resource-configs/unique_key.md
@@ -1,12 +1,65 @@
 ---
-resource_types: [snapshots]
+resource_types: [snapshots, models]
 description: "Learn more about unique_key configurations in dbt."
 datatype: column_name_or_expression
 ---
 
 
+<Tabs>
+
+<TabItem value="models" label="Models">
+
+Configure the `unique_key` in the `config` block of your [incremental model's](/docs/build/incremental-models) SQL file, in your `models/properties.yml` file, or in your `dbt_project.yml` file.
+
+<File name='models/my_incremental_model.sql'>
+
+```sql
+{{
+    config(
+        materialized='incremental',
+        unique_key='id'
+    )
+}}
+
+```
+
+</File>
+
+<File name='models/properties.yml'>
+
+```yaml
+models:
+  - name: my_incremental_model
+    description: "An incremental model example with a unique key."
+    config:
+      materialized: incremental
+      unique_key: id
+
+```
+
+</File>
+
+<File name='dbt_project.yml'>
+
+```yaml
+name: jaffle_shop
+
+models:
+  jaffle_shop:
+    staging:
+      +unique_key: id
+```
+
+</File>
+
+</TabItem>
+
+<TabItem value="snapshots" label="Snapshots">
+
 <VersionBlock firstVersion="1.9">
 
+For [snapshots](/docs/build/snapshots), configure the `unique_key` in the your `snapshot/filename.yml` file or in your `dbt_project.yml` file.
+
 <File name='snapshots/<filename>.yml'>
 
 ```yaml
@@ -23,6 +76,8 @@ snapshots:
 
 <VersionBlock lastVersion="1.8">
 
+Configure the `unique_key` in the `config` block of your snapshot SQL file or in your `dbt_project.yml` file.
+
 import SnapshotYaml from '/snippets/_snapshot-yaml-spec.md';
 
 <SnapshotYaml/>
@@ -49,10 +104,13 @@ snapshots:
 
 </File>
 
+</TabItem>
+</Tabs>
+
 ## Description
-A column name or expression that is unique for the inputs of a snapshot. dbt uses this to match records between a result set and an existing snapshot, so that changes can be captured correctly.
+A column name or expression that is unique for the inputs of a snapshot or incremental model. dbt uses this to match records between a result set and an existing snapshot or incremental model, so that changes can be captured correctly.
 
-In dbt Cloud "Latest" and dbt v1.9+, [snapshots](/docs/build/snapshots) are defined and configured in YAML files within your `snapshots/` directory. You can specify one or multiple `unique_key` values within your snapshot YAML file's `config` key.
+In dbt Cloud "Latest" release track and from dbt v1.9, [snapshots](/docs/build/snapshots) are defined and configured in YAML files within your `snapshots/` directory. You can specify one or multiple `unique_key` values within your snapshot YAML file's `config` key.
 
 :::caution 
 
@@ -67,6 +125,32 @@ This is a **required parameter**. No default is provided.
 ## Examples
 ### Use an `id` column as a unique key
 
+<Tabs>
+
+<TabItem value="models" label="Models">
+
+In this example, the `id` column is the unique key for an incremental model.
+
+<File name='models/my_incremental_model.sql'>
+
+```sql
+{{
+    config(
+        materialized='incremental',
+        unique_key='id'
+    )
+}}
+
+select * from ..
+```
+
+</File>
+</TabItem>
+
+<TabItem value="snapshots" label="Snapshots">
+
+In this example, the `id` column is used as a unique key for a snapshot.
+
 <VersionBlock firstVersion="1.9">
 
 <File name="snapshots/orders_snapshot.yml">
@@ -114,10 +198,38 @@ snapshots:
 
 </File>
 
+</TabItem>
+</Tabs>
+
 <VersionBlock firstVersion="1.9">
 
 ### Use multiple unique keys
 
+<Tabs>
+<TabItem value="models" label="Models">
+
+Configure multiple unique keys for an incremental model as a string representing a single column or a list of single-quoted column names that can be used together, for example, `['col1', 'col2', …]`. 
+
+Columns must not contain null values, otherwise the incremental model will fail to match rows and generate duplicate rows. Refer to [Defining a unique key](/docs/build/incremental-models#defining-a-unique-key-optional) for more information.
+
+<File name='models/my_incremental_model.sql'>
+
+```sql
+{{ config(
+    materialized='incremental',
+    unique_key=['order_id', 'location_id']
+) }}
+
+with...
+
+```
+
+</File>
+
+</TabItem>
+
+<TabItem value="snapshots" label="Snapshots">
+
 You can configure snapshots to use multiple unique keys for `primary_key` columns.
 
 <File name='snapshots/transaction_items_snapshot.yml'>
@@ -137,12 +249,35 @@ snapshots:
 ```
 
 </File>
+</TabItem>
+</Tabs>
 </VersionBlock>
 
 <VersionBlock lastVersion="1.8">
 
 ### Use a combination of two columns as a unique key
 
+<Tabs>
+<TabItem value="models" label="Models">
+
+<File name='models/my_incremental_model.sql'>
+
+```sql
+{{ config(
+    materialized='incremental',
+    unique_key=['order_id', 'location_id']
+) }}
+
+with...
+
+```
+
+</File>
+
+</TabItem>
+
+<TabItem value="snapshots" label="Snapshots">
+
 This configuration accepts a valid column expression. As such, you can concatenate two columns together as a unique key if required. It's a good idea to use a separator (for example, `'-'`) to ensure uniqueness.
 
 <File name='snapshots/transaction_items_snapshot.sql'>
@@ -170,7 +305,6 @@ from {{ source('erp', 'transactions') }}
 
 Though, it's probably a better idea to construct this column in your query and use that as the `unique_key`:
 
-
 <File name='models/transaction_items_ephemeral.sql'>
 
 ```sql
@@ -211,4 +345,6 @@ from {{ source('erp', 'transactions') }}
 ```
 
 </File>
+</TabItem>
+</Tabs>
 </VersionBlock>
diff --git a/website/sidebars.js b/website/sidebars.js
@@ -941,6 +941,7 @@ const sidebarSettings = {
             "reference/resource-configs/pre-hook-post-hook",
             "reference/resource-configs/schema",
             "reference/resource-configs/tags",
+            "reference/resource-configs/unique_key",
             "reference/resource-configs/meta",
             "reference/advanced-config-usage",
             "reference/resource-configs/plus-prefix",
@@ -985,7 +986,6 @@ const sidebarSettings = {
             "reference/resource-configs/strategy",
             "reference/resource-configs/target_database",
             "reference/resource-configs/target_schema",
-            "reference/resource-configs/unique_key",
             "reference/resource-configs/updated_at",
           ],
         },