> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/concepts/resources/nilus/batch/batch-sources/google-analytics.md). # Google Analytics [Google Analytics 4](https://analytics.google.com/) is Google's web/app analytics platform. Nilus uses GA4 as a batch source to run [Data API](https://developers.google.com/analytics/devguides/reporting/data/v1) reports, built-in or custom, and load the results into a downstream warehouse. Under the hood, Nilus authenticates against the GA4 Data API using a Google Cloud service account, scoped to one GA4 property ID supplied in the URI host. ## Requirements Connectivity and credentials must both be in place before the pipeline can run. ### Connectivity * The Nilus runtime must be able to reach `https://analyticsdata.googleapis.com` over HTTPS. * Add the service-account email as a **Viewer** of the GA4 property (Admin → Property Access Management). * Pass the GA4 numeric property ID in the URI host (no `properties/` prefix). {% hint style="info" %} Service-account JSON keys are sensitive. Store via Nilus secrets/projections (or use `credentials_base64` from a secret) rather than committing the JSON to YAML. {% endhint %} ### Required parameters | Parameter | Required | Default | Description | | -------------------- | ------------------------------------------------- | ------- | ----------------------------------------------------------------------- | | `credentials_path` | Yes | - | Path to the service-account JSON key file inside the runtime container. | | `credentials_base64` | One of `credentials_path` or `credentials_base64` | - | Base64-encoded contents of the service-account JSON. | ### URI format ``` googleanalytics://?credentials_path= googleanalytics://?credentials_base64= ``` ## Supported reports | Report | Merge key | Strategy | Description | | ------------------------------- | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `traffic` | `date` | merge | Traffic-source breakdown by day. | | `events` | `date` | merge | Event counts by day and event name. | | `ecommerce` | `date` | merge | Ecommerce performance by day. | | `demographics` | `date` | merge | Demographics breakdown by day. | | `custom::` | configurable | merge | Custom GA4 report. Provide GA4 dimensions and metrics as comma-separated lists. Must include at least one date dimension (`date`, `yearMonth`). | ## Source options | Option | Required | Description | | ----------------- | -------- | -------------------------------------------------------------------------- | | `source_table` | Yes | One of the resources in the [supported reports](#supported-reports) table. | | `interval_start` | No | Lower bound for resources that support a time window. | | `interval_end` | No | Upper bound for resources that support a time window. | | `incremental_key` | No | Not used. Nilus manages refresh cadence per resource internally. | ## Sink options | Option | Required | Description | | ---------------------- | -------- | --------------------------------------------------------------------------------------------------- | | `dest_table` | Yes | Destination table name. Use one stable target per source resource so re-runs merge cleanly. | | `incremental_strategy` | Yes | Destination write behavior. Use `merge` for dated reports and `replace` for snapshot-style reports. | ## Sample Nilus config ```yaml name: googleanalytics-traffic-batch version: v1alpha type: nilus spec: type: batch compute: universe-compute source: address: googleanalytics://123456789?credentials_path=/etc/dataos/secret/ga4-sa.json options: source_table: traffic interval_start: "2024-01-01" interval_end: "2024-01-31" sink: address: dataos://warehouse?purpose=rw options: dest_table: marketing.ga4_traffic incremental_strategy: merge ``` ## Behavior and capabilities * **Pipeline mode**: Google Analytics runs as a `batch` source. * **Report selection**: set `source.options.source_table` to a built-in report or a `custom::` report from the supported reports table. * **Fetch semantics**: report windows are controlled with `interval_start` and `interval_end`; use a date dimension for custom reports that need merge-friendly incremental windows. * **Custom reports**: dimensions and metrics must be valid GA4 API fields, and custom reports should include `date` or `yearMonth` for time-windowed loads. * **API limits**: GA4 applies property-level quotas and may sample high-cardinality reports. Shorten windows or reduce dimensions when reports become too large. ## Troubleshooting | Symptom | Likely cause | Resolution | | -------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `PERMISSION_DENIED` | Service-account email is not a Viewer on the GA4 property. | Add it under Admin → Property Access Management → Add User. | | `SERVICE_DISABLED` | GA Data API not enabled in the Cloud project. | Enable `Google Analytics Data API` in Cloud Console → APIs & Services. | | Custom report fails | Dimensions/metrics not valid GA4 fields, or no time dimension. | Check the [GA4 dimensions and metrics list](https://developers.google.com/analytics/devguides/reporting/data/v1/api-schema) and include `date` or `yearMonth`. | | Sampled data warning | GA4 sampling on high-cardinality custom reports. | Reduce dimensions or shorten the window to stay below sampling thresholds. | ## Related docs * [Batch sample configs](/concepts/resources/nilus/batch/sample-configs.md) * [Understanding Batch Pipeline Config](/concepts/resources/nilus/batch/pipeline-config.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://v2.dataos.info/concepts/resources/nilus/batch/batch-sources/google-analytics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.