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

@@ -26,6 +26,9 @@
   - Better error messaging for queries that can't be parsed correctly.
 
 ## October 2024
+
+- **New**: Use the `event_time` configuration to specify when an event occurred. This configuration is required for [Incremental microbatch](/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.
+
 <Expandable alt_header="Coalesce 2024 announcements">
 
   Documentation for new features and functionality announced at Coalesce 2024:

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

@@ -31,6 +31,14 @@ dbt reports the comparison differences in:
 
 <Lightbox src="/img/docs/dbt-cloud/example-ci-compare-changes-tab.png" width="85%" title="Example of the Compare tab" />
 
+### Speeding up comparisons
+It's common for CI jobs to only [build a subset of data](/best-practices/best-practice-workflows#limit-the-data-processed-when-in-development), for example only the last 7 days of data. When an [`event_time`](/reference/resource-configs/event-time) column is specified on your model, compare changes can:
+
+- Compare data in CI against production for only the overlapping times, avoiding false positives and returning results faster.
+- Handle scenarios where CI contains fresher data than production by using only the overlapping timeframe, which avoids incorrect row-count changes.
+
+<Lightbox src="/img/docs/deploy/apples_to_apples.png" width="90%" 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,258 @@
+---
+title: "event_time"
+id: "event-time"
+sidebar_label: "event_time"
+resource_types: [models, seeds, source]
+description: "dbt uses event_time to understand when an event occurred. When defined, event_time enables microbatch incremental models and more refined comparison of datasets during Advanced CI."
+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. 
+
+Here are some examples of good and bad `event_time` columns:
+✅ Good:
+
+- `account_created_at` &mdash; This represents the specific time when an account was created, making it a fixed event in time.
+- `session_began_at` &mdash; This captures the exact timestamp when a user session started, which won’t change and directly ties to the event.
+
+❌ Bad:
+
+- `_fivetran_synced` &mdash; This isn't the time that the event happened, it's the time that the event was ingested.
+- `last_updated_at` &mdash; This isn't a good use case as this will keep changing over time. 
+
+`event_time` is required for [Incremental microbatch](/docs/build/incremental-microbatch) and [Advanced CI's compare changes](/docs/deploy/advanced-ci#speeding-up-comparisons) 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.
+- Accounts 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. This 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`. It ensures that the `record_timestamp` is used consistently in [Advanced CI's compare changes](/docs/deploy/advanced-ci#speeding-up-comparisons) or [incremental microbatching](/docs/build/incremental-microbatch).
+
+</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",