New snapshot_meta_column_names config for dbt snapshots

website/docs/docs/build/snapshots.md

@@ -512,6 +512,8 @@ Basically – keep your query as simple as possible! Some reasonable exceptions
 
 Snapshot <Term id="table">tables</Term> will be created as a clone of your source dataset, plus some additional meta-fields*.
 
+In v1.9 or with [dbt Cloud Versionless](/docs/dbt-versions/upgrade-dbt-version-in-cloud#versionless), these column names can be customized to your team or organizational conventions via the [`snapshot_meta_column_names`](/reference/resource-configs/snapshot_meta_column_names) config.
+
 | Field          | Meaning | Usage |
 | -------------- | ------- | ----- |
 | dbt_valid_from | The timestamp when this snapshot row was first inserted | This column can be used to order the different "versions" of a record. |

website/docs/docs/dbt-versions/release-notes.md

@@ -21,7 +21,7 @@ Release notes are grouped by month for both multi-tenant and virtual private clo
 ## October 2024
 
 
-- **New**: In dbt Cloud Versionless, [Snapshots](/docs/build/snapshots) have been updated to use YAML configuration files instead of SQL snapshot blocks. This new feature simplifies snapshot management and improves performance, and will soon be released in dbt Core 1.9.
+- **New**: In dbt Cloud Versionless, [Snapshots](/docs/build/snapshots) have been updated to use YAML configuration files instead of SQL snapshot blocks. This new feature simplifies snapshot management and improves performance, and will soon be released in dbt Core 1.9. This includes a new `snapshot_meta_column_names` config for customizing the snapshot metadata columns.
   - Who does this affect? New user on Versionless can define snapshots using the new YAML specification. Users upgrading to Versionless who use snapshots can keep their existing configuration or can choose to migrate their snapshot definitions to YAML. 
   - Users on dbt 1.8 and earlier: No action is needed; existing snapshots will continue to work as before. However, we recommend upgrading to Versionless to take advantage of the new snapshot features.
 - **Enhancement**: In dbt Cloud Versionless, snapshots defined in SQL files can now use `config` defined in `schema.yml` YAML files. This update resolves the previous limitation that required snapshot properties to be defined exclusively in `dbt_project.yml` and/or a `config()` block within the SQL file. This enhancement will be included in the upcoming dbt Core v1.9 release.

website/docs/reference/resource-configs/snapshot_meta_column_names.md

@@ -0,0 +1,109 @@
+---
+resource_types: [snapshots]
+description: "Snapshot meta column names"
+datatype: "{<dictionary>}"
+default_value: {"dbt_valid_from": "dbt_valid_from", "dbt_valid_to": "dbt_valid_to", "dbt_scd_id": "dbt_scd_id", "dbt_updated_at": "dbt_updated_at"}
+id: "snapshot_meta_column_names"
+---
+
+Available in v1.9 or with [versionless](/docs/dbt-versions/upgrade-dbt-version-in-cloud#versionless) dbt Cloud.
+
+<File name='snapshots/schema.yml'>
+
+```yaml
+snapshots:
+  - name: <snapshot_name>
+    config:
+      snapshot_meta_column_names:
+        dbt_valid_from: <string>
+        dbt_valid_to: <string>
+        dbt_scd_id: <string>
+        dbt_updated_at: <string>
+
+```
+
+</File>
+
+<File name='snapshots/<filename>.sql'>
+
+```jinja2
+{{
+    config(
+      snapshot_meta_column_names={
+        "dbt_valid_from": "<string>",
+        "dbt_valid_to": "<string>",
+        "dbt_scd_id": "<string>",
+        "dbt_updated_at": "<string>",
+      }
+    )
+}}
+
+```
+
+</File>
+
+<File name='dbt_project.yml'>
+
+```yml
+snapshots:
+  [<resource-path>](/reference/resource-configs/resource-path):
+    +snapshot_meta_column_names:
+      dbt_valid_from: <string>
+      dbt_valid_to: <string>
+      dbt_scd_id: <string>
+      dbt_updated_at: <string>
+
+```
+
+</File>
+
+## Description
+
+In order to align with an organization's naming conventions, the `snapshot_meta_column_names` config can be used to customize the names of the [metadata columns](/docs/build/snapshots#snapshot-meta-fields) within each snapshot.
+
+## Default
+
+By default, dbt snapshots use the following column names to track change history using [Type 2 slowly changing dimension](https://en.wikipedia.org/wiki/Slowly_changing_dimension#Type_2:_add_new_row) records:
+
+| Field          | Meaning | Notes |
+| -------------- | ------- | ----- |
+| `dbt_valid_from` | The timestamp when this snapshot row was first inserted and became valid. | The value is affected by the [`strategy`](/reference/resource-configs/strategy). |
+| `dbt_valid_to`   | The timestamp when this row is no longer valid. |  |
+| `dbt_scd_id`     | A unique key generated for each snapshot row. | This is used internally by dbt. |
+| `dbt_updated_at` | The `updated_at` timestamp of the source record when this snapshot row was inserted. | This is used internally by dbt. |
+
+However, these column names can be customized using the `snapshot_meta_column_names` config.
+
+:::note
+
+To avoid any uninentional data modification, dbt will **not** automatically apply any column renames. So if a user applyies `snapshot_meta_column_names` config for a snapshot without updating the pre-existing table, they will get an error. Our recommendation is to either only use these settings for net-new snapshots, or to arrange an update of pre-existing tables prior to committing a column name change.
+
+:::
+
+## Example
+
+<File name='snapshots/schema.yml'>
+
+```yaml
+snapshots:
+  - name: orders_snapshot
+    relation: ref("orders")
+    config:
+      unique_key: id
+      strategy: check
+      check_cols: all
+      snapshot_meta_column_names:
+        dbt_valid_from: start_date
+        dbt_valid_to: end_date
+        dbt_scd_id: scd_id
+        dbt_updated_at: modified_date
+```
+
+</File>
+
+The resulting snapshot table contains the configured meta column names:
+
+| id | scd_id               |        modified_date |           start_date |             end_date |
+| -- | -------------------- | -------------------- | -------------------- | -------------------- |
+|  1 | 60a1f1dbdf899a4dd... | 2024-10-02 ...       | 2024-10-02 ...       | 2024-10-02 ...       |
+|  2 | b1885d098f8bcff51... | 2024-10-02 ...       | 2024-10-02 ...       |                      |

website/docs/reference/snapshot-configs.md

@@ -69,6 +69,7 @@ snapshots:
     [+](/reference/resource-configs/plus-prefix)[strategy](/reference/resource-configs/strategy): timestamp | check
     [+](/reference/resource-configs/plus-prefix)[updated_at](/reference/resource-configs/updated_at): <column_name>
     [+](/reference/resource-configs/plus-prefix)[check_cols](/reference/resource-configs/check_cols): [<column_name>] | all
+    [+](/reference/resource-configs/plus-prefix)[snapshot_meta_column_names](/reference/resource-configs/snapshot_meta_column_names): {<dictionary>}
 
 ```
 
@@ -100,6 +101,7 @@ snapshots:
       [strategy](/reference/resource-configs/strategy): timestamp | check
       [updated_at](/reference/resource-configs/updated_at): <column_name>
       [check_cols](/reference/resource-configs/check_cols): [<column_name>] | all
+      [snapshot_meta_column_names](/reference/resource-configs/snapshot_meta_column_names): {<dictionary>}
 
 ```
 </File>
@@ -113,7 +115,6 @@ snapshots:
 <VersionBlock lastVersion="1.8">
 
 ```jinja
-
 {{ config(
     [target_schema](/reference/resource-configs/target_schema)="<string>",
     [target_database](/reference/resource-configs/target_database)="<string>",
@@ -139,6 +140,7 @@ snapshots:
     [strategy](/reference/resource-configs/strategy)="timestamp" | "check",
     [updated_at](/reference/resource-configs/updated_at)="<column_name>",
     [check_cols](/reference/resource-configs/check_cols)=["<column_name>"] | "all"
+    [snapshot_meta_column_names](/reference/resource-configs/snapshot_meta_column_names)={<dictionary>}
 ) }}
 
 ```

website/sidebars.js

@@ -974,6 +974,7 @@ const sidebarSettings = {
             "reference/resource-configs/unique_key",
             "reference/resource-configs/updated_at",
             "reference/resource-configs/invalidate_hard_deletes",
+            "reference/resource-configs/snapshot_meta_column_names",
           ],
         },
         {