Google BigQuery Integration

The BigQuery integration lets agents run SQL queries against your Google BigQuery datasets. Use it to look up customer data, generate reports, check analytics figures, or retrieve any structured data stored in BigQuery — directly from a conversation.

Authentication

BigQuery uses a service account JSON key for authentication.

Field	Description
Service Account JSON	Full JSON content of a GCP service account key file
Project ID	Your GCP project ID (e.g. my-company-prod)
Location	BigQuery dataset location — optional, defaults to US

Minimum IAM permissions:

• roles/bigquery.dataViewer — for SELECT queries
• roles/bigquery.dataEditor — for INSERT, UPDATE, DELETE
• roles/bigquery.jobUser — required on the project to run jobs

To generate a key: GCP Console → IAM & Admin → Service Accounts → select or create a service account → Keys → Add Key → JSON.

Installing

1. Go to your project → Integrations → Browse
2. Find Google BigQuery and click Install
3. Paste the full service account JSON into the Credentials JSON field
4. Enter your Project ID
5. Optionally enter a Location (e.g. EU, us-central1)
6. Select the Run Query action
7. Click Install

Actions

run_query — Run Query

Executes a SQL query against BigQuery and returns the results.

Tool reference: {{tool:bigquery_run_query}}

Parameters:

Parameter	Required	Description
query	Yes	SQL query to run. Use {{param}} placeholders for dynamic values
project_id	No	Override the project ID set during installation
location	No	Override the dataset location

Returns: Array of rows as objects, plus count (number of rows returned). Capped at 1,000 rows.

Supports: SELECT, INSERT, UPDATE, DELETE, MERGE. DML statements return [{"affected_rows": N}].

Using BigQuery in an agent

Attach the BigQuery tool and describe what data the agent should look up. Example system prompt fragment:

When a user asks about their account usage or billing data, use
{{tool:bigquery_run_query}} to query the analytics dataset.

Dataset: `my-company-prod.analytics`
Tables: `events`, `sessions`, `users`

Example:
- "How many active users last week?" →
  SELECT COUNT(DISTINCT user_id) as count
  FROM `analytics.events`
  WHERE DATE(timestamp) >= DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY)
  AND event_type = 'session_start'

Only return data that directly answers the user's question.
Do not expose raw SQL in your response.

Limitations

• Results are capped at 1,000 rows per query
• Queries must complete within 60 seconds — long-running jobs will time out
• The service account must have bigquery.jobUser on the project, not just on the dataset
• Cross-project queries require the service account to have access to all referenced projects

Troubleshooting

403 Access Denied

The service account doesn't have the required roles. Verify it has at minimum bigquery.dataViewer and bigquery.jobUser on the project.

404 Not Found: Dataset

The dataset or table name is wrong, or the service account doesn't have access to that dataset. Check that the project_id matches the dataset's project.

Query timeout

The query is taking too long. Add a LIMIT clause or filter by a date partition column to reduce scan size.

Invalid JSON credentials

The service account JSON was pasted incorrectly. It should start with { and end with }. Copy the entire file content including the curly braces.