add event_time page

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

@@ -20,7 +20,7 @@ Refer to [Supported incremental strategies by adapter](/docs/build/incremental-s
 
 Incremental models in dbt are a [materialization](/docs/build/materializations) designed to efficiently update your data warehouse tables by only transforming and loading _new or changed data_ since the last run. Instead of reprocessing an entire dataset every time, incremental models process a smaller number of rows, and then append, update, or replace those rows in the existing table. This can significantly reduce the time and resources required for your data transformations.
 
-Microbatch incremental models make it possible to process transformations on very large time-series datasets with efficiency and resiliency. When dbt runs a microbatch model — whether for the first time, during incremental runs, or in specified backfills — it will split the processing into multiple queries (or "batches"), based on the `event_time` and `batch_size` you configure.
+Microbatch incremental models make it possible to process transformations on very large time-series datasets with efficiency and resiliency. When dbt runs a microbatch model — whether for the first time, during incremental runs, or in specified backfills — it will split the processing into multiple queries (or "batches"), based on the [`event_time`](/reference/resource-configs/event-time) and `batch_size` you configure.
 
 Each "batch" corresponds to a single bounded time period (by default, a single day of data). Where other incremental strategies operate only on "old" and "new" data, microbatch models treat every batch as an atomic unit that can be built or replaced on its own. Each batch is independent and <Term id="idempotent" />. This is a powerful abstraction that makes it possible for dbt to run batches separately — in the future, concurrently — and to retry them independently.
 
@@ -162,7 +162,7 @@ Several configurations are relevant to microbatch models, and some are required:
 
 | Config   | Type | Description   | Default |
 |----------|------|---------------|---------|
-| `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     |
+| [`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`      | 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` | String (required)  | The granularity of your batches. Supported values are `hour`, `day`, `month`, and `year`             | N/A     |
 | `lookback`   | Integer (optional) | Process X batches prior to the latest bookmark to capture late-arriving records.                                         | `1`     |

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

@@ -20,6 +20,7 @@
 
 ## October 2024
 
+- **New**: Use the `event_time` configuration to specify when an event occurred. This configuration is required for [Incremental mircrobatch](/docs/build/incremental-microbatch) and can be added to ensure you're comparing overlapping times in [Advanced CI's compare changes](/docs/deploy/advanced-ci). Available in dbt Cloud Versionless and dbt Core v1.9 and higher. Refer to [event_time](/reference/resource-configs/event-time) for more information.
 - **Fix:** Previously, POST requests to the Jobs API with invalid `cron` strings would return HTTP response status code 500s but would update the underlying entity. Now, POST requests to the Jobs API with invalid `cron` strings will result in status code 400s, without the underlying entity being updated.
 - **Fix:** Fixed an issue where the `Source` view page in dbt Explorer did not correctly display source freshness status if older than 30 days.
 - **Fix:** The UI now indicates when the description of a model is inherited from a catalog comment.

website/docs/docs/deploy/advanced-ci.md

@@ -31,6 +31,18 @@
 
 <Lightbox src="/img/docs/dbt-cloud/example-ci-compare-changes-tab.png" width="85%" title="Example of the Compare tab" />
 
