BigQuery

Connect GradientHarbor to Google BigQuery to analyze your cloud data warehouse with AI-powered insights.

Prerequisites

• A Google Cloud project with BigQuery enabled
• A service account with BigQuery read access
• A service account JSON key file

Configuration

Field	Description	Required
Service Account JSON	The full JSON key file for the service account	Yes
Project ID	Google Cloud project ID (auto-detected from key)	Yes
Maximum Bytes Billed	Per-query billing cap to prevent runaway costs	No

Setup Steps

1. Create a Service Account

In the Google Cloud Console:

1. Go to IAM & Admin > Service Accounts
2. Click Create Service Account
3. Name it (e.g., gradientharbor-reader)
4. Grant the role BigQuery Data Viewer and BigQuery Job User
5. Create a JSON key and download it

WARNING

The BigQuery Job User role is required to execute queries. BigQuery Data Viewer grants read access to datasets and tables.

2. Add the Connector

1. Go to Administration > DB Connectors in GradientHarbor
2. Select BigQuery
3. Paste or upload the service account JSON key
4. Optionally set a Maximum Bytes Billed limit
5. Test the connection

3. Select Datasets

After initial introspection, select which BigQuery datasets to catalog. Only selected datasets will be introspected and made available to the AI agent.

Cost Control

BigQuery charges by bytes scanned. GradientHarbor provides two levels of cost protection:

1. Maximum Bytes Billed — Set a per-query cap in the connector configuration. Queries that would exceed this limit are rejected before execution.
2. Read-only execution — All queries run as read-only, preventing accidental data modifications.

TIP

Set a reasonable bytes-billed limit (e.g., 10 GB) to prevent the AI agent from accidentally running expensive full-table scans during exploration.

Troubleshooting

Issue	Solution
Permission denied	Ensure the service account has both BigQuery Data Viewer and BigQuery Job User roles.
Invalid JSON key	Verify you downloaded the key in JSON format (not P12). The file should contain "type": "service_account".
Dataset not showing	Check that the service account has access to the specific dataset. Dataset-level IAM may override project-level roles.