ga4-export-fixer 0.6.2-dev.4 → 0.7.1-dev.0

package/README.md

@@ -1,6 +1,10 @@
-# ga4-export-fixer
+<img src="docs/images/header.svg" alt="ga4-export-fixer">
+
+# An enhanced, incremental GA4 events table, built with Dataform
 
 [![npm version](https://img.shields.io/npm/v/ga4-export-fixer)](https://www.npmjs.com/package/ga4-export-fixer)
+[![License](https://img.shields.io/npm/l/ga4-export-fixer)](https://github.com/tanelytics/ga4-export-fixer/blob/main/LICENSE)
+![Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
 
 **ga4-export-fixer** is a **Dataform NPM package** that transforms raw GA4 BigQuery export data into a cleaner, more queryable incremental table. It combines **daily, fresh (360), and intraday exports** so the best available version of each event is always in use, adds session-level fields like `session_id` and `landing_page`, promotes key event parameters to columns, and fixes known GA4 export issues — handling the boilerplate transformations that are otherwise tedious to include in every GA4 query.
 
@@ -10,10 +14,10 @@ The goal of the package is to **speed up development** when building data models
 
 *Example data model built with ga4-export-fixer*
 
-### Table of Contents
+## Table of Contents
 <!-- TOC -->
-  - [Main Features](#main-features)
-  - [Planned, Upcoming Features](#planned-upcoming-features)
+- [Main Features](#main-features)
+- [Planned Features](#planned-features)
 - [Installation](#installation)
   - [Bash](#bash)
   - [In Google Cloud Dataform](#in-google-cloud-dataform)
@@ -21,12 +25,12 @@ The goal of the package is to **speed up development** when building data models
   - [Create GA4 Events Enhanced Table](#create-ga4-events-enhanced-table)
   - [Configuration Object](#configuration-object)
   - [Assertions](#assertions)
-  - [Creating Incremental Downstream Tables from ga4_events_enhanced](#creating-incremental-downstream-tables-from-ga4_events_enhanced)
+  - [Creating Incremental Downstream Tables from `ga4_events_enhanced`](#creating-incremental-downstream-tables-from-ga4_events_enhanced)
   - [Helpers](#helpers)
 - [License](#license)
 <!-- /TOC -->
 
-### Main Features
+## Main Features
 
 <table>
 <tr>
@@ -105,31 +109,33 @@ The goal of the package is to **speed up development** when building data models
   <code>data_is_final</code> flag and <code>export_type</code> label on every row
 </td>
 <td valign="top">
-  <b>🔃 Selective Re-processing</b><br>
-  Re-process a date range without full table rebuild using <code>incrementalStartOverride</code> and <code>incrementalEndOverride</code>
+  <b>🔍 Data Quality Assertions</b><br>
+  Built-in daily assertion reconciles sessions, events, and revenue between the enhanced table and raw export
 </td>
 </tr>
 <tr>
+<td valign="top">
+  <b>🔃 Selective Re-processing</b><br>
+  Re-process a date range without full table rebuild using <code>incrementalStartOverride</code> and <code>incrementalEndOverride</code>
+</td>
 <td valign="top">
   <b>📑 Batch Processing</b><br>
   Process large exports in smaller batches via <code>numberOfDaysToProcess</code>
 </td>
+</tr>
+<tr>
 <td valign="top">
   <b>🕐 Timezone-Aware Datetime</b><br>
   <code>event_datetime</code> converted to a configurable IANA timezone
 </td>
-</tr>
-<tr>
 <td valign="top">
   <b>🛡️ Zero Dependencies</b><br>
   No additional external dependencies added to your Dataform repository
 </td>
-<td valign="top">
-</td>
 </tr>
 </table>
 
-### Planned, Upcoming Features
+## Planned Features
 
 Features under consideration for future releases:
 
@@ -138,7 +144,6 @@ Features under consideration for future releases:
 - Data enrichment (item-level, session-level, event-level)
 - Custom processing steps (additional CTEs)
 - Custom traffic source attribution
-- Default assertions
 
 ## Installation
 
@@ -158,7 +163,7 @@ Include the package in the package.json file in your Dataform repository.
 {
   "dependencies": {
     "@dataform/core": "3.0.42",
-    "ga4-export-fixer": "0.6.1"
+    "ga4-export-fixer": "0.7.0"
   }
 }
 ```
@@ -175,11 +180,11 @@ If your Dataform repository does not have a package.json file, see this guide: [
 
 Creates an **enhanced** version of the GA4 BigQuery export (daily & intraday).
 
-#### JS Deployment (Recommended)
+#### JS Deployment (Recommended) ![.JS](https://img.shields.io/badge/.JS-F7DF1E?style=flat-square)
 
 Create a new **ga4_events_enhanced** table using a **.js** file in your repository's **definitions** folder.
 
-##### Using Defaults
+**Using Defaults**
 
 **`definitions/ga4/ga4_events_enhanced.js`**
 
@@ -193,7 +198,7 @@ const config = {
 ga4EventsEnhanced.createTable(publish, config);
 ```
 
-##### With Custom Configuration
+**With Custom Configuration**
 
 **`definitions/ga4/ga4_events_enhanced.js`**
 
@@ -256,7 +261,7 @@ const config = {
 ga4EventsEnhanced.createTable(publish, config);
 ```
 
-#### SQLX Deployment
+#### SQLX Deployment ![.SQLX](https://img.shields.io/badge/.SQLX-4285F4?style=flat-square)
 
 Alternatively, you can create the **ga4_events_enhanced** table using a .SQLX file.
 
@@ -292,6 +297,10 @@ pre_operations {
 }
 ```
 
+<br>
+
+---
+
 ### Configuration Object
 
 All fields are optional except `sourceTable`. Default values are applied automatically, so you only need to specify the fields you want to override.
@@ -445,6 +454,10 @@ itemListAttribution: { lookbackType: 'TIME', lookbackTimeMs: 86400000 }
 
 > **Note:** This feature adds a compute-heavy CTE with a window function over unnested items. Only enable it if you need item list attribution for ecommerce analysis.
 
+<br>
+
+---
+
 ### Assertions
 
 The package includes built-in data quality assertions that can be automatically created alongside the enhanced events table. Pass Dataform's `assert` function as the third argument to `createTable`:
@@ -503,7 +516,11 @@ assert('daily_quality_check', {
 });
 ```
 
-### Creating Incremental Downstream Tables from ga4_events_enhanced
+<br>
+
+---
+
+### Creating Incremental Downstream Tables from `ga4_events_enhanced`
 
 Setting up incremental updates is easy using the **setPreOperations()** function. Just ensure that your result table includes the **data_is_final** flag from the **ga4_events_enhanced** table.
 
@@ -573,6 +590,10 @@ pre_operations {
 }
 ```
 
+<br>
+
+---
+
 ### Helpers
 
 The helpers contain templates for common SQL expressions. The functions are referenced by **ga4EventsEnhanced** but can also be imported as utility functions for working with GA4 data.

package/helpers/ga4Transforms.js

@@ -195,6 +195,40 @@ const itemListAttributionExpr = (lookbackType, timestampColumn, lookbackTimeMs)
     )`;
 };
 
+/**
+ * Generates a SQL expression for a deterministic hash-based row id used by the
+ * item list attribution join. Only computed for events in `ecommerceEventsFilter`;
+ * other events get NULL.
+ *
+ * The row_number() window keeps the id stable across CTE re-evaluations:
+ * BigQuery may inline the CTE and re-run the window per reference, so without
+ * a stable ordering the two sides of the downstream join could hash differently.
+ * partition by event_name avoids a single-partition bottleneck.
+ * Residual collisions (identical event_timestamp + identical items) are safe —
+ * the rows are interchangeable, so arbitrary row number assignment between them
+ * produces the same result.
+ *
+ * @param {string} ecommerceEventsFilter - Comma-separated, quoted list of event names
+ *        (e.g., "'purchase', 'add_to_cart'").
+ * @returns {string} SQL expression that evaluates to the row id or NULL.
+ */
+const itemListAttributionRowId = (ecommerceEventsFilter) => {
+  return `if(
+      event_name in (${ecommerceEventsFilter}),
+      farm_fingerprint(concat(
+        user_pseudo_id,
+        cast(event_timestamp as string),
+        event_name,
+        to_json_string(items),
+        cast(row_number() over(
+          partition by event_name, user_pseudo_id
+          order by event_timestamp, to_json_string(items)
+        ) as string)
+      )),
+      null
+    )`;
+};
+
 /**
  * Official GA4 ecommerce events that carry item data.
  * Based on: https://developers.google.com/analytics/devguides/collection/ga4/ecommerce
@@ -223,5 +257,6 @@ module.exports = {
   isGa4ExportColumn,
   getGa4ExportType,
   itemListAttributionExpr,
+  itemListAttributionRowId,
   ga4EcommerceEvents
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ga4-export-fixer",
-  "version": "0.6.2-dev.4",
+  "version": "0.7.1-dev.0",
   "description": "",
   "main": "index.js",
   "files": [

package/tables/ga4EventsEnhanced/index.js

@@ -229,12 +229,7 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
             // ecommerce
             ecommerce: helpers.fixEcommerceStruct('ecommerce'),
             items: 'items',
-            // unique row id for item list attribution join. Only computed for ecommerce events.
-            // row_number() breaks hash collisions for batched events with identical data.
-            // partition by event_name avoids a single-partition bottleneck in the window function.
-            // Non-determinism is safe: colliding rows have identical items (to_json_string(items) is in the hash),
-            // so swapping row numbers between them produces the same final result.
-            _item_list_attribution_row_id: itemListAttribution ? `if(event_name in (${ecommerceEventsFilter}), farm_fingerprint(concat(user_pseudo_id, cast(event_timestamp as string), event_name, to_json_string(items), cast(row_number() over(partition by event_name, user_pseudo_id) as string))), null)` : undefined,
+            _item_list_attribution_row_id: itemListAttribution ? helpers.itemListAttributionRowId(ecommerceEventsFilter) : undefined,
             // flag if the data is "final" and is not expected to change anymore
             data_is_final: helpers.isFinalData(mergedConfig.dataIsFinal.detectionMethod, mergedConfig.dataIsFinal.dayThreshold),
             export_type: helpers.getGa4ExportType('_table_suffix'),