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

@@ -19,6 +19,7 @@
 \* The official release date for this new format of release notes is May 15th, 2024. Historical release notes for prior dates may not reflect all available features released earlier this year or their tenancy availability.
 
 ## November 2024
+- **New**: Use the `event_time` configuration to specify "at what time did the row occur." 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.
 - **Fix**: This update improves [dbt Semantic Layer Tableau integration](/docs/cloud-integrations/semantic-layer/tableau) making query parsing more reliable. Some key fixes include:
   - Error messages for unsupported joins between saved queries and ALL tables.
   - Improved handling of queries when multiple tables are selected in a data source.
@@ -27,6 +28,7 @@
 - **Enhancement**: The dbt Semantic Layer supports creating new credentials for users who don't have permissions to create service tokens.  In the **Credentials & service tokens** side panel, the **+Add Service Token** option is unavailable for those users who don't have permission. Instead, the side panel displays a message indicating that the user doesn't have permission to create a service token and should contact their administration. Refer to [Set up dbt Semantic Layer](/docs/use-dbt-semantic-layer/setup-sl) for more details.
 
 ## October 2024
+
 <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,17 @@ 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
+
+
+When an [`event_time`](/reference/resource-configs/event-time) column is specified on your model, compare changes can optimize comparisons by using only the overlapping timeframe (meaning the timeframe exists in both the CI and production environment), helping you avoid incorrect row-count changes and return results faster.
+
+This is useful in scenarios like:
+- **Subset of data in CI** &mdash; When CI builds only a [subset of data](/best-practices/best-practice-workflows#limit-the-data-processed-when-in-development) (like the most recent 7 days), compare changes might interpret the excluded data as "deleted rows." Configuring `event_time` allows you to avoid this issue by limiting comparisons to the overlapping timeframe, preventing false alerts about data deletions that are just filtered out in CI.
+- **Fresher data in CI than in production** &mdash; When your CI job includes fresher data than production (because it has run more recently), compare changes might flag the additional rows as "new" data, even though they’re just fresher data in CI. With `event_time` configured, the comparison only includes the shared timeframe and correctly reflects actual changes in the data.
+
+<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,284 @@
+---
+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 -- "at what time did the row occur" -- as opposed to an event ingestion 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 highly recommended for [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.
+
+## 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.
+</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="snapshot" label="Snapshots">
+
+Here's an example in the `dbt_project.yml` file:
+
+<File name='dbt_project.yml'>
+
+```yml
+snapshots:
+  my_project:
+    my_snapshot:
+      +event_time: record_timestamp
+```
+
+</File>
+
+Example in a snapshot properties YAML:
+
+<File name='my_project/properties.yml'>
+
+```yml
+snapshots:
+  - name: my_snapshot
+    config:
+      event_time: record_timestamp
+```
+</File>
+
+This setup sets `record_timestamp` as the `event_time` for `my_snapshot`. 
+
+</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",