BigQuery Integration

Connect BigQuery to enable agents to query your datasets during investigations. This integration authenticates via a linked GCP integration. No static credentials are stored. You must have a GCP integration configured before adding BigQuery.

How It Works

The BigQuery integration delegates authentication to a linked GCP integration. At query time, Autoheal:

1. Resolves temporary GCP credentials from the linked GCP integration (via OIDC Workload Identity Federation)
2. Uses those credentials to execute read-only SQL queries against your BigQuery datasets

This means you configure OIDC federation once in the GCP integration, and any number of BigQuery integrations can reuse it.

Capabilities

Once connected, agents can:

Capability	Description
BigQuery Queries	Execute read-only SQL queries (SELECT, SHOW, DESCRIBE, EXPLAIN) against any dataset the GCP Service Account can access
Connection Test	Validate that GCP authentication and BigQuery dataset access are working

info

Mutation queries (INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, MERGE) are blocked at the application layer. This provides defense in depth on top of IAM-level read-only restrictions.

Prerequisites

• A working GCP integration configured in Autoheal with BigQuery access
• The GCP Service Account used by that integration must have:
  • roles/bigquery.dataViewer — to read data from tables and views
  • roles/bigquery.jobUser — to run queries (create jobs)

Setup

1

Set up a GCP integration

If you do not have one yet, create a GCP integration with the required BigQuery IAM roles. The BigQuery integration authenticates through it.

2

Add the BigQuery integration in Autoheal

1. Go to Integrations in Autoheal
2. Click BigQuery
3. Enter a name (e.g., "Production Analytics BigQuery")
4. Complete the fields:
   • GCP Integration (required): Select the GCP integration that provides authentication
   • Default Dataset (optional): A default dataset for unqualified table names (e.g., analytics). Can be overridden per query.
   • Dataset Location (optional): BigQuery dataset location. Defaults to US.
5. Click Test Connection to check the connection. Then click Save

Example Queries

Once connected, you can ask an agent:

Show me the most recent 50 error events from the incidents table

What are the top 10 customers by order count in the last 30 days?

What tables are available in the analytics dataset?

Show me the schema of the events table

Run a SELECT query on the production_metrics dataset to show daily active users for the past week

Security

• No stored credentials: Authentication is handled by the linked GCP integration via OIDC Workload Identity Federation. Autoheal never stores BigQuery credentials or service account keys.
• Read-only enforcement: Both IAM roles (bigquery.dataViewer) and the Autoheal application layer independently enforce read-only access.
• Scoped access: The GCP Service Account's dataset-level IAM bindings control exactly which BigQuery datasets this integration can query.

Troubleshooting

Test Connection fails with 'Please check if your linked GCP integration is enabled and working'

The BigQuery integration cannot obtain credentials from the linked GCP integration. Check:

• The linked GCP integration is enabled and passes its own connection test
• The GCP Workload Identity Federation setup is complete (pool, provider, service account binding)
• The Service Account email and Workload Identity Pool Provider resource name in the GCP integration are correct

BigQuery 403 'Access Denied'

GCP authentication succeeded but BigQuery rejected the query. The Service Account is missing required roles:

• roles/bigquery.dataViewer — allows reading data from tables and views
• roles/bigquery.jobUser — allows running queries

Verify with:

gcloud projects get-iam-policy YOUR_PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:autoheal-readonly@YOUR_PROJECT_ID.iam.gserviceaccount.com"

BigQuery 404 'Not Found'

The dataset or table name in your query doesn't exist in the project. List available datasets:

bq ls --project_id=YOUR_PROJECT_ID

Query blocked: 'Only read-only queries are allowed'

Autoheal only allows SELECT, SHOW, DESCRIBE, and EXPLAIN queries. INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, and MERGE statements are blocked at the application layer for safety.