ga4-export-fixer 0.4.1-dev.0 → 0.4.1-dev.2

package/columns/columnDescriptions.json

@@ -157,7 +157,7 @@
         }
     },
     "session_first_traffic_source": {
-        "description": "The collected_traffic_source from the first event in the session (ordered by timestamp, nulls included). Useful for session-level first-click attribution",
+        "description": "The data extracted from the collected_traffic_source struct of the session's first event. Similar to the session_traffic_source_last_click but does not include last non-direct attribution. Meaning that sessions that started without a source of traffic are always reported as direct in this field. Can be useful for building custom attribution models.",
         "columns": {
             "manual_campaign_id": "Manual campaign ID (utm_id)",
             "manual_campaign_name": "Manual campaign name (utm_campaign)",
@@ -209,7 +209,7 @@
                     "source_platform": "Cross-channel source platform",
                     "source": "Cross-channel source",
                     "medium": "Cross-channel medium",
-                    "primary_channel_group": "Custom primary channel group for the session's last non-direct click",
+                    "primary_channel_group": "The highest-level traffic categorization (e.g., Organic Search, Paid Social). Use this as the default dimension for all general 'traffic source' questions",
                     "default_channel_group": "Default channel group for the session's last non-direct click"
                 }
             },

package/columns/columnTypicalUse.json

@@ -16,7 +16,7 @@
     "items": "Product-level data array. Unnest with CROSS JOIN UNNEST(items) for item-level analysis. For product revenue and units sold, filter to event_name = 'purchase' and use item_revenue and quantity. Use item_category to filter or group by product category",
     "collected_traffic_source": "Event-level UTM parameters and click identifiers. For session-level attribution, prefer session_first_traffic_source instead",
     "session_first_traffic_source": "First-touch traffic source for the session. Use for session-level acquisition and campaign reporting",
-    "session_traffic_source_last_click": "Google-attributed session traffic source. Use for last-click attribution analysis across Google Ads and manual channels",
+    "session_traffic_source_last_click": "Google-attributed session traffic source. For high-level 'traffic source' reporting, ALWAYS use .cross_channel_campaign.primary_channel_group as the primary dimension. Use .cross_channel_campaign.source as a secondary drill-down when granular detail is required",
     "data_is_final": "Data stability flag. Use WHERE data_is_final = true when you need only stable data that will not change in future refreshes",
     "export_type": "Source export type (daily, intraday, fresh). Use for debugging data freshness or filtering by export source",
     "row_inserted_timestamp": "Pipeline metadata. Use to identify when data was last refreshed or to debug incremental update issues"

package/columns/tableAgentInstructions.json

@@ -42,7 +42,7 @@
         },
         {
             "terms": ["traffic source", "channel", "channel group", "source of traffic"],
-            "sql": "session_traffic_source_last_click.cross_channel_campaign.primary_channel_group for top-level channel grouping. session_traffic_source_last_click.cross_channel_campaign.source, session_traffic_source_last_click.cross_channel_campaign.medium, and session_traffic_source_last_click.cross_channel_campaign.campaign_name for detailed source/medium/campaign analysis.",
+            "sql": "Drill-down hierarchy: (1) .primary_channel_group is the default — always use when asked vaguely about traffic sources or channels. (2) .source and .medium — use when asked for source/medium breakdown. (3) .campaign_name — use when asked for campaign-level detail. All under session_traffic_source_last_click.cross_channel_campaign.",
             "dependsOn": ["session_traffic_source_last_click"]
         },
         {
@@ -99,7 +99,7 @@
         },
         {
             "field": "session_traffic_source_last_click",
-            "note": "Primary field for traffic source analysis. Use .cross_channel_campaign.primary_channel_group for channel grouping. When asked about popular traffic sources, default to channel group unless specified otherwise.",
+            "note": "Primary field for traffic source analysis. When a user asks a general or vague question about 'traffic sources' or 'where traffic comes from', DEFAULT to .cross_channel_campaign.primary_channel_group. Only drill down to .source if the user explicitly mentions 'source' or specific site names.",
             "dependsOn": ["session_traffic_source_last_click"]
         },
         {

package/package.json

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