+### Considerations
+You can set a [event_time](/reference/resource-configs/event-time) for a model, seed, snapshot, or source to represent the actual timestamp of the event, rather than something like loading date. This configuration is important for certain features, such as [Incremental microbatch](/docs/build/incremental-microbatch) and compare changes in CI/CD workflows, where it ensures the same time-slice of data is accurately compared between your CI and production environments.
+
+When configured, `event_time` enables compare changes to:
+
+- Compare data in CI versus production for overlapping times only, reducing false discrepancies.
+- Handle scenarios where CI contains fresher data than production by using only the overlapping timeframe, which avoids incorrect row-count changes.
+- Account for subset data builds in CI without flagging filtered-out rows as "deleted" when compared with production.
+- Coming soon, you'll be able to add a flag to the command list allowing you to select the specific time slice to compare.
+
+<Lightbox src="/img/docs/deploy/apples_to_apples.png" title="event_time ensures the same time-slice of data is accurately compared between your CI and production environments." />
+
 ## About the cached data
 
 After [comparing changes](#compare-changes), dbt Cloud stores a cache of no more than 100 records for each modified model for preview purposes. By caching this data, you can view the examples of changed data without rerunning the comparison against the data warehouse every time (optimizing for lower compute costs). To display the changes, dbt Cloud uses a cached version of a sample of the data records. These data records are queried from the database using the connection configuration (such as user, role, service account, and so on) that's set in the CI job's environment. 

website/docs/reference/resource-configs/event-time.md

@@ -0,0 +1,247 @@
+---
+title: "event_time"
+id: "event-time"
+sidebar_label: "event_time"
+resource_types: [models, seeds, source]
+description: "Setting the event_time config allows you to specify when an event occurred. It's required for microbatch and can added to ensure you're comparing overlapping times in compare changes"
+datatype: string
+---
+
+Available in dbt Cloud Versionless and dbt Core v1.9 and higher.
+
+<Tabs>
+<TabItem value="model" label="Models">
+
+<File name='dbt_project.yml'>
+
+```yml
+models:
+  [resource-path:](/reference/resource-configs/resource-path)
+    +event_time: my_time_field
+```
+</File>
+
+
+<File name='models/properties.yml'>
+
+```yml
+models:
+  - name: model_name
+    [config](/reference/resource-properties/config):
+      event_time: my_time_field
+```
+</File>
+
+<File name="models/modelname.sql">
+
+```sql
+{{ config(
+    event_time='my_time_field'
+) }}
+```
+
+</File>
+
+</TabItem>
+
+<TabItem value="seeds" label="Seeds">
+
+<File name='dbt_project.yml'>
+
+```yml
+seeds:
+  [resource-path:](/reference/resource-configs/resource-path)
+    +event_time: my_time_field
+```
+</File>
+
+<File name='seeds/properties.yml'>
+
+```yml
+seeds:
+  - name: seed_name
+    [config](/reference/resource-properties/config):
+      event_time: my_time_field
+```
+
+</File>
+</TabItem>
+
+<TabItem value="snapshot" label="Snapshots">
+
+<File name='dbt_project.yml'>
+
+```yml
+snapshots:
+  [resource-path:](/reference/resource-configs/resource-path)
+    +event_time: my_time_field
+```
+</File>
+
+<VersionBlock firstVersion="1.9">
+<File name='snapshots/properties.yml'>
+
+```yml
+snapshots:
+  - name: snapshot_name
+    [config](/reference/resource-properties/config):
+      event_time: my_time_field
+```
+</File>
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
+<File name="models/modlename.sql">
+
+```sql
+
+{{ config(
+    event_time: 'my_time_field'
+) }}
+```
+
+</File>
+
+
+import SnapshotYaml from '/snippets/_snapshot-yaml-spec.md';
+
+<SnapshotYaml/>
+</VersionBlock>
+
+
+
+</TabItem>
+
+<TabItem value="sources" label="Sources">
+
+<File name='dbt_project.yml'>
+
+```yml
+sources:
+  [resource-path:](/reference/resource-configs/resource-path)
+    +event_time: my_time_field
+```
+</File>
+
+<File name='models/properties.yml'>
+
+```yml
+sources:
+  - name: source_name
+    [config](/reference/resource-properties/config):
+      event_time: my_time_field
+```
+
+</File>
+</TabItem>
+</Tabs>
+
+## Definition
+
+Set the `event_time` to the name of the field that represents the timestamp of the event, as opposed to a date like data loading date.  You can configure `event_time` for a [model](/docs/build/models), [seed](/docs/build/seeds), or [source](/docs/build/sources) in your `dbt_project.yml` file, property YAML file, or config block. 
+
+`event_time` is required for [Incremental mircrobatch](/docs/build/incremental-microbatch) and [Advanced CI's compare changes](/docs/deploy/advanced-ci) in CI/CD workflows, where it ensures the same time-slice of data is correctly compared between your CI and production environments.
+
+When you configure `event_time`, it enables compare changes to:
+
+- Compare data in CI versus production for overlapping times only, reducing false discrepancies.
+- Handle scenarios where CI has "fresher" data than production by using only the overlapping timeframe, allowing you to avoid incorrect row-count changes.
+- Account for subset data builds in CI without flagging filtered-out rows as "deleted" when compared with production.
+
+## Examples
+
+<Tabs> 
+
+<TabItem value="model" label="Models">
+
+Here's an example in the `dbt_project.yml` file:
+
+<File name='dbt_project.yml'>
+
+```yml
+models:
+  my_project:
+    user_sessions:
+      +event_time: session_start_time
+```
+</File>
+
+Example in a properties YAML file:
+
+<File name='models/properties.yml'>
+
+```yml
+models:
+  - name: user_sessions
+    config:
+      event_time: session_start_time
+```
+
+</File>
+
+Example in sql model config block:
+
+<File name="models/user_sessions.sql">
+
+```sql
+{{ config(
+    event_time='session_start_time'
+) }}
+```
+
+</File> 
+
+This setup sets `session_start_time` as the `event_time` for the `user_sessions` model, which makes sure the compare changes process uses this timestamp for time-slice comparisons or incremental microbatching.
+</TabItem> 
+
+<TabItem value="seeds" label="Seeds">
+
+Here's an example in the `dbt_project.yml` file:
+
+<File name='dbt_project.yml'>
+
+```yml
+seeds:
+  my_project:
+    my_seed:
+      +event_time: record_timestamp
+```
+
+</File>
+
+Example in a seed properties YAML:
+
+<File name='seeds/properties.yml'>
+
+```yml
+seeds:
+  - name: my_seed
+    config:
+      event_time: record_timestamp
+```
+</File>
+
+This setup sets `record_timestamp` as the `event_time` for `my_seed`. This ensures that the `record_timestamp` is used consistently for compare changes processes or incremental microbatching.
+
+</TabItem> 
+<TabItem value="sources" label="Sources">
+
+Here's an example of source properties YAML file:
+
+<File name='models/properties.yml'>
+
+```yml
+sources:
+  - name: source_name
+    tables:
+      - name: table_name
+        config:
+          event_time: event_timestamp
+```
+</File>
+
+This setup sets `event_timestamp` as the `event_time` for the specified source table.
+
+</TabItem> 
+</Tabs>

website/sidebars.js

@@ -926,6 +926,7 @@ const sidebarSettings = {
             "reference/resource-configs/alias",
             "reference/resource-configs/database",
             "reference/resource-configs/enabled",
+            "reference/resource-configs/event-time",
             "reference/resource-configs/full_refresh",
             "reference/resource-configs/contract",
             "reference/resource-configs/grants",