Overview
Everything in Lens begins with a data table. Boards, reports, KPI tiles, and calculated metrics all query tables for their numbers. A table is a ClickHouse table under the covers, populated by a sync job that pulls from an external source (GA4, a CSV upload, an Airbyte connector, an S3 folder of JSONL files) or derived from other tables via join, union, or pivot operations.
Because ClickHouse is columnar and fast, Lens can serve interactive charts on top of tens of millions of rows without a warehouse bill. The tradeoff is that you need to think about your schema up front: which columns are dimensions, which are metrics, which date column anchors the table. Get those right when you create the table and you'll rarely need to revisit the decision.
Navigate to Tables
Open Lens > Tables from the left sidebar. The list shows every table scoped to your property, with the source type, row count, and last sync timestamp. Click Add Table to create a new one.
Choose a data source
The first decision is the source type. GA4 pulls from the Google Analytics 4 Data API using an OAuth connection. Google Ads reads campaign cost, clicks, impressions, and conversions, or account config, from a chosen report stream. Adobe Analytics pulls a report suite broken down by one dimension. CSV takes a file upload, which is handy for one-off datasets or data that doesn't have a programmatic source. Airbyte uses connector-based sync for SaaS apps that Airbyte supports. JSONL reads newline-delimited JSON from S3, and Google Cloud Storage and Amazon S3 read JSONL from your own buckets.
More sources cover your warehouse and live data. Echo (real-time events) reads your own server-side events that Echo writes as JSONL to S3, synced incrementally (one per property). BigQuery reads a single table, a wildcard table set like events_*, or a custom SQL query from your warehouse. REST API polls any JSON endpoint on a schedule with configurable auth, pagination, and date parameters.
The derived source types combine other tables. Join merges two tables on shared dimensions (for example date + source, producing a wider row per combination). Union stacks tables and deduplicates by date, useful for layering real-time Echo data over slower GA4 backfills. Pivot performs conditional aggregation when you want one row per entity with metrics split across columns rather than rows.
Configure dimensions and metrics
For GA4 tables, select the dimensions (date, source, medium, etc.) and metrics (sessions, conversions, revenue) you want. Lens always includes date on GA4 tables automatically, because time is how everything downstream pivots. For CSV sources, map your file's column headers to Lens dimension and metric types so it knows how to aggregate them.
Join, Union, and Pivot tables ask for the source tables instead of raw columns. Pick the upstream tables, then tell Lens which columns to align on. Changes to an upstream table's schema can break a derived table, so name your columns consistently across sources when you know you'll combine them.
Set sync schedule
Choose how often data should refresh: Hourly, Daily, Weekly, Monthly, or Manual. Manual means the table only syncs when you click the button in the UI, which is fine for CSV uploads and one-off exports but wrong for anything you want to keep current.
For GA4 tables, the first sync honors the Backfill Days setting (7, 30, 90, 180, or 365). Subsequent syncs are incremental and only pull the trailing 7 days, which respects GA4's 48-hour data finalization window while keeping queries fast. If you need more history after the initial sync, edit the backfill range and trigger a manual sync to extend the window.
Save and sync
Click Save. The table record is created but it contains no data yet. Click Sync to pull the first batch from the source. Progress shows in real time, and once it finishes the rows are in ClickHouse ready for boards to query. From here on, the schedule you chose keeps the table current, or you can re-sync manually any time.
Join tables combine data from different sources on shared dimensions like date plus source. Union tables merge multiple tables with date-based deduplication, which is exactly what you want to layer real-time Echo data on top of daily GA4 backfills. You cannot delete a table that another table depends on (Join, Union, or Pivot), so reorganize downstream tables first.
Troubleshooting
GA4 sync fails immediately with an auth error
The OAuth token tied to your Google service connection has expired or been revoked. Open Settings > Service Connections, find the Google entry, and reconnect. GA4 refresh tokens can be invalidated if the Google account owner revokes access or if the account's 2FA settings changed.
CSV upload rejected as "invalid format"
Check the file has a header row and that the column delimiter is a comma. Lens is strict about comma-separated format for CSV uploads. Excel sometimes saves CSV with a BOM or semicolon delimiters in locales outside the US; re-save as UTF-8 comma-delimited to fix it.
Join or Union table shows fewer rows than expected
Joins only emit rows where the join key matches in both tables, so if one source has date records the other doesn't, those dates drop out. Unions deduplicate by date, so overlapping dates between sources collapse to a single row. Review the join keys and date coverage in each source table; the answer is almost always on the upstream side rather than in Lens itself.