Overview
A BigQuery table lets Lens read directly from your warehouse. This is the path for GA4's BigQuery export, ecommerce order tables, or any modeled dataset you already maintain in BigQuery. Lens discovers the schema, you pick which scalar leaves become dimensions and metrics, and the sync job copies the result into ClickHouse for fast charting.
You authenticate with a service account. The shared TagPipes service account works out of the box, but for billing isolation per client you should point the table at a company-owned connection that carries your own GCP credentials. Either way, the service account needs read and query permission on the project.
Connect project and dataset
Open Lens > Tables, click + New Table, and choose Google BigQuery. Name the table, then choose a Service Account. If you use the shared account, grant its service-account email the BigQuery Data Viewer role on the dataset and BigQuery Job User on the project. Enter the Project ID (the project that owns the dataset) and the Dataset name; the region is auto-detected. Click Test Connection to confirm the account can list tables without reading any data.
Choose a query mode
Single Table reads one table from the dataset; use Browse to pick it. Wildcard Tables reads a set like events_*, which is how the GA4 BigQuery export is structured, with a Suffix Format of YYYYMMDD (daily) or YYYYMM (monthly). Custom SQL runs a full standard-SQL query, where you can bind the named parameters @start_date, @end_date, and @since from your Backfill Days.
Discover schema and set the date column
Click Discover Schema to fetch column types and nested structure. Then set the Date Column, which anchors each row's date partition. For Single Table and Custom SQL modes the date column is required, because every row needs a date for the partition key. For Wildcard mode it defaults to _table_suffix when left blank, since the suffix already encodes the date.
For REPEATED RECORD arrays such as GA4's event_params, add an UNNEST Mapping: pick the array path, the key column, an optional key value to filter on, and the value path to extract. Then pick scalar leaves as Dimensions (GROUP BY) and Metrics (numeric, summed by default). Nested fields are addressed with dot-paths like device.category.
Set backfill, save, and sync
Set Backfill Days (default 30). For wildcard tables it drives the _TABLE_SUFFIX range; for custom SQL it binds the date parameters; for single tables it's informational, since the whole table is read. Pick a schedule, then Save and Sync.
For the GA4 BigQuery export, use Wildcard mode with the events_* pattern and a YYYYMMDD suffix, leave the date column blank so it uses _table_suffix, and UNNEST event_params to flatten parameters like page_title into named columns.
BigQuery tables are Full Refresh only right now. The Incremental option appears but is disabled. Every sync wipes and reimports, so keep the backfill window scoped to what you actually need to chart.
Troubleshooting
Test Connection fails with a permission error
The service account lacks access. Grant the account BigQuery Data Viewer on the dataset and BigQuery Job User on the project. For company-owned connections, confirm the service-account JSON is for the correct project.
Sync fails on a missing date column
Single Table and Custom SQL modes require a date column for the partition key. Discover the schema and pick a DATE, TIMESTAMP, or DATETIME column, or type a custom dot-path if it lives inside a nested struct. Wildcard mode can fall back to _table_suffix, but the other modes cannot.
event_params columns are blank
Repeated records need an UNNEST mapping to flatten. Add a mapping that picks the array path (event_params), the key to match (for example page_title), and the value path to extract (value.string_value). The output column then appears in the dimension and metric pickers by its output name.