API Reference

dataform-ga4-sessions

dataform-ga4-sessions module

Example

const ga4 = require('dataform-ga4-sessions')

• dataform-ga4-sessions
  • ~DataformAction
    • new DataformAction(sourceConfig, targetConfig)
    • ._source
    • ._target
    • ._timezone
    • ._tags
    • ._assertions
    • ._partitionBy
    • ._uniqueKey
    • ._clusterBy
    • ._updatePartitionFilter
    • ._additionalOptions
    • ._partitionExpirationDays
    • ._requirePartitionFilter
    • ._columns
    • ._eventParams
    • ._userProperties
    • ._queryParameters
    • ._itemColumns
    • ._itemParams
    • .addColumns(columns)
    • .addEventParams(eventParams)
    • .addUserProperties(userProperties)
    • .addQueryParameters(queryParameters)
    • .addItemColumns()
    • .addItemParams()
    • .getSqlUniqueId()
    • .publish()
    • .publishAssertions()
  • ~Event ⇐ DataformAction
    • new Event(sourceConfig, targetConfig)
    • ._uniqueKey
    • ._timestampEventParamName
    • .addItemColumns()
    • .addItemParams()
    • .skipUniqueEventsStep()
    • .getSqlUniqueId()
    • .setEventName(eventName)
    • .publish()
  • ~EventFactory
    • new EventFactory(sourceConfig)
    • ._timestampEventParamName
    • ._targetSchema
    • .createEvent(eventConfig) ⇒ Event
    • .createEvents(eventConfig) ⇒ Array.<Event>
    • .createEcommerceEvents() ⇒ Array.<Event>
    • .createFormEvents() ⇒ Array.<Event>
    • .createAllRecommendedEvents() ⇒ Array.<Event>
  • ~Session ⇐ DataformAction
    • new Session(sourceConfig, targetConfig)
    • ._uniqueKey
    • ._sourceMediumRules
    • ._postProcessing
    • ._processingSteps
    • ._lastNonDirectLookBackWindow
    • ._assertions
    • .applyPreset(presetName)
    • .getSqlUniqueId()
    • .skipLastNonDirectStep()
    • .skipChannelStep()
    • .skipSourceMediumStep()
    • .publish()
    • .publishAssertions()

dataform-ga4-sessions~DataformAction

Creates Dataform Action to build GA4 Event tables based on BigQuery exported data.

Kind: inner class of dataform-ga4-sessions
Access: package

• ~DataformAction
  • new DataformAction(sourceConfig, targetConfig)
  • ._source
  • ._target
  • ._timezone
  • ._tags
  • ._assertions
  • ._partitionBy
  • ._uniqueKey
  • ._clusterBy
  • ._updatePartitionFilter
  • ._additionalOptions
  • ._partitionExpirationDays
  • ._requirePartitionFilter
  • ._columns
  • ._eventParams
  • ._userProperties
  • ._queryParameters
  • ._itemColumns
  • ._itemParams
  • .addColumns(columns)
  • .addEventParams(eventParams)
  • .addUserProperties(userProperties)
  • .addQueryParameters(queryParameters)
  • .addItemColumns()
  • .addItemParams()
  • .getSqlUniqueId()
  • .publish()
  • .publishAssertions()

new DataformAction(sourceConfig, targetConfig)

Param	Type	Description
sourceConfig	Object	GA4 BigQuery Source configuration
sourceConfig.database	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.dataset	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.incrementalTableName	string	Source incremental table name. For example events_20240101
sourceConfig.nonIncrementalTableName	string	Source non-incremental table name. For example events_*
sourceConfig.incrementalTableEventStepWhere	string	This property set where condition for the incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
sourceConfig.nonIncrementalTableEventStepWhere	string	This property set where condition for the non-incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
targetConfig	Object	Optional. Target configuration
targetConfig.schema	string	Optional. Target schema name
targetConfig.tableName	string	Optional. Target table name

dataformAction._source

Kind: instance property of DataformAction
Properties

Name	Type	Description
source	Object	GA4 BigQuery Source configuration
source.database	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
source.dataset	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
source.incrementalTableName	string	Source incremental table name. For example events_20240101
source.nonIncrementalTableName	string	Source non-incremental table name. For example events_*
source.incrementalTableEventStepWhere	string	This property set where condition for the incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
source.nonIncrementalTableEventStepWhere	string	This property set where condition for the non-incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false

