Integrating Google BigQuery on Clarisights

Connect a Google BigQuery table or view to Clarisights so internal datasets — attribution, LTV, finance, or any governed table you maintain in BigQuery — flow directly into your reports. The most common use is joining backend conversion data to ad spend and adding internal performance metrics that don't live in any ad platform.

At a glance

Connector type	Data warehouse (read-only)
Authentication	Service account (Clarisights-managed) with IAM access on your project
Permissions needed	BigQuery Data Viewer + BigQuery Job User
Object support	Tables and views
Refresh cadence	Set per pipeline
Limited rollout	No

Authentication options

BigQuery uses a single authentication model:

• Service account / IAM grant — Clarisights manages a dedicated Google Cloud service account for your workspace. You grant that service account email IAM access on your BigQuery project and dataset. There is no JSON key, password, or OAuth flow for you to manage.

Setting up the connection

Step 1 — Identify the dataset to share

Decide which dataset and which table or view you want Clarisights to read. If the data lives in a brand-new dataset, create it in BigQuery first. You can share an existing dataset; you don't need a new one.

Step 2 — Get the Clarisights service account email

Ask your CSM (or write to support@clarisights.com) for the service account email assigned to your workspace. The same email is reused across every BigQuery connection you set up.

Step 3 — Grant IAM access

In Google Cloud Console, grant the Clarisights service account email these two roles:

• BigQuery Data Viewer — on the dataset (or the specific table/view) you want to share. This grants read access on the data.

• BigQuery Job User — on the project. This lets Clarisights run the queries that read your data.

Both roles are required. Job User alone can't read data; Data Viewer alone can't run queries.

Access Denied: User does not have permission → the service account is missing one of the two roles. Confirm BigQuery Data Viewer is on the dataset and BigQuery Job User is on the project.

Step 4 — Share the connection details

Send your CSM:

• Project ID (e.g. my-org-prod)

• Dataset name

• Table or view name

We validate by running a small probe query against the table or view. Once that succeeds, the connection is live and the first scheduled pull begins.

Table not found → double-check the project ID, dataset, and table or view name you shared. BigQuery names are case-sensitive.

Connection details exchange

You provide to Clarisights	Clarisights provides to you
GCP project ID	Service account email (one per workspace)
Dataset name
Table or view name
IAM role grants on the project + dataset

What we read

Clarisights reads the rows of the table or view you point us at. Each row becomes a record in your report, and each column becomes a dimension or metric.

Tables and views

Both are first-class. Pointing us at a view is equivalent to pointing us at a table — you don't lose anything by using a view, and views are often the cleanest way to control exactly what data Clarisights sees (you can pre-filter rows, rename columns, or join other tables in the view definition).

Nested data

Nested data is like boxes inside boxes. Clarisights reads tables that look like flat lists — one row, one set of columns. If your table has a nested column (a column that contains a smaller table inside it — RECORD or REPEATED types in BigQuery), Clarisights may not load it correctly.

The fix: create a view on your side that flattens the nested columns into normal columns (BigQuery's UNNEST(...) does this), and point us at the view instead of the original table.

Connector specifics

• Query timeouts. Each pull runs a query against your table or view. If a query exceeds BigQuery's job timeout it will fail. For very large tables, prefer pointing us at a view that limits the row range — for example, a view that reads only the last N days from a partitioned base table.

• Partitioning helps. If your base table is partitioned (typically by date), a view that filters on the partition column will let queries scan far fewer bytes and run reliably even on large datasets.

• Query bytes are billed to your project. Because Clarisights runs queries inside your GCP project, the bytes scanned are billed to you. Right-size partitions and clustering, and prefer views that limit scan size.

Limitations & known constraints

• One object per connection. Each BigQuery connection maps to a single table or view. To bring in additional tables, set up additional connections.

• Read-only. Clarisights runs SELECT queries only and never writes back to BigQuery.

• Nested columns aren't supported directly. Flatten RECORD and REPEATED columns in a view (using UNNEST) and point us at the view.

• External tables need extra access. Tables backed by Cloud Storage, Drive, or other external sources require the Clarisights service account to also have read access on the underlying source (e.g. Storage Object Viewer on the bucket).

Operating notes

• Refresh cadence is set per pipeline at the time we configure the connection. Daily is typical; faster cadences are available — discuss with your CSM.

• IAM rotation. The service account email and the IAM grants you put in place are stable. There is no key or password to rotate on your side. If you ever need to revoke access, remove the IAM grants in Google Cloud Console.

• VPC Service Controls. If your project enforces VPC-SC, add the Clarisights service account to your access policy.

Need help?

When contacting support from the in-app messenger, please include:

• The integration name and account ID (Integrations → your BigQuery connection)

• The exact error message or screenshot

• The step where the issue occurred

• When the issue started