BigQuery

This guide walks you through connecting a Google BigQuery dataset to Roundtable so the AI can query your data using the query_bigquery tool.

Prerequisites

Before you begin, make sure you have:

• A Google Cloud project with the BigQuery API enabled.
• A BigQuery dataset containing the tables you want to query.
• Owner or Editor permissions on the GCP project (to create a service account).
• Admin access to your Roundtable organization (to create connections).

---

Step 1: Create a Service Account

The service account gives Roundtable read-only access to your BigQuery data.

1. Open the Google Cloud Console.
2. Select your project from the project picker.
3. Navigate to IAM & Admin → Service Accounts.
4. Click Create Service Account.
5. Enter a name (e.g., roundtable-bigquery-reader).
6. Click Create and Continue.
7. Grant the service account the BigQuery Data Viewer role.
   • This role provides read-only access to table data and metadata.
   • If you also want the AI to see dataset and table listings, add the BigQuery Metadata Viewer role.
8. Click Done.

tip

Follow the principle of least privilege. The BigQuery Data Viewer role allows SELECT queries but prevents any data modification. Only add additional roles if your use case requires them.

---

Step 2: Download the JSON Key

1. In the Service Accounts list, click the service account you just created.
2. Go to the Keys tab.
3. Click Add Key → Create New Key.
4. Select JSON as the key type.
5. Click Create.

A .json file will download to your machine. This file contains the private key that Roundtable will use to authenticate. Keep it secure.

danger

Treat this JSON key like a password. Do not commit it to version control, share it in chat, or store it in an unsecured location. After uploading it to Roundtable, you can delete the local copy.

---

Step 3: Add the Connection in Roundtable

1. Go to your Roundtable organization's Settings → Connections.
2. Click Add Connection.
3. Select BigQuery as the connection type.
4. Fill in the required fields:

Field	Description	Example
Connection Name	A friendly label for this connection	Production BigQuery
Project ID	Your GCP project ID	my-company-analytics
Dataset	The default BigQuery dataset to query	analytics
Service Account Key	The JSON key file contents	Paste or upload the .json file

5. Click Save.

---

Step 4: Test the Connection

After saving, click the Test Connection button. Roundtable will:

1. Authenticate with BigQuery using the service account key.
2. Verify that the specified project and dataset exist.
3. Confirm that the service account has read permissions.

If the test succeeds, you'll see a green checkmark. If it fails, the error message will indicate the issue — common problems include:

Error	Cause	Fix
Permission denied	Service account lacks the required role	Add BigQuery Data Viewer role
Dataset not found	Typo in dataset name or wrong project	Double-check project ID and dataset name
Invalid key	Malformed or expired JSON key	Generate a new key and re-upload

---

Step 5: Attach to a Workspace

1. Open the workspace where you want BigQuery access.
2. Go to Settings → Connections.
3. Select your BigQuery connection from the dropdown.
4. Click Save.

The query_bigquery tool is now active in this workspace.

---

Example: Querying Your Data

Once the connection is live, workspace members can ask the AI to query BigQuery in natural language:

User:

What were the top 5 products by revenue last month?

AI response (using query_bigquery):

The AI will:

1. Generate a SQL query like:

   SELECT product_name, SUM(revenue) AS total_revenue
   FROM `my-company-analytics.analytics.orders`
   WHERE DATE(order_date) >= DATE_SUB(CURRENT_DATE(), INTERVAL 1 MONTH)
   GROUP BY product_name
   ORDER BY total_revenue DESC
   LIMIT 5

2. Execute the query against your BigQuery dataset.
3. Return the results in a formatted table with a plain-language summary.

tip

Give the AI context about your schema in the system prompt. When the AI knows your table names, column types, and business terminology, it writes more accurate queries on the first try.