Install

Installation involves setting the configuration options and then executing the deploy_installer function in the region in which your GA4 dataset is located. Common patterns are described below.

Example Usage - Quick Installation (External Destination)

This is the most common installation pattern as it pushes transformed event data to Google Cloud Storage and creates an external table in BigQuery for subsequent usage. It also unlocks cross-cloud and external compute options by supporting direct connection to transformed data in GCS.

This pattern supports automatic schema and parameter evolution by default, so will only process each date partition precisely once, and will never require a full table rebuild.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `decode-ga4.eu.deploy_installer`(options)
    );

Example Usage - Quick Installation (Partitioned Destination)

This is a simpler pattern which creates a date-partitioned table containing transformed event data. It does not require a GCS bucket, so data can only be accessed by querying the BigQuery table directly.

Incorporating any schema or parameter changes into the table will require a full table rebuild each time the new changes are to be incorporated.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_partitioned"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `decode-ga4.eu.deploy_installer`(options)
    );

Example Usage - Installation to Custom Dataset (External Destination)

Setting the deployment_dataset_id in the options will deploy Decode GA4 resources and the output events table into the defined dataset instead of the decode_analytics_xxxxxxxx dataset.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname",
        "deployment_dataset_id": "project_id.custom_dataset_name"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `decode-ga4.eu.deploy_installer`(options)
    );

Setting the destination_dataset_id here will override the destination for the output events table.

Example Usage - Installation with Destination Dataset (External Destination)

This pattern is used when you want to create the output tables in a different dataset to the source GA4 data and the deployed Decode GA4 resources. This may be desirable if using the transformed events table as an input to subsequent transformations in e.g. Dataform or DBT.

This will deploy the transformed events table to the dataset defined by the destination_dataset_id, and the Decode GA4 resources to the decode_analytics_xxxxxxxx dataset.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname",
        "destination_dataset_id": "project_id.destination_dataset_name"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `decode-ga4.eu.deploy_installer`(options)
    );

To deploy Decode GA4 resources to a different, specifically-defined dataset, use the deployment_dataset_id option in combination with the output_dataset_id option.

Example Usage - App Stream Installation (External Destination)

This will install Decode GA4 for an App stream, which includes app-specific event names and parameters by default.

DECLARE options JSON;

SET options = JSON '''
    {
        "ga4_dataset_id": "project_id.ga4_dataset_name",
        "transform_config_template": "events_external",
        "gcs_bucket_name": "bucketname",
        "stream_type": "app"
    }
    ''';

EXECUTE IMMEDIATE (
    SELECT `decode-ga4.eu.deploy_installer`(options)
    );

Argument Reference

• ga4_dataset_id - (Required) The project_id.dataset_name of the dataset containing your GA4 BigQuery export.

• transform_config_template - (Required) The name of the transformation configuration template to use, events_external or events_partitioned.

• gcs_bucket_name - (Required for events_external config) The name of the Google Cloud Storage bucket in which to store compressed, transformed data.

• deployment_dataset_id - (Optional) The project_id.dataset_name of the dataset into which Decode GA4 will be deployed. Default is project_id.decode_analytics_xxxxxxxx, aligned to your ga4_dataset_id integer suffix.

• destination_dataset_id - (Optional) The project_id.dataset_name of the dataset into which the output eventstable will be built and maintained.

• stream_type - (Optional) The type of GA4 stream (app/web/all), which defines default values for event names and parameters. Default is web.

Event Names

• include_observed_events - (Optional) Boolean to determine whether to include observed events in the transform. Default is true.

• include_default_events - (Optional) Boolean to determine whether to include default events for the stream_type in the the transform. Default is true.

• conversion_event_names - (Optional) Array of event_name values to classify as conversions. Default is ['purchase'].

• exclude_event_names - (Optional) Array of event_name values to exclude from the transform.

• custom_event_names - (Optional) Array of additional event_name values to be included in the transform.

Event Parameters

• include_observed_event_params - (Optional) Boolean to determine whether to include observed event parameters in the transform. Default is true.

• include_default_event_params - (Optional) Boolean to determine whether to include default event parameters for the stream_type in the transform. Default is true.

• exclude_event_params - (Optional) Array of event_param names to exclude from the transform.

• custom_event_params - (Optional) JSON array of event_param name and type (string, int, float) to be included in the transform (e.g. JSON'[{"name": "new_parameter", "type": "string"}]').

User Properties

• include_observed_user_properties - (Optional) Boolean to determine whether to include observed user properties in the transform. Default is true.

• exclude_user_properties - (Optional) Array of user_property names to exclude from the transform.

• custom_user_properties - (Optional) JSON array of user_property name and type (string, int, float) values to be included in the transform (e.g. JSON'[{"name": "new_property", "type": "string"}]').

Item Parameters

• include_observed_item_params - (Optional) Boolean to determine whether to include observed item parameters in the transform. Default is true.

• exclude_item_params - (Optional) Array of item_param names to exclude from the transform.

• custom_item_params - (Optional) JSON array of item_param name and type (string, int, float) values to be included in the transform (e.g. JSON'[{"name": "new_parameter", "type": "string"}]').