BigQuery
Connect a BigQuery dataset to TraceX through a Google Cloud service account with read-only roles. Each question can scan at most 20 GB.
Connect one BigQuery dataset, read through a Google Cloud service account.
Why connect BigQuery
Section titled “Why connect BigQuery”Data warehouses hold the history your production database doesn’t: events, analytics, billing records, everything over time. With BigQuery connected, TraceX can answer questions like “when did signups from Android start dropping?” and back up an investigation with trends, not just single rows.
Before you start
Section titled “Before you start”- In Google Cloud, open IAM & Admin → Service accounts and create a service account,
for example
tracex-reader. - Give it BigQuery Data Viewer on the dataset (dataset → Sharing → Permissions) and BigQuery Job User on the project (needed to run queries).
- Open the service account → Keys → Add key → JSON and download the key file.
Connect
Section titled “Connect”In the dashboard, open Integrations → BigQuery and fill in:
| Field | Value |
|---|---|
| Service account key (JSON) | the key file’s contents |
| Dataset | analytics |
| Project id | optional, read from the key |
| Location | optional, e.g. US, EU, asia-south1 |
TraceX tests the connection, reads the schema, and is ready for investigations. The key is stored encrypted and never shown again.
How TraceX queries it
Section titled “How TraceX queries it”Every query TraceX writes is checked before it runs:
- it must be a single read-only statement: no writes, no schema changes, no locks, no file or remote functions;
- it runs in a read-only transaction with row and time limits, so a query can’t slow your database down;
- results are summarized for the investigation, and secrets in them are masked before an AI model sees them.
TraceX also reads the schema (tables or collections, columns or fields) when you connect, so it writes queries against names that really exist. Add notes about what a table is for in the company profile: they help it pick the right table first time.
Troubleshooting
Section titled “Troubleshooting”| Problem | What to check |
|---|---|
| Access denied running a query | The service account needs BigQuery Job User on the project, not only Data Viewer on the dataset. |
| Dataset not found | Check the dataset name and set the location if the dataset isn’t in US. |
| A query is refused for size | It would scan more than 20 GB. Ask about a shorter time range, or use partitioned tables. |
Remove access
Section titled “Remove access”Disconnect BigQuery in Integrations, then delete the key (or the service account) in Google Cloud.