Custom Reports

Overview

Our Google Analytics 4 via API integration extracts and loads a set of standard reports from the GA4 Data API into your database. If there is data you want to pull outside of those standard reports, you can now use this integration's new Custom Report feature.

The new Custom Report feature allows you to create a new data extraction that will load into the ga4_api schema in your database.

Please note that this will only load the raw data into your database. You will need to set up custom Looker visualizations and/or transform code to expose the data to end users.

Enterprise-only feature

This feature loads raw data into your database to make it available for customization purposes. Since you are not able to customize your data model on Growth, this feature is not available in Growth.

Where to find the Custom Reports feature

Open your GA4 API integration and click "Edit" in the upper right corner. If you scroll down, you will see the Custom Reports section, where you can create a new custom report:

Loading data

Once you have the custom report configured, it will load data whenever your GA4 API integration is refreshed. This will happen by default in your daily workflow. If you do not want to wait til the next day to see new data in your custom report table, you can start to load history after completing setup.

Editing custom reports is not possible

Due to the difficulties in modifying a table that already exists, we do not allow you to edit your custom report once it is created. If you create a custom report and realize you need to modify which fields are included, you will need to delete the custom report and start from scratch.

Enabling/disabling reports

If you leave a report enabled, it will continue to load new data whenever the GA4 via API integration refreshes.

If you disable it, it will preserve the table and the data you have already loaded, but it will not load any new data.

Custom report configuration

Here is a detailed walkthrough of each field in the Custom Report interface.

Name

This is the name for the custom report that will be displayed within the app.

Database table name

This is the name of the new table where this custom report's data will be loaded in the ga4_api schema in your database.

Please note that whatever table name you enter here will be prefixed by custom_ to ensure that it's clear that the table is from a custom report. So if you input landing_page in thie field, the table the report uses will be ga4_api.custom_landing_page.

Dimensions & metrics

This is where you choose which fields will be included in your custom report. You can start typing to search for a field, and the interface will autopopulate options to help make this process easier.

The field names in this section are as they appear in the GA4 Data API. To explore all of the dimensions and metrics available in the Data API and ensure you are making the right selections, use Google's GA4 Dimensions & Metrics Explorer tool. This lets you search the field list and see definitions for each dimension and metric.

Here are some important things to keep in mind when choosing dimensions & metrics:

Only 9 dimensions & 10 metrics are allowed per report

The GA4 Data API only allows 9 dimensions and 10 metrics per request, so your options are limited.

Some dimension + metric combinations are incompatible

Some fields have strict scope limitations that make them incompatible with other fields. When you choose an invalid combination, the GA4 Data API will return an error. For example, you will get an error if you combine an item-scoped field like itemName with an event-scoped field like eventCount.

When you choose your dimensions & metrics, you will click the Test button, and we will ping the Data API to validate the combination. If it is an invalid combination, you will see an error message.

Parameterized dimensions & metrics not currently available

Our custom report builder does not currently support parameterized dimensions and metrics that are specific to your property. For example, you can use the standard sessionDefaultChannelGrouping dimension, but you could not use a property-specific custom channel grouping like sessionCustomChannelGroup:607245006.

We plan to support these custom dimensions and metrics in the future, but they are not currently available.

Sync key

Our integration will pull data using a period that overlaps previous data pulls to ensure that we capture any updates. In that process, we will insert any new rows that are captured and will update any pre-existing rows.

The sync key is the unique value for each row that helps the integration determine if the new data should be inserted or should be used to update an existing row.

Typically you will only want to edit this field if you are including a unique identifier like transactionId in your custom report. In that case, you would want to use only transactionId + streamId as the sync key.

In all other instances, you should lave the sync key set to the default, which will be a combination of all the dimensions included in the report.

Partial report

You will want to toggle this to On if you are including the newVsReturning dimension or any attribution-related dimensions.

This option exists because there is a quirk with the GA4 Data API where it will return partially-processed data. So for example if you pull data before it is full processed, it may have a blank value for the newVsReturning or sessionSourceMedium dimensions. This causes issues with syncing because eventually that data will be fully processed, and those dimensions will no longer be blank. But since the blank value was used as part of the sync key, the new data will have a different sync key, and your metrics will become inflated.

When you turn the Partial report option on, the integration will actually create two tables, for example ga4_api.custom_landing_page and ga4_api.custom_landing_page_partial.

The ga4_api.custom_landing_page_partial table will always contain the previous 2 days of data. Instead of syncing this table, we delete the contents and reload the contents every day to ensure we do not run into the issue mentioned above with partially processed data.

The ga4_api.custom_landing_page table will always contain any data that is greater than 2 days old. The results of this table will be synced normally (new rows will be inserted, and existing rows will be updated) since this older data is fully processed.