dataformAction._target

Use getter / setter methods to set values for the following properties.

Kind: instance property of DataformAction
Properties

Name	Type	Description
target	Object	Destination table config.
target.schema	string	The target schema. Destination dataset name. Default is dataform_staging
target.tableName	string	The target table name. Destination table name.

Example

session.target = {schema: "dataform_testing", tableName: "test_sessions"}}

dataformAction._timezone

Kind: instance property of DataformAction
Properties

Name	Type	Description
timezone	string	The timezone. Default is Europe/London

Example

session.timezone = "Europe/Berlin"

dataformAction._tags

Kind: instance property of DataformAction
Properties

Name	Type	Description
tags	Array.<string>	Dataform execution tags needed to run a chose a set of actions to run. By default [source.dataset] tag is added.

Example

session.tags = ["daily","hourly"]

dataformAction._assertions

Kind: instance property of DataformAction
Properties

Name	Type	Description
assertions	Array.<{name: String, config: {description: String}, query: function(String): String}>	List of default Dataform assertions for the class, but in most cases if you need extra assertions you could define them outside the class in separate files.

dataformAction._partitionBy

Kind: instance property of DataformAction
Properties

Name	Type	Description
partitionBy	string	The [partition by])(https://cloud.google.com/dataform/docs/partitions-clusters#create_a_table_partition). Dataform use this keys to generate partitioned tables. By default partitionBy is set to date. If you want to use another partitionBy value you need to set it manually.

Example

session._partitionBy = "DATE(timestamp)"

dataformAction._uniqueKey

Kind: instance property of DataformAction
Properties

Name	Type	Description
uniqueKey	string	The unique key for incremental tables. Dataform use this keys to generate merge queries.

Example

session.uniqueKey = ["session_id","date"]

dataformAction._clusterBy

Kind: instance property of DataformAction
Properties

Name	Type	Description
clusterBy	Array.<string>	The cluster by. Dataform use this keys to generate clustered tables. By default clusterBy is not set. If you want to use clusterBy you need to set it manually.

Example

session.clusterBy = ["name", "revenue"]

dataformAction._updatePartitionFilter

Kind: instance property of DataformAction
Properties

Name	Type	Description
updatePartitionFilter	string	The update partition filter. Dataform use this keys to to avoid scanning the whole table to find matching rows, set updatePartitionFilter to only consider a subset of records. By default updatePartitionFilter is not set. If you want to use updatePartitionFilter you need to set it manually.

Example

session.updatePartitionFilter = "timestamp >= timestamp_sub(current_timestamp(), interval 24 hour)"

dataformAction._additionalOptions

Kind: instance property of DataformAction
Properties

Name	Type	Description
additionalOptions	Object	IBigQueryOptions additionalOptions. Key-value pairs for the table, view, and materialized view options.

Example

session.additionalOptions = {numeric_option: "5", string_option: '"string-value"'}

dataformAction._partitionExpirationDays

Kind: instance property of DataformAction
Properties

Name	Type	Description
partitionExpirationDays	number	IBigQueryOptions partitionExpirationDays. The number of days for which BigQuery stores data in each partition. The setting applies to all partitions in a table, but is calculated independently for each partition based on the partition time.

Example

session.partitionExpirationDays = 90

dataformAction._requirePartitionFilter

Kind: instance property of DataformAction
Properties

Name	Type	Description
requirePartitionFilter	boolean	IBigQueryOptions partitionExpirationDays. Declares whether the partitioned table requires a WHERE clause predicate filter that filters the partitioning column.

Example

session.requirePartitionFilter = true

dataformAction._columns

Kind: instance property of DataformAction
Properties

Name	Type	Description
columns	Array.<Object>	List of columns from GA4 raw table to be added to the final table. You could check the list of all available columns here. By default columns are added based on the preset. Or you could add them manually using addColumns method.
columns[].name	String	Name of the column in GA4 raw table.
[columns[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as in GA4 raw table.

dataformAction._eventParams

Kind: instance property of DataformAction
Properties

Name	Type	Description
eventParams	Array.<Object>	List of event params unnested from GA4 raw table event_params column. By default eventParams are added based on the preset. You could add your custom event_params using addEventParams method.
eventParams[].name	String	The value of key in the event_params record.
[eventParams[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as eventParams[].name.
[eventParams[].type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.

dataformAction._userProperties

Kind: instance property of DataformAction
Properties

Name	Type	Description
userProperties	Array.<Object>	List of user properties unnested from GA4 raw table user_properties column. By default userProperties are not added. You could add your custom user_properties using addUserProperties method.
userProperties[].name	String	The value of key in the user_properties record.
[userProperties[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as userProperties[].name.
[userProperties[].type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.

dataformAction._queryParameters

Kind: instance property of DataformAction
Properties

Name	Type	Description
queryParameters	Array.<Object>	List of query parameters from the unnested event_params column with the key page_location. You could add your custom query_parameters using addQueryParameters method.
queryParameters[].name	String	The query parameter name.
[queryParameters[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as queryParameters[].name.

dataformAction._itemColumns

Kind: instance property of DataformAction
Properties

Name	Type	Description
itemColumns	Array.<Object>	List of child columns to keep in the final table from items column. By default itemColumns are not added, and if items added as a column all child columns wil be added. You could add itemColumns manually using addItemColumns method.
itemColumns[].name	String	Name of child column the column in GA4 raw table.
[itemColumns[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as itemColumns[].name.

dataformAction._itemParams

Kind: instance property of DataformAction
Properties

Name	Type	Description
itemParams	Array.<Object>	List of event params of item scope unnested from GA4 raw table items.item_params column. By default itemParams are not added. You could add your custom item_params using addItemParams method.
itemParams[].name	String	The value of key in the items.item_params record.
[itemParams[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as itemParams[].name.
[userProperties[].type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.

dataformAction.addColumns(columns)

warning

If you add columns with RECORD type, like: device.*, geo.* you should specify the columnName. Because the result column name couldn't have a dot (.) symbol in the name.

Kind: instance method of DataformAction

Param	Type	Description
columns	Array.<Object>	List of columns from GA4 raw table to be added to the final table.
columns[].name	String	Name of the column in GA4 raw table.
[columns[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as in GA4 raw table.

Example

session.addColumns([{ name: "geo.city", columnName: "city" },{ name: "geo.metro", columnName: "metro" },{ name: "stream_id" },{ name: "platform" },])

dataformAction.addEventParams(eventParams)

Kind: instance method of DataformAction

Param	Type	Description
eventParams	Array.<Object>	List of event params unnested from GA4 raw table event_params column.
eventParams[].name	String	The value of key in the event_params record.
[eventParams[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as eventParams[].name.
[eventParams[].type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.

Example

session.addEventParams([{ name: "page_title", type: "string" }])

dataformAction.addUserProperties(userProperties)

Kind: instance method of DataformAction

Param	Type	Description
userProperties	Array.<Object>	List of user properties unnested from GA4 raw table user_properties column.
userProperties[].name	String	The value of key in the user_properties record.
[userProperties[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as userProperties[].name.
[userProperties[].type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.

Example

session.addUserProperties([{ name: "user_status", type: "string" }])

dataformAction.addQueryParameters(queryParameters)

Kind: instance method of DataformAction

Param	Type	Description
queryParameters	Array.<Object>	List of query parameters from the unnested event_params column with the key page_location.
queryParameters[].name	String	The query parameter name.
[queryParameters[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as queryParameters[].name.

Example

session.addQueryParameters([{ name: "fbclid" },{ name: "ttclid" },{ name: "gclid", columnName: "gclid_url" },])

dataformAction.addItemColumns()

note

Supported only in Event class

In the example below from items columns only item_id, item_name, price, quantity will be added to the final table in the items.item_id, items.item_name, items.price, items.quantity accordingly.

Kind: instance method of DataformAction
Properties

Name	Type	Description
itemColumns	Array.<Object>	List of child columns to keep in the final table from items column. By default itemColumns are not added, and if items added as a column all child columns wil be added. You could add itemColumns manually using addItemColumns method.
itemColumns[].name	String	Name of child column the column in GA4 raw table.
[itemColumns[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as itemColumns[].name.

Example

purchase.addItemColumns([{ name: "item_id" },{ name: "item_name" },{ name: "price" },{ name: "quantity" },])

dataformAction.addItemParams()

note

Supported only in Event class

In the example below the items.item_params column will be expanded and filtered for the key color. The resulting string values will be stored in items.item_color.

Kind: instance method of DataformAction

Param	Type	Description
[userProperties[].type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The type of the value in the items.item_params column. By default string.

Properties

Name	Type	Description
itemParams	Array.<Object>	List of names of item-scoped custom dimensions to extract from items.item_params by key. By default itemParams are not added. You could add itemParams manually using addItemParams method.
itemParams[].name	String	Name of item-scoped custom dimensions.
[itemParams[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as itemParams[].name.

Example

purchase.addItemParams([{ name: "color" , columnName: "item_color"},])

dataformAction.getSqlUniqueId()

Helper method to generate SQL code to get unique id for each row in a final table, used inside publish method. Should be overwritten in the child class.

Kind: instance method of DataformAction

dataformAction.publish()

Main method to publish Dataform Action. This method generates SQL and then uses Dataform core publish method to generate incremental and non-incremental session table. This method should be overwritten in the child class.

Kind: instance method of DataformAction

dataformAction.publishAssertions()

The method to publish default Dataform assertions. This method should be overwritten in the child class.

Kind: instance method of DataformAction

dataform-ga4-sessions~Event ⇐ DataformAction

Creates Dataform Action to build GA4 event tables based on BigQuery exported data, for example table for purchase events. But instead of using this class directly, it is recommended to use EventFactory to create events. The factory could simplify the creation of auto or recommended events. But after the creation of the event, you could use any of DataformAction methods and properties.

Kind: inner class of dataform-ga4-sessions
Extends: DataformAction

• ~Event ⇐ DataformAction
  • new Event(sourceConfig, targetConfig)
  • ._uniqueKey
  • ._timestampEventParamName
  • .addItemColumns()
  • .addItemParams()
  • .skipUniqueEventsStep()
  • .getSqlUniqueId()
  • .setEventName(eventName)
  • .publish()

new Event(sourceConfig, targetConfig)

Constructor for the Event class inherited from DataformAction class. Before creating the object of this class you need to declare GA4 source tables using declareSources method.

Param	Type	Description
sourceConfig	Object	GA4 BigQuery Source configuration
sourceConfig.database	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.dataset	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.incrementalTableName	string	Source incremental table name. For example events_20240101
sourceConfig.nonIncrementalTableName	string	Source non-incremental table name. For example events_*
sourceConfig.incrementalTableEventStepWhere	string	This property set where condition for the incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
sourceConfig.nonIncrementalTableEventStepWhere	string	This property set where condition for the non-incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
targetConfig	Object	Optional. Target configuration
targetConfig.schema	string	Optional. Target schema name. Default is dataform_staging
targetConfig.tableName	string	Optional. Target table name.

Example

// Define your configconst eventConfig = {dataset: "analytics_XXXXXX",incrementalTableName: "events_XXXXXX",};
// Declare GA4 source tablesga4.declareSources(eventConfig);
// Create eventlet purchase = new ga4.Event(eventConfig);
// Set destination table name and add where conditions for the eventpurchase.setEventName("purchase");

event._uniqueKey

Kind: instance property of Event
Properties

Name	Type	Description
uniqueKey	string	The unique key for incremental tables. Dataform use this keys to generate merge queries. Default value for Event is ["date", "event_id"]

Example

event.uniqueKey = ["event_id","date"]

event._timestampEventParamName

Kind: instance property of Event
Properties

Name	Type	Description
timestampEventParamName	string	This property will be used to generate unique event_id. The value will be from unnested event_params column with the key equals the value of this property. But at first you should add this event parameter in your GTM setup. js event.timestampEventParamName = "gtm_event_timestamp"

event.addItemColumns()

warning

If you provide doesn't existing column name in the itemColumns list, you will get a SQL error and can't build the table.

In the example below from items columns only item_id, item_name, price, quantity will be added to the final table in the items.item_id, items.item_name, items.price, items.quantity accordingly.

Kind: instance method of Event
Properties

Name	Type	Description
itemColumns	Array.<Object>	List of child columns to keep in the final table from items column. By default itemColumns are not added, and if items added as a column all child columns wil be added. You could add itemColumns manually using addItemColumns method.
itemColumns[].name	String	Name of child column the column in GA4 raw table.
[itemColumns[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as itemColumns[].name.

Example

purchase.addItemColumns([{ name: "item_id" },{ name: "item_name" },{ name: "price" },{ name: "quantity" },])

event.addItemParams()

warning

item_params were added to the BigQuery export late October 2023. And you can't use addItemParams for events before that date.

In the example below the items.item_params column will be expanded and filtered for the key color. The resulting string values will be stored in items.item_color.

Kind: instance method of Event

Param	Type	Description
[userProperties[].type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The type of the value in the items.item_params column. By default string.

Properties

Name	Type	Description
itemParams	Array.<Object>	List of names of item-scoped custom dimensions to extract from items.item_params by key. By default itemParams are not added. You could add itemParams manually using addItemParams method.
itemParams[].name	String	Name of item-scoped custom dimensions.
[itemParams[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as itemParams[].name.

Example

purchase.addItemParams([{ name: "color" , columnName: "item_color"},])

event.skipUniqueEventsStep()

Helper method to skip unique events step. By default where condition is added to filter all events with event_id equals to null. Also QUALIFY statement is added to get only one event per event_id. But if you want to skip this step you could use this method.

Kind: instance method of Event
Example

event.skipUniqueEventsStep();

event.getSqlUniqueId()

Helper method to generate SQL code to get unique id for each row in a final table, used inside publish method. By default it use getSqlEventId from dataform-ga4-helpers package

Kind: instance method of Event

event.setEventName(eventName)

This helper method will use event name to define target table and add where conditions for the final query. It's recommended to use EventFactory to create events. But if you want to create event manually you could use this method.

Kind: instance method of Event

Param	Type	Description
eventName	string	The event name. For example purchase

Example

event.setEventName("purchase")

event.publish()

Main method to publish Dataform Action. This method generates SQL and then uses Dataform core publish method to generate incremental and non-incremental session table. This method should be overwritten in the child class.

Kind: instance method of Event
Example

purchase.publish()

dataform-ga4-sessions~EventFactory

Helper class to create GA4 events. It's recommended to use this class to create events. But if you want to create event manually you could use Event class.

Kind: inner class of dataform-ga4-sessions

• ~EventFactory
  • new EventFactory(sourceConfig)
  • ._timestampEventParamName
  • ._targetSchema
  • .createEvent(eventConfig) ⇒ Event
  • .createEvents(eventConfig) ⇒ Array.<Event>
  • .createEcommerceEvents() ⇒ Array.<Event>
  • .createFormEvents() ⇒ Array.<Event>
  • .createAllRecommendedEvents() ⇒ Array.<Event>

new EventFactory(sourceConfig)

Create any recommended or auto event using EventFactory method like createEventName.

Param	Type	Description
sourceConfig	Object	GA4 BigQuery Source configuration
sourceConfig.database	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.dataset	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.incrementalTableName	string	Source incremental table name. For example events_20240101
sourceConfig.nonIncrementalTableName	string	Source non-incremental table name. For example events_*
sourceConfig.incrementalTableEventStepWhere	string	This property set where condition for the incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
sourceConfig.nonIncrementalTableEventStepWhere	string	This property set where condition for the non-incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false

Example

// Define your configconst eventConfig = {dataset: "analytics_XXXXXX",incrementalTableName: "events_XXXXXX",};
// Define EventFactoryconst ef = new ga4.EventFactory(eventConfig);
// Create purchase event:const purchase = ef.createPurchase();
//Publish eventpurchase.publish()

eventFactory._timestampEventParamName

Kind: instance property of EventFactory
Properties

Name	Type	Description
timestampEventParamName	string	This property will be used to generate unique event_id. The value will be from unnested event_params column with the key equals the value of this property. But at first you should add this event parameter in your GTM setup.

Example

// Define EventFactoryconst ef = new ga4.EventFactory(eventConfig);// Set timestampEventParamNameef.timestampEventParamName = "gtm_event_timestamp"

eventFactory._targetSchema

Kind: instance property of EventFactory
Properties

Name	Type	Description
targetSchema	string	This property will be used to set target schema for all events generated by factory.

Example

// Define EventFactoryconst ef = new ga4.EventFactory(eventConfig);// Set target schema for all events created by factoryef.targetSchema = 'my_schema'let events = ef.createEcommerceEvents();events.forEach((event) => {// But you could overwrite target schema for particular event    if (event.target.tableName === "purchase") {        event.target.schema = " my_schema_2";    }    event.publish()});

eventFactory.createEvent(eventConfig) ⇒ Event

Kind: instance method of EventFactory
Returns: Event - Event object

Param	Type	Description
eventConfig	Object	Event configuration
eventConfig.eventName	String	Event name. For example purchase
[eventConfig.columns]	Object	List of columns from GA4 raw table to be added to the final table. You could check the list of all available columns here. By default columns are added based on the preset. Or you could add them manually using addColumns method.
[eventConfig.columns.name]	String	Name of the column in GA4 raw table.
[eventConfig.columns.columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as in GA4 raw table.
[eventConfig.eventParams]	Object	List of event params unnested from GA4 raw table event_params column. By default eventParams are added based on the preset. You could add your custom event_params using addEventParams method.
[eventConfig.eventParams.name]	String	The value of key in the event_params record.
[eventParams.columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as eventParams.name.
[eventConfig.eventParams.type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.
[eventConfig.userProperties]	Object	List of user properties unnested from GA4 raw table user_properties column. By default userProperties are not added. You could add your custom user_properties using addUserProperties method.
[eventConfig.userProperties.name]	String	The value of key in the user_properties record.
[eventConfig.userProperties.columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as userProperties.name.
[eventConfig.userProperties.type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.
[eventConfig.queryParameters]	Object	List of query parameters from the unnested event_params column with the key page_location. You could add your custom query_parameters using addQueryParameters method.
[eventConfig.queryParameters.name]	String	The query parameter name.
[eventConfig.queryParameters.columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as queryParameters[].name.

Example

const purchase = ef.createEvent({ eventName: "session_start", columns:[{name:"privacy_info.analytics_storage", columnName:"analytics_storage"}], eventParams:[ { name: "page_referrer", type: "string" }]})

eventFactory.createEvents(eventConfig) ⇒ Array.<Event>

Tne method to create multiple events using list of events configurations. This method is useful if you want to reuse the same event configurations between projects. In this case you could define event configurations in separate file and import the configs and create events using this helper method.

Kind: instance method of EventFactory
Returns: Array.<Event> - List of events

Param	Type	Description
eventConfig	Array.<Object>	List of event configurations
eventConfig[].eventName	String	Event name. For example purchase
[eventConfig[].columns]	Object	List of columns from GA4 raw table to be added to the final table. You could check the list of all available columns here. By default columns are added based on the preset. Or you could add them manually using addColumns method.
[eventConfig[].columns.name]	String	Name of the column in GA4 raw table.
[eventConfig[].columns.columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as in GA4 raw table.
[eventConfig[].eventParams]	Object	List of event params unnested from GA4 raw table event_params column. By default eventParams are added based on the preset. You could add your custom event_params using addEventParams method.
[eventConfig[].eventParams.name]	String	The value of key in the event_params record.
[eventParams[].columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as eventParams.name.
[eventConfig[].eventParams.type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.
[eventConfig[].userProperties]	Object	List of user properties unnested from GA4 raw table user_properties column. By default userProperties are not added. You could add your custom user_properties using addUserProperties method.
[eventConfig[].userProperties.name]	String	The value of key in the user_properties record.
[eventConfig[].userProperties.columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as userProperties.name.
[eventConfig[].userProperties.type]	'string' | 'int' | 'double' | 'float' | 'coalesce' | 'coalesce_float'	Optional. The name of the value in the event_params column. By default string.
[eventConfig[].queryParameters]	Object	List of query parameters from the unnested event_params column with the key page_location. You could add your custom query_parameters using addQueryParameters method.
[eventConfig[].queryParameters.name]	String	The query parameter name.
[eventConfig[].queryParameters.columnName]	String	Optional. The name of the column in the result table. If not provided the name will be the same as queryParameters[].name.

Example

// Create eventslet events = ef.createEvents(configs);// Publish eventsevents.forEach(event => event.publish());

eventFactory.createEcommerceEvents() ⇒ Array.<Event>

The method to create all recommended ecommerce events.

Kind: instance method of EventFactory
Returns: Array.<Event> - List of events
Example

// Define your configconst eventConfig = {dataset: "analytics_XXXXXX",incrementalTableName: "events_XXXXXX",};// Create all recommended eventslet events = ef.createEcommerceEvents();// Publish events events.forEach(event => event.publish());

eventFactory.createFormEvents() ⇒ Array.<Event>

The method to create all recommended events for form tracking.

Kind: instance method of EventFactory
Returns: Array.<Event> - List of events
Example

// Define your configconst eventConfig = {dataset: "analytics_XXXXXX",incrementalTableName: "events_XXXXXX",};// Create all recommended eventslet events = ef.createFormEvents();// Publish events events.forEach(event => event.publish());

eventFactory.createAllRecommendedEvents() ⇒ Array.<Event>

The method to create all recommended and auto events.

Kind: instance method of EventFactory
Returns: Array.<Event> - List of events
Example

// Define your configconst eventConfig = {dataset: "analytics_XXXXXX",incrementalTableName: "events_XXXXXX",};// Create all recommended eventslet events = ef.createAllRecommendedEvents();// Publish events events.forEach(event => event.publish());

dataform-ga4-sessions~Session ⇐ DataformAction

Creates Dataform Action to build GA4 Session tables based on BigQuery exported data. The class extends DataformAction class.

Kind: inner class of dataform-ga4-sessions
Extends: DataformAction

• ~Session ⇐ DataformAction
  • new Session(sourceConfig, targetConfig)
  • ._uniqueKey
  • ._sourceMediumRules
  • ._postProcessing
  • ._processingSteps
  • ._lastNonDirectLookBackWindow
  • ._assertions
  • .applyPreset(presetName)
  • .getSqlUniqueId()
  • .skipLastNonDirectStep()
  • .skipChannelStep()
  • .skipSourceMediumStep()
  • .publish()
  • .publishAssertions()

new Session(sourceConfig, targetConfig)

Constructor for the Session class inherited from DataformAction class. And set default values for additional properties needed for the Session Action and also apply standard presets. Before creating the object of this class you need to declare GA4 source tables using declareSources method.

Param	Type	Description
sourceConfig	Object	GA4 BigQuery Source configuration
sourceConfig.database	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.dataset	string	The GA4 export database name. For example <YOUR-GCP-PROJECT-ID>
sourceConfig.incrementalTableName	string	Source incremental table name. For example events_20240101
sourceConfig.nonIncrementalTableName	string	Source non-incremental table name. For example events_*
sourceConfig.incrementalTableEventStepWhere	string	This property set where condition for the incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
sourceConfig.nonIncrementalTableEventStepWhere	string	This property set where condition for the non-incremental queries. The important note this condition is added to the first step, not the final step. So if you filter for example events with source / medium values you could miss this data in the final result. Default is false
targetConfig	Object	Optional. Target configuration
targetConfig.schema	string	Optional. Target schema name. Default is dataform_staging
targetConfig.tableName	string	Optional. Target table name. Default is sessions

Example

// Define your configconst sessionConfig = {dataset: "analytics_XXXXXX",incrementalTableName: "events_XXXXXX",};
// Declare GA4 source tablesga4.declareSources(sessionConfig);
// Create sessions objectconst sessions = new ga4.Session(sessionConfig);

session._uniqueKey

Kind: instance property of Session
Properties

Name	Type	Description
uniqueKey	string	The unique key for incremental tables. Dataform use this keys to generate merge queries. Default value for Session is ["date", "session_id"]

Example

session.uniqueKey = ["session_id","date"]

session._sourceMediumRules

The order of sourceMediumRules is important, the first rule that meets the condition will be applied.

Kind: instance property of Session
Properties

Name	Type	Description
sourceMediumRules	Array.<Object>	The source medium rules. Default is defaultSourceMediumRules from includes/constants.js. This property is used to create a source medium columns in the final table.
sourceMediumRules[].columns	Array.<String>	The rule will check columns from the list in the final table.
sourceMediumRules[].conditionType	'NOT_NULL'	The rule condition type define the logic how to check columns. At the moment only NOT_NULL is supported.
sourceMediumRules[].conditionValue	String	The rule expected value. Not used by NOT_NULL condition type.
sourceMediumRules[].value	Object	The value of source medium that should be set in the final table if condition is met.
sourceMediumRules[].value.source	String	The source value that should be set. If the value should be literal it should be in the single quotes. For example "'google'"" otherwise it should be a column name from the final table for example "source".
sourceMediumRules[].value.medium	String	The medium value that should be set.
sourceMediumRules[].value.campaign	String	The campaign value that should be set.

Example

sessions.sourceMediumRules = [ {  columns: ["gclid_url"], conditionType: "NOT_NULL", conditionValue: "", value: {  source: "'google'",  medium: "'cpc'",  campaign: "campaign", },},...sessions.sourceMediumRules,];

session._postProcessing

Kind: instance property of Session
Properties

Name	Type	Description
processingSteps	Object	The post processing config. At the moment only delete is supported.
processingSteps.delete	Array.<String>	Columns listed in this property will be deleted from the final table. By default [source, medium, campaign] columns will be delete. Because during sessions_with_source_medium_and_lp step and sessions_with_last_non_direct these columns also will be added to last_click_attribution and last_non_direct_attribution accordingly.

Example

sessions.processingSteps = {delete: ["column2", "column2"],};

session._processingSteps

Default session processing steps

Step Name	Description
events	Extract the needed columns from all events. Generate session_id
sessions_base	Group events into sessions by session id. Add standard columns like: session_start, session_end, session_engaged, landing_page etc.
sessions_with_source_medium_and_lp	Apply source / medium rules to create last click attribution
sessions_with_channel	Add channel grouping based on source / medium
sessions_with_last_non_direct	Add last non direct attribution based on lookback window

Kind: instance property of Session
Properties

Name	Type	Description
processingSteps	Array.<Object>	The Session Action create a final table in a few steps. Queries for all default steps are defined in includes/processing_steps.js. You could skip any of step using methods below or add custom processing steps.
processingSteps[].queryName	String	The name of the step. The name should be unique.
processingSteps[].query	String	The Function that generates SQL for the step. The function has two parameters this and ctx which is Dataform context.

session._lastNonDirectLookBackWindow

Kind: instance property of Session
Properties

Name	Type	Description
lastNonDirectLookBackWindow	string	The last non direct look back window, if session has direct source / medium, a sessions_with_last_non_direct processing step tries to find previous non direct sessions inside the look back window. Default is 30 days. This property is used to create a last_non_direct_attribution columns in the final table.

Example

sessions.lastNonDirectLookBackWindow = 60

session._assertions

Default session assertions

Name	Description
Sessions Timeliness	Check that we have fresh sessions with a delay of no more than 2 days
Sessions Completeness	Check that we have sessions for all days without gaps
Sessions Validity	Check that sessions have all the required columns

Kind: instance property of Session
Properties

Name	Type	Description
assertions	Array.<{name: String, config: {description: String}, query: function(String): String}>	List of default Dataform assertions for the class, but in most cases if you need extra assertions you could define them outside the class in separate files.

session.applyPreset(presetName)

The function add list of columns, event_params and user_properties to the final table based on the preset.

Kind: instance method of Session

Param	Type	Description
presetName	"standard" | "extended" | "none"	The name of the preset. The following presets are available: standard, extended, none. Default is standard.

session.getSqlUniqueId()

Helper method to generate SQL code to get unique id for each row in a final table, used inside publish method. By default it use getSqlSessionId from dataform-ga4-helpers package

Kind: instance method of Session

session.skipLastNonDirectStep()

The method skips sessions_with_last_non_direct processing step.

Kind: instance method of Session
Example

sessions.skipLastNonDirectStep();

session.skipChannelStep()

The method skips sessions_with_channel processing step. It should be called only after skipLastNonDirectStep as it depends on it. Also if this method is called a table with channels definitions created by helpers.getSqlSourceCategoriesTable wouldn't be added.

Kind: instance method of Session
Example

sessions.skipLastNonDirectStep();sessions.skipChannelStep();

session.skipSourceMediumStep()

The method skip sessions_with_source_medium_and_lp processing step. This method should be used if you want to create your own source / medium attribution logic. The order is important as each step uses the preceding step. So you can't skip the channel step and have a last_non_direct step. But you could delete all the steps, and add your own processing steps.

Kind: instance method of Session
Example

// Ignore all processing steps except the firstsessions.skipLastNonDirectStep();sessions.skipChannelStep();sessions.skipSourceMediumStep();

session.publish()

Main method to publish Dataform Action. This method generates SQL and then uses Dataform core publish method to generate incremental and non-incremental session table.

Kind: instance method of Session
Example

session.publish()

session.publishAssertions()

The method to publish default Dataform assertions.

Kind: instance method of Session
Example

session.publishAssertions()