Skip to main content
Last updated: April 24, 2026
For most teams, the standard setup — granting BigQuery User at the project level — is the simplest path. But security-conscious organizations (especially those with shared GCP projects or compliance requirements) often want to scope Detrics’ access as narrowly as possible. This page describes a least-privilege configuration that:
  • Lets Detrics fully operate transfers and schema migrations
  • Scopes all data access to one specific dataset
  • Prevents Detrics from seeing or reading any other dataset or table in your project — even their names
This is the configuration we recommend for enterprise security reviews.
Image persistence is not compatible with least-privilege today. If you enable image persistence, the Detrics service account needs project-level roles/storage.admin to auto-create the Cloud Storage bucket that hosts the images — there is no narrower grant that works with the current flow. If your security policy doesn’t allow project-level Storage permissions, leave image persistence disabled. Everything else on this page applies normally.

​
How It Works

Detrics’ write path requires two distinct kinds of permission:
  1. The ability to submit jobs to BigQuery (queries, load jobs, DML). Job creation is a project-level action in BigQuery — it cannot be scoped to a dataset.
  2. The ability to read and write data. This can be scoped to a single dataset.
The trick is that the project-level “submit a job” permission grants no data access on its own. A job will fail with Access Denied unless the service account also has data permissions on the specific dataset the job touches. So combining a project-level jobUser with a dataset-level dataEditor gives Detrics exactly what it needs and nothing more.

​
Required Roles

ScopeRoleWhat it allows
Projectroles/bigquery.jobUserSubmit BigQuery jobs (queries, load jobs, DML). No data access.
Dataset (only the one Detrics writes to)roles/bigquery.dataEditorCreate, read, modify, and delete tables in this dataset. Insert and update data.
That’s it. Two grants, one of which is scoped to a single dataset.
The dataset must be pre-created by you under this configuration — Detrics won’t have permission to create it automatically. See Pre-creating the Dataset below.

​
Step-by-Step Setup

​
1. Pre-create the BigQuery Dataset

In Google Cloud Console:
  1. Navigate to BigQuery
  2. Click your project → Create Dataset
  3. Set the Dataset ID (e.g., detrics_marketing) and Data location (must match what you’ll configure in Detrics)
  4. Click Create Dataset

​
2. Grant BigQuery Job User at the Project Level

  1. Go to Google Cloud Console → IAM & Admin → IAM
  2. Make sure the correct project is selected in the top dropdown
  3. Click Grant Access
  4. In New principals, paste your Detrics service account email (shown on your destination page)
  5. In Select a role, search for and select BigQuery Job User
  6. Click Save
Do not grant any other project-level role. In particular, avoid BigQuery User, BigQuery Admin, basic Viewer, basic Editor, or basic Owner — any of these would broaden Detrics’ access beyond what’s needed and defeat the purpose of this setup.

​
3. Grant BigQuery Data Editor on Your Dataset

  1. In BigQuery Console, click your dataset (the one you created in step 1)
  2. Click SHARING → Permissions
  3. Click ADD PRINCIPAL
  4. Paste the Detrics service account email
  5. Select role BigQuery Data Editor
  6. Click Save

​
4. Test the Connection

In Detrics, open your destination and click Test Connection. All five stages should pass:
  • BigQuery Connectivity
  • Project Access
  • Dataset Permissions (verifies your pre-created dataset)
  • Table Permissions (creates and deletes a test table inside the dataset)
  • Job Permissions (loads and reads a test row)
If any stage fails, see Troubleshooting below.

​
What Detrics Can and Cannot Do

With this configuration, Detrics has access to a precise, verifiable subset of your project.

​
Can do (within the granted dataset only)

  • Create, alter, and drop tables
  • Insert, update, and delete rows
  • Read data from tables it created
  • Run queries that reference only this dataset
  • Run schema migrations using its safe temp-table-then-rename pattern

​
Cannot do (anywhere else in your project)

  • See the existence or names of other datasets
  • List tables or read metadata in other datasets
  • Query data from any other dataset
  • Create or delete datasets
  • Read IAM policies, billing data, or any other GCP resource
You can confirm exactly what permissions the service account has at any time using the IAM Policy Troubleshooter in the GCP Console.

​
Pre-creating the Dataset

In the standard setup, Detrics auto-creates the dataset on first use. Under least-privilege, that creation permission is intentionally not granted, so you create the dataset yourself once during setup. Day-to-day operation does not require any further intervention from you — Detrics manages tables and rows within the dataset on its own. If you ever need to add a second dataset (for example, to separate environments), repeat the dataset-level grant for each one.

​
Troubleshooting

The dataset doesn’t exist yet and Detrics tried to create it. Pre-create the dataset in BigQuery Console (see Step 1 above) and re-run the test.
The BigQuery Job User role wasn’t granted at the project level, or hasn’t propagated yet. Confirm the role is assigned in IAM & Admin → IAM, then wait ~60 seconds and retry.
The BigQuery Data Editor role wasn’t granted on the dataset itself. Open the dataset in BigQuery Console → SHARING → Permissions and confirm the service account is listed with BigQuery Data Editor.
This usually means the service account inherited a broader role from somewhere — most commonly a basic Viewer, Editor, or Owner role at the project level, or an explicit grant on another dataset. Audit:
  1. Project IAM — confirm the service account has only BigQuery Job User
  2. Each suspicious dataset — open it in BigQuery Console → SHARING → Permissions and remove the service account if present
  3. Inherited roles — basic project roles (Viewer/Editor/Owner) automatically grant data-level read across all datasets. Look for “Viewers of project X” or “Editors of project X” entries on dataset sharing panels — those are inherited from project-level basic roles

​
When to Use This Setup

Choose least-privilege when:
  • Your GCP project is shared with other workloads or contains sensitive data
  • Your security or compliance team requires least-privilege access for third-party integrations
  • You want a defense-in-depth posture even if Detrics’ credentials were ever compromised
Choose the standard setup when:
  • The GCP project is dedicated to Detrics (no other data lives there)
  • You’d rather not pre-create the dataset yourself
  • You need image persistence (requires project-level Storage Admin, not compatible with least-privilege)
  • Convenience matters more than scope-limited access in your context
Both setups are fully supported. You can also start with the standard setup and migrate to least-privilege later — just remove the broader project role, pre-create the resources, and add the scoped grants.