Google BigQuery¶

Connect Adverity Atlas to your BigQuery project. Choose the authentication method that fits your organization’s security policies.

Prerequisites¶

A user or role that can read the data you want to query. Adverity Atlas only issues read queries against your tables, it does not create, modify, or drop them, so read access is all it needs.

The identity needs these roles:

Role	Purpose
`BigQuery Data Viewer`	Read access to tables and views
`BigQuery Job User`	Permission to run queries
`BigQuery Metadata Viewer`	Schema and table listing

What Adverity Atlas reads¶

A sync lists the objects in each dataset you bind and records what kind each one is. Profiling then runs aggregate queries over the types it can profile, and those field statistics are what Chat and the glossary work from. An object that is discovered but not profiled is still queryable, it just carries no statistics.

Object type	Discovered and queryable	Profiled
Tables, including external tables	Yes	Yes
Views	Yes	No
Materialized views	Yes	No

Any other object type, a table snapshot for example, is skipped rather than guessed at, so it does not appear in your schema.

Querying and profiling need the same access: SELECT on the objects you want available. Profiling adds no privilege of its own, it reads the same objects with aggregate queries. The Connection test on the wizard’s Test step proves exactly that access, in the order a sync needs it: connect, list the schemas, list the tables in the target schema, and read a row.

Authentication methods¶

Google BigQuery supports 3 authentication methods. Choose the one that matches your security posture.

Service Account JSON¶

Paste a Google service-account JSON key. Best for unattended sync.

Best for: Initial setup, unattended sync, single-project access.

Credentials:

Field	Description
Service Account JSON	e.g. `{"type": "service_account", ...}` Stored encrypted.	Required

Workload Identity Federation¶

Federate an external identity (AWS/Azure/OIDC) to a GCP service account, no service-account key. For Adverity Atlas running outside GCP.

Best for: Organizations that prohibit long-lived service account keys and run Adverity Atlas outside GCP (AWS, Azure, or any OIDC provider).

Credentials:

Field	Description
Credential Config JSON	e.g. `{"type": "external_account", ...}` Stored encrypted.	Required

Sign in with Google¶

Authorize with your own Google account. You’ll pick the GCP project after sign-in.

Best for: Teams where each user has their own BigQuery permissions.

Note

An admin must first create a service config with the OAuth client credentials, under Settings > Integrations.

Saving that config checks it against Google straight away, no sign-in needed: its Status reads Verified once Google has accepted the client, or Verification failed with Google’s reason, so a wrong or rotated Client Secret shows up before anyone reaches a consent screen. See Service configs.

No credentials are stored for this method.

Setup¶

Go to Settings > Data Governance > Data Sources. Under Add Connection, choose BigQuery. The Add a data source wizard opens and runs in five steps.
Source, confirm BigQuery is selected and click Continue.
Auth method, pick one of the methods above and click Continue.
Authenticate. For Sign in with Google, click the sign-in button under Sign in yourself, authenticate with the provider, and you are returned to the wizard. For every other method, fill in the Configuration and Credentials fields and click Save credentials. Then click Continue.
Test, Adverity Atlas tests the connection as soon as you arrive and shows the result under Connection test. Continue unlocks once the test passes. After fixing a failure, click Test again. Back discards the saved credentials and returns you to Authenticate, with the configuration still filled in.
Review & create, enter a Name, choose a Sync schedule, and pick a Mode: Active (sync runs on schedule and agents can query this source), Development (sync runs, but agents cannot query it yet), or Disabled (no automated operations). Then click Create data source.

The Connection test runs the full connection diagnostic: it authenticates, lists the visible schemas, lists the tables in the target schema, and reads a row. You cannot continue to Review & create until every check passes, so a wrong credential or a missing grant is resolved here rather than becoming an unhealthy source afterwards. A failed check reports the warehouse’s own error, and the grant that is missing where Adverity Atlas can work it out, see Connection diagnostics. A test that could not run at all says “The connection test could not run. Try again in a moment.”

With Sign in with Google, the first test runs before a project is chosen, so it checks Sign in & list projects: that the sign-in works and that the account can see at least one project with BigQuery. When the account can see exactly one project, Adverity Atlas picks it for you (“Using project, the only BigQuery project this account can see.”) and tests again with it. Otherwise, Continue opens the project picker. Pick a project and you return to Test, which runs the full test with that project before Review & create unlocks.

Adverity Atlas verifies the connection as soon as the source is created, and starts the first sync when verification succeeds and the mode allows it. Schema discovery and field profiling run from that sync.

Tip

If someone else holds the credentials, use Share a one-time link under Or ask someone else on the Authenticate step. They submit the credentials through that link and see the connection test run on their page too. If it fails, Provide credentials again lets them correct what they entered. Your wizard moves on to Test once they submit, so the secret never passes through you.

Connection fields¶

These appear under Configuration on the wizard’s Authenticate step.

Field	Description
Project ID	e.g. `my-gcp-project` Only for Workload Identity Federation.	Required for Workload Identity Federation

Troubleshooting¶

Symptom	Likely cause
“Service account JSON must be valid JSON”, “Service account JSON must have “type”: “service_account””, or “Service account JSON is missing …” when saving credentials	The pasted key is not a complete Google service-account key. Paste the whole JSON key file as downloaded, including `project_id`, `private_key`, `client_email`, and `token_uri`. A Workload Identity Federation config (`"type": "external_account"`) belongs under that method instead.
“Permission denied” on test	The service account or user is missing BigQuery Data Viewer, Job User, or Metadata Viewer.
“Your Google account has no projects with BigQuery enabled.” on test	The account you signed in with cannot use BigQuery in any project. Click Back and sign in with an account that can use BigQuery in at least one project.
“No datasets found”	Project ID is wrong, include/exclude patterns are too restrictive, or Metadata Viewer is not granted at project level.
OAuth token expired or revoked	Re-authenticate via Sign in with Google. Check Google Account > Security > Third-party access.
Service config shows “Verification failed”	The reason under the badge is Google’s own. “Invalid client credentials” means the Client ID or Client Secret does not match the OAuth client in the Google Cloud console; the secret may have been rotated there. Fix and save to check again.
Profiling a table fails with an access-denied message	The connection can see the table but BigQuery refuses to read it, for example an external table whose files the connection cannot reach. The message is BigQuery’s own explanation. The table is kept, so grant the access and profile it again.
Federation fails	The external identity is not mapped to the target service account, or the workload identity pool is misconfigured.

What’s next?¶

Configure the glossary, align the language across your platforms so answers use your definitions
Ask questions about your data, start a conversation against the data you just connected
Data sources, schema discovery, profiling, and managing connections