Configuration Variables

Click on each card below to see more details!

Full Custom Config file (for easy copying)

Description: Below is a full, ready-to-copy, Premium compatible custom config file (includes/custom/config.js) that you can use if you updated from Core (since we don't overwrite config.js files during updates).

Existing variables

Remember to save your current variables before proceeding - you'll need to restore them afterward.

const { helpers } = require("../core/helpers");
const lowerSQL = helpers.lowerSQL;

/*
    ga4dataform runs the core model with SQL that can be tweaked with
    configuration settings in this file.

    Below, you will find a sample config file that you can tweak to
    your likings.

    See the documentation for all details.
*/

// config object should be a valid javascript object


const customConfig = {
  // on a new or full build, this start date will be picked

  GA4_START_DATE: "2020-01-01",

  // include support for fresh and intraday tables?
  // These can both be enabled, only 1 tableset per day is used
  // events_ takes priority over fresh_, takes priority over intraday_
  USE_FRESH_EVENTS: true,
  USE_INTRADAY_EVENTS: false,

  // custom definitions
  // a very complete list of all recommended and standard event parameters is
  // included in the `event_params` column.
  // If you have custom definitions, add them here and they will appear in 
  // the `events_params_custom` column.

  // all custom_ arrays should be in the form:
  // 
  // { name: "paramname", type: "TYPE", renameTo: "outputcolumnname" }
  //
  // "paramname" will be extracted from the data (event param / user property / item custom dim / url parameter)
  // TYPE will be the column type.
  // - "int" -> look for int_value, store as INT
  // - "string" -> look for all values, store as STRING
  // - "decimal" -> look for all numerical values, store as FLOAT
  // options:
  // - "renameTo" -> name the output column to this name. Default: "paramname" will be used
  // cleaningMethod: lowerSQL -> transform the output (of strings) to lower case
 
  // event dimensions and metrics
  // example:
  // CUSTOM_EVENT_PARAMS_ARRAY: [
  //    { name: "event_value", type: "decimal" },
  //    { name: "event_value", type: "string", renameTo: "event_value_string" }
  // ],
  CUSTOM_EVENT_PARAMS_ARRAY: [],

  // user properties
  // example:
  // CUSTOM_USER_PROPERTIES_ARRAY: [
  //    { name: "lifetime_value",   type: "decimal" }
  // ],
  CUSTOM_USER_PROPERTIES_ARRAY: [],

  // item custom dimensions and metrics
  // these will appear in `items.item_params_custom.*`
  // example:
  // CUSTOM_ITEM_PARAMS_ARRAY: [
  //    { name: "stock_status", type: "string" }
  // ]
  CUSTOM_ITEM_PARAMS_ARRAY: [],

  // URL parameters to extract to own column
  // (note: all standard utm params are already extracted to `url_params`)
  // custom url params will appear in `url_params_custom`
  // (this does NOT support the "type" key: only strings are supported)

  // Examples based on internal search engine params:
  //   CUSTOM_URL_PARAMS_ARRAY: [
  //      { name: "q", cleaningMethod: lowerSQL },
  //      { name: "s", cleaningMethod: lowerSQL },
  //      { name: "search",cleaningMethod: lowerSQL }
  //   ],
  CUSTOM_URL_PARAMS_ARRAY: [],

  // include session-level custom parameters in the sessions table. These will end up in
  // int_ga4_sessions and ga4_sessions in the column `session_params_custom`.
  // In the "pick" property you can choose how you want to select a single value
  // of a parameter per session. It supports: first, last, min, max, boolean methods.
  // example:
  // CUSTOM_SESSION_PARAMS_ARRAY: [
  //   { name: "event_params_custom.lead_id", pick: "first", renameTo: "initial_lead_id", description: "First lead ID captured in session" },
  //   { name: "event_params_custom.lead_status", pick: "last", renameTo: "final_lead_status", description: "Final lead qualification status in session" },
  //   { name: "safe_cast(event_params_custom.engagement_score as INT64)", pick: "max", renameTo: "peak_engagement_score", description: "Highest user engagement score achieved in session" },
  //   { name: "safe_cast(event_params_custom.plan_price as NUMERIC)", pick: "min", renameTo: "lowest_price_viewed", description: "Lowest pricing plan amount viewed in session" },
  //   { name: "event_params_custom.feature_tier", pick: "boolean", renameTo: "viewed_premium_features", description: "Whether user explored premium feature tiers" }
  // ],
  // Warning: item fields are not (yet) supported!
  CUSTOM_SESSION_PARAMS_ARRAY: [],
 
  // provide a list of fields you want to aggregate. These will end up in 
  // int_ga4_sessions and ga4_sessions in the corresponding STRUCT `totals.count/distinct_count/has_event/sum`
  // examples that show allowed formatting options:
  // CUSTOM_SESSION_TOTALS: {
  //   eventsToCount: [
  //     'page_view',
  //     { name: 'sign_up', renameTo: 'registrations'},
  //     { name: ['video_start', 'video_progress', 'video_complete'], renameTo: 'video_engagement' }
  //   ],
  //   uniqueFields: [
  //     { name: 'ecommerce.transaction_id', renameTo: 'unique_transactions' },
  //     { name: 'event_params.currency', renameTo: 'funnel_currencies', eventFilter: ['begin_checkout', 'purchase'] },
  //   ],
  //   sumFields: [
  //     'event_params.video_duration',
  //     { name: 'event_params.engagement_time_msec', renameTo: 'total_engagement_time' },
  //     { name: 'ecommerce.purchase_revenue', eventFilter: 'purchase', renameTo: 'purchase_revenue' },
  //     { name: 'ecommerce.shipping_value', eventFilter: ['purchase', 'refund'], renameTo: 'net_shipping_value' },
  //   ]
  // },
  // Warning: item fields are not (yet) supported!
  CUSTOM_SESSION_TOTALS: {
    eventsToCount: [],
    uniqueFields: [],
    sumFields: [],
  },

  // filters
  // array: list the event names you want to exclude from the events table 
  EVENTS_TO_EXCLUDE: [],
  // arrays: list the hostnames you want to exclude (or include) from the events table
  // for including/excluding NULL values, use the empty string ( "" )
  HOSTNAME_EXCLUDE: [],
  HOSTNAME_INCLUDE_ONLY: [],

  // Set this to true to enable "Organic AI" (and possible other future channels that
  // are not compatible with GA4)
  EXTRA_CHANNEL_GROUPS: true,

  // attribution
  // if a visitors lands on your site without a source, we look back to
  // find a previous session of this user with a source. How many days?
  LAST_NON_DIRECT_LOOKBACK_DAYS: 90,

  
  // USER STITCHING object:
  // if enabled, we overwrite the user_id column in the ga4_sessions table based on user_pseudo_id

  // you can choose to add more stitching columns in the 'dimensions' array.
  // make sure the column names exist in the ga4_events table.
  // the output column in the sessions table will be a struct "stitched_ids" with these columns in them
  //
  // example:
  //    dimensions: [ 
  //      { name: "user_properties.customer_segment", renameTo: "customer_segment" },
  //      { name: "event_params.lead_id", renameTo: "lead_id" }
  //  ],
  //
  // lookBackDays: if session is found without a user_id, we look back to
  // find a previous session of this user with a user_id. How many days?
  // (default: 90, like the campaign lookback)
  //
  // lookAheadDays:  if session is found without a user_id in the past, we look ahead to 
  // find a future session of this user with a user_id. How many days?
  // Note: this will overwrite "already processed days" to de-anonimise sessions
  // (default: 0)

  USER_STITCHING: {
    enabled: false,
    dimensions: [],
    lookBackDays: 90,
    lookAheadDays: 10
  },

  // Use CUSTOM_EVENT_ID_PARAMETER to add another custom event parameter to the event_id
  // creation that makes an event unique. We usually recommend using a UNIX timestamp.
  CUSTOM_EVENT_ID_PARAMETER: '',

  // For the ga4_transactions table:
  // by default, we leave duplicate transaction_ids alone, but you can deduplicate here
  // note: setting this to true will still keep all transactions with NULL transaction_id
  TRANSACTIONS_DEDUPE: true,
  // we keep a running count for transactions, based on an identifier. Defaults to "user_pseudo_id"
  // if you have an other one, you can change it here (e.g. "user_id" - make sure it's a valid column)
  TRANSACTION_TOTALS_UID: 'user_pseudo_id',

  // assertions and quality checks can be toggled on (true) or off (false) here
  // quality checks can be toggled off by changing to false

  // assertions
  // id uniqueness checks
  ASSERTIONS_EVENT_ID_UNIQUENESS: false,
  ASSERTIONS_SESSION_ID_UNIQUENESS: false,

  // check for session durations and events look valid?
  ASSERTIONS_SESSION_DURATION_VALIDITY: false,
  ASSERTIONS_SESSIONS_VALIDITY: false, 
  // check GA4 tables: are they on time?
  ASSERTIONS_TABLES_TIMELINESS: false,
  // check for a transaction IDs on a purchase?
  ASSERTIONS_TRANSACTION_ID_COMPLETENESS: false,
  // check for cookies on all hits? (note: cookieless pings will trigger a fail)
  ASSERTIONS_USER_PSEUDO_ID_COMPLETENESS: false,

}



module.exports = {
    customConfig
};

GA4 Start Date

GA4_START_DATE: "2020-01-01"

Description: Defines the starting date for the GA4 data that the model should process.
Customization: Change this date to reflect the earliest data you want to include in your reports. For example, if you started collecting GA4 data on a different date, modify this to match that date.

Use Fresh Events 💎

USE_FRESH_EVENTS: true

Description: If you set this to true, ga4_events will query from fresh table shards if they are available. If events_* table also exists for the same date, that will be used. Priority for same date shards: 1. regular events_ 2. fresh_ (if enabled) 3. intraday_ (if enabled)

Use Intraday Events 💎

USE_INTRADAY_EVENTS: false

Description: If you set this to true, ga4_events will query from intraday table shards if they are available. Priority for same date shards: 1. regular events_ 2. fresh_ (if enabled) 3. intraday_ (if enabled)

Custom Event Parameters

CUSTOM_EVENT_PARAMS_ARRAY: []

Description: This allows you to specify custom event parameters that are not part of the standard GA4 data. The custom parameters will be added to the event_params_custom column in the ga4_events table.
Customization: Add parameters using the format { name: "paramname", type: "TYPE", renameTo: "outputcolumnname", description: "This parameter means XYZ" }.

Field	Description
name	Required. The original event parameter name to extract
type	Required. Data type for extraction and storage. `int`: Extracts from int_value, stores as INT; `string`: Extracts from all values, stores as STRING; `decimal`: Extracts from all numerical values, stores as FLOAT
renameTo	Optional. New name for the output column. If not specified, original parameter name is used
cleaningMethod	Optional. Transformation method to apply: `lowerSQL`: Converts string outputs to lowercase
description	Optional. Add a description for a column that will show up in the table schema

Example:

CUSTOM_EVENT_PARAMS_ARRAY: [
  { name: "gtm_info", type: "string", description: "GTM container ID + container version"},
  { name: "consent", type: "string", description: "The current consent status of the user"},
  { name: "page_type", type: "string", description: "The type of page: category, listing, product, home, checkout" }
]

User Properties

CUSTOM_USER_PROPERTIES_ARRAY: []

Description: Allows you to extract user properties into their own columns.
Customization: Define user properties you want to extract in the format { name: "param_name", cleaningMethod: method }. These will be stored in the user_properties column in the ga4_events table.

Field	Description
name	Required. The original user property name to extract
type	Required. Data type for extraction and storage. `int`: Extracts from int_value, stores as INT; `string`: Extracts from all values, stores as STRING; `decimal`: Extracts from all numerical values, stores as FLOAT
renameTo	Optional. New name for the output column. If not specified, original parameter name is used
cleaningMethod	Optional. Transformation method to apply: `lowerSQL`: Converts string outputs to lowercase
description	Optional. Add a description for a column that will show up in the table schema

Example:

  CUSTOM_USER_PROPERTIES_ARRAY: [
  { name: "user_tier", type: "string", description: "The loyalty tier of the user (e.g., 'gold', 'silver')" },
  { name: "lifetime_value", type: "decimal", renameTo: "ltv", description: "The calculated lifetime value of the user" },
  { name: "first_purchase_date", type: "string", description: "The date of the user's first purchase" }
]

Custom Item Parameters

CUSTOM_ITEM_PARAMS_ARRAY: []

Description: Similar to event parameters, but for item custom dimensions and metrics. These will be stored in the items.item_params_custom.* column in the ga4_events table. Customization: Add custom item parameters in the same format.

Field	Description
name	Required. The original item parameter name to extract
type	Required. Data type for extraction and storage. `int`: Extracts from int_value, stores as INT; `string`: Extracts from all values, stores as STRING; `decimal`: Extracts from all numerical values, stores as FLOAT
renameTo	Optional. New name for the output column. If not specified, original parameter name is used
cleaningMethod	Optional. Transformation method to apply: `lowerSQL`: Converts string outputs to lowercase
description	Optional. Add a description for a column that will show up in the table schema

Example:

CUSTOM_ITEM_PARAMS_ARRAY: [
  { name: "stock_status", type: "string", description: "Whether the item is currenly in_stock/low_stock/out_of_stock", cleaningMethod: lowerSQL },
  { name: "stock_amount", type: "string", description: "The amount of items currently in stock" },
  { name: "margin", type: "decimal", description: "Encoded margin for the item. It can be decoded for readability." }
]

Custom URL Parameters

CUSTOM_URL_PARAMS_ARRAY: []

Description: Allows you to extract custom URL parameters into their own columns. These will be stored in the url_params_custom.* column in the ga4_events table. Customization: Define custom URL parameters you want to extract in the format { name: "q", renameTo: "query_parameter", cleaningMethod: lowerSQL }. Note that URL params will always be strings.

Field	Description
name	Required. The original item parameter name to extract
renameTo	Optional. New name for the output column. If not specified, original parameter name is used
cleaningMethod	Optional. Transformation method to apply: `lowerSQL`: Converts string outputs to lowercase
description	Optional. Add a description for a column that will show up in the table schema

Example:

CUSTOM_URL_PARAMS_ARRAY: [
  { name: "q", cleaningMethod: lowerSQL },
  { name: "product-size", renameTo: "size" }
]

Custom Session Parameters 💎

  CUSTOM_SESSION_PARAMS_ARRAY: []

Description: Include session-level custom parameters in the sessions table. These will appear in int_ga4_sessions and ga4_sessions tables in the session_params_custom column. Customization: Add parameters with aggregation methods to select a single value per session.

Field	Description
name	Required. The full path to the parameter to aggregate (e.g., `event_params_custom.lead_id`). It should exist in the `ga4_events` table.
pick	Required. The method to select a single value: `first` (first non-null value based on timestamp), `last` (last non-null value), `min`, `max`, `boolean` (true if the parameter exists with any value at least once).
renameTo	Optional. New name for the output column. If not specified, original parameter name is used
cleaningMethod	Optional. Transformation method to apply: `lowerSQL`: Converts string outputs to lowercase
description	Optional. Add a description for a column that will show up in the table schema

Example:

  CUSTOM_SESSION_PARAMS_ARRAY: [
    { name: "event_params_custom.lead_id", pick: "first", renameTo: "initial_lead_id", description: "First lead ID captured in session" },
    { name: "event_params_custom.lead_status", pick: "last", renameTo: "final_lead_status", description: "Final lead qualification status in session" },
    { name: "safe_cast(event_params_custom.engagement_score as INT64)", pick: "max", renameTo: "peak_engagement_score", description: "Highest user engagement score achieved in session" },
    { name: "event_params_custom.feature_tier", pick: "boolean", renameTo: "viewed_premium_features", description: "Whether user explored premium feature tiers" }
  ]

Item fields are not (yet) supported!

This will throw an error:
{ name: "items.item_params_custom.stock_status", pick: "first" }

Custom Session Totals 💎

CUSTOM_SESSION_TOTALS: {
    eventsToCount: [],
    uniqueFields: [],
    sumFields: [],
  }

Description: Provide a list of fields you want to aggregate at the session level. These will end up in the int_ga4_sessions ga4_sessions table in the corresponding struct within totals (e.g., totals.count, totals.distinct_count, totals.has_events, totals.sum).

Customization: Configure the eventsToCount, uniqueFields, and sumFields arrays. You can use a simple string for the name or an object for more complex logic like renaming, filtering, or grouping events.

note

Column descriptions are auto-generated for session total fields based on the configuration!

Each array in CUSTOM_SESSION_TOTALS supports multiple format options to accommodate different use cases. Choose the format that best fits your needs!

Events to Count (`eventsToCount`)

Counts occurrences of specific events per session. Results are stored in totals.count.* and totals.has_event.* in int_ga4_sessions and ga4_sessions tables.

Supported Formats:

Format	Use Case	Example
String	Simple event counting	`'page_view'`
Object with metadata	Event counting with custom naming	`{ name: 'sign_up', renameTo: 'registrations' }`
Object with event array	Count multiple related events as one metric	`{ name: ['video_start', 'video_progress'], renameTo: 'video_interactions' }`

Available Fields:

name (required): Event name(s) to count - string or array of strings
renameTo (optional): Custom output column name

Unique Fields (`uniqueFields`)

Counts distinct values of specified fields per session. Results are stored in totals.distinct_count.* in int_ga4_sessions and ga4_sessions tables.

Supported Formats:

Format	Use Case	Example
Object with field path	Count unique values across all events	`{ name: 'ecommerce.transaction_id', renameTo: 'unique_transactions' }`
Object with event filter	Count unique values only from specific events	`{ name: 'event_params.currency', eventFilter: ['purchase', 'refund'], renameTo: 'transaction_currencies' }`

Available Fields:

name (required): Field path to count unique values from
eventFilter (optional): Limit counting to specific event types - string or array of strings
renameTo (optional): Custom output column name

Sum Fields (`sumFields`)

Sums numeric values of specified fields per session. Results are stored in totals.sum.* in int_ga4_sessions and ga4_sessions tables.

Supported Formats:

Format	Use Case	Example
String	Simple field summation across all events	`'event_params.video_duration'`
Object with metadata	Field summation with custom naming	`{ name: 'event_params.engagement_time_msec', renameTo: 'total_engagement' }`
Object with event filter	Sum values only from specific events	`{ name: 'ecommerce.purchase_revenue', eventFilter: ['purchase', 'refund'], renameTo: 'net_purchase_revenue' },`

Available Fields:

name (required): Field path to count unique values from
eventFilter (optional): Limit counting to specific event types - string or array of strings
renameTo (optional): Custom output column name

Example:

CUSTOM_SESSION_TOTALS: {
  eventsToCount: [
    'page_view',
    { name: 'sign_up', renameTo: 'registrations', description: 'User registration events in session' },
    { name: ['video_start', 'video_progress', 'video_complete'], renameTo: 'video_engagement', description: 'All video interaction events' }
  ],
  uniqueFields: [
    { name: 'ecommerce.transaction_id', renameTo: 'unique_transactions', description: 'Number of unique transaction IDs in session' },
    { name: 'event_params.currency', renameTo: 'funnel_currencies', eventFilter: ['begin_checkout', 'purchase'], description: 'Unique currencies used in checkout funnel' },
  ],
  sumFields: [
    { name: 'event_params.engagement_time_msec', renameTo: 'total_engagement_time', description: 'Sum of engagement time in milliseconds' },
    { name: 'ecommerce.purchase_revenue', eventFilter: ['purchase', 'refund'], renameTo: 'net_purchase_revenue' },
  ]
}

Item fields are not (yet) supported!

This will throw an error:
{ name: "items.item_params_custom.item_sku", eventFilter: ['purchase'] }

Event and Hostname Filters

Events to Exclude

EVENTS_TO_EXCLUDE: []

Description: List the event names that should be excluded from the events table.
Customization: Add event names you don’t want to process.
Example:

EVENTS_TO_EXCLUDE: ["user_engagement", "scroll"]

Hostname Exclude/Include

HOSTNAME_EXCLUDE: []
HOSTNAME_INCLUDE_ONLY: []

Description: Exclude or include specific hostnames from the data.
Customization: Add hostnames to either list based on whether you want to include or exclude them from the data. Example:

HOSTNAME_EXCLUDE: []
HOSTNAME_INCLUDE_ONLY: [ "www.ga4dataform.com", "ga4dataform.com" ]

Last Non-Direct Lookback Days

LAST_NON_DIRECT_LOOKBACK_DAYS: 90

Description: Defines the number of days to look back when assigning a source for a user who lands on your site without any known sources.
Customization: Change the number of days to your liking.

Details

Extra Channel Grouping

We’ve implemented GA4’s Default Channel Grouping logic as a JavaScript function. While our implementation closely mirrors GA4's behavior, it may not provide exact matches in all cases. This is primarily because the BigQuery export does not include certain parameters that GA4 uses in its grouping logic, such as Source platform and Google Ads campaign type. As a result, discrepancies might appear between GA4 UI groupings and our classification.

EXTRA_CHANNEL_GROUPS: true

Description: If you enable this, session_source.first/last.default_channel_grouping in int_ga4_sessions and session_source.default_channel_grouping in ga4_sessions will use an Organic AI grouping based on a set list of matching AI-related referrer domains listed in includes/core/extra/source_categories.json.

User stitching 💎

USER_STITCHING: {
  enabled: false,
  dimensions: [],
  lookBackDays: 90,
  lookAheadDays: 10
}

Description: The user stitching functionality looks at the cookie of the user (user_pseudo_id) and "fills in gaps" of certain column(s) - most notably the user_id. It does this on the session level.

How it works:

Lookback: we look back in time to find if that visitor in the past has had a session with a user_id, and assign that user_id to the current session. The last seen user_id is used to fill in the blanks.
Lookahead: if there is no session in the past with a user_id, we look in the future to find one. This effectively rewrites the history and de-anonimises sessions leading up to a login (caution is advised not to breach privacy regulations, policies).
Results are stored in the stitched_ids struct column in the ga4_sessions table.
The stitching is not restricted to user_id only: if you have (custom) parameters, user_properties, url_params, you can stitch them via the same procedure using the dimensions array.
We use user_pseudo_id as the partition for the lookback and lookahead windows

Configuration Options:

Field	Description
enabled	Enable/disable user stitching functionality
dimensions	Array of objects that contain additional fields to stitch beyond user_id
lookBackDays	Days to search backwards for user identification (default: 90)
lookAheadDays	Days to search forward for retroactive identification (default: 10)

Dimensions Format:

name: the column name as it appears in ga4_events
renameTo: the column name as it will appear in the stitched_ids struct in ga4_sessions

Field naming

If no renameTo field is used, the full (sanitized) name is used. So event_params_custom.lead_id will become event_params_custom_lead_id.

Example:

  USER_STITCHING: {
    enabled: true,
    dimensions: [
	    { name: "user_properties.datatrics_segment", renameTo: "datatrics_segment" },
      { name: "event_params_custom.showroom_name" }
    ],
    lookBackDays: 90,
    lookAheadDays: 3
  }

Respect user privacy

Be mindul of user choices and privacy when stitching data. If you use stitched data to enrich customer profiles with information gathered while they were logged out, it may not be what they expect. Or even what you promised in your own privacy policy.

Custom Event ID Parameter 💎

CUSTOM_EVENT_ID_PARAMETER: ''

Description: Use CUSTOM_EVENT_ID_PARAMETER to add another custom event parameter that makes an event unique. This field will be concatenated with the default event_id fields and will ensure event uniqueness. We usually recommend using a UNIX timestamp or a custom event_id.

Example:

CUSTOM_EVENT_ID_PARAMETER: 'event_params_custom.hit_timestamp'

Which will return this SQL in ga4_events:

farm_fingerprint(
    event_name || '-' ||
    time.event_timestamp || '-' ||
    coalesce(user_pseudo_id, 'no') || '-' ||
    coalesce(event_params.ga_session_id, 0) || '-' ||
    coalesce(batch.batch_page_id, 0) || '-' ||
    coalesce(batch.batch_ordering_id,0) || '-' ||
    coalesce(batch.batch_event_index,0) || '-' ||
    coalesce(ecommerce.ecommerce_transaction_id, "no") || '-' ||
    coalesce(event_params.engagement_time_msec, 0)
    || safe_cast(coalesce(event_params_custom.hit_timestamp,'no') as string)
  ) as event_id

warning

Make sure to add the custom field you are using as CUSTOM_EVENT_ID_PARAMETER to the CUSTOM_EVENT_PARAMS_ARRAY as well!

Deduplicating Transactions

TRANSACTIONS_DEDUPE: true

Description: By default, we leave duplicate transaction_ids alone in ga4_transactions, but you can enable deduplication with this setting.

note

Setting this to true will still keep all transactions with NULL transaction_id

Customization: enable/disable

Transaction Totals User Identifier

TRANSACTION_TOTALS_UID: 'user_pseudo_id'

Description: Specifies the user identifier field for calculating running transaction counts in ga4_transactions. Customization: Default identifier is user_pseudo_id. Change to your preferred user identifier (e.g., user_id for authenticated users). Ensure the specified column exists in your data.

Data Quality Assertions

These assertions check the data for consistency and quality. You can enable or disable specific checks by setting them to true or false.

Event ID Uniqueness

ASSERTIONS_EVENT_ID_UNIQUENESS: true

Ensures that each event has a unique event ID.

Session ID Uniqueness

ASSERTIONS_SESSION_ID_UNIQUENESS: true

Ensures that each session has a unique session ID.

Session Duration Validity

ASSERTIONS_SESSION_DURATION_VALIDITY: true

Ensures that session durations are valid and within reasonable limits.

Session Validity

ASSERTIONS_SESSIONS_VALIDITY: true

Validates that session data is correct.

Tables Timeliness

ASSERTIONS_TABLES_TIMELINESS: true

Checks if the GA4 tables are up to date.

Transaction ID Completeness

ASSERTIONS_TRANSACTION_ID_COMPLETENESS: false

Checks if transaction IDs are present for purchase events.

User Pseudo ID Completeness

ASSERTIONS_USER_PSEUDO_ID_COMPLETENESS: false

Ensures that the "user_pseudo_id" is present for all hits.

Advanced Consent Mode

If you use Advanced Consent Mode, this assertion will always fail.

Events to Count (eventsToCount)​

Unique Fields (uniqueFields)​

Sum Fields (sumFields)​

Events to Count (`eventsToCount`)

Unique Fields (`uniqueFields`)

Sum Fields (`sumFields`)