BigQuery
By connecting Super with BigQuery, you can ask natural-language questions and get answers backed by live queries against your data warehouse — no SQL required.
This article covers connecting BigQuery, how Super uses your data, permissions, and troubleshooting.
Connecting BigQuery & Super
Required Permissions for Setup
To connect Super and BigQuery, you must have the necessary permissions* in both platforms.
- In Super: Permission to add or remove data sources depends on your team's settings. By default, only workspace admins or owners can set up a connection. However, a Super admin can enable a setting to allow all members to add and remove data sources.
- In BigQuery: You need permission to create a service account, generate a service account key in the Google Cloud project, and configure domain-wide delegation in Google Workspace.
*If you don't have these permissions, ask a Google Cloud admin to generate the service account key for you. A Google Workspace admin will need to set up domain-wide delegation.
Initial BigQuery Connection (Steps 1–5)
Step 1: Create a service account
Visit the Google Cloud Console and navigate to your project.
Go to IAM & Admin → Service Accounts.
Click Create Service Account.
Provide a name and description for the service account, then click Create and Continue.
Grant the service account the BigQuery User and BigQuery Data Viewer roles.
Click Continue and then Done.
Step 2: Generate a service account key
In the Service Accounts list, find the service account you just created.
Click it, then go to the Keys tab.
Click Add Key → Create new key.
Select JSON as the key type and click Create.
The JSON key file will be downloaded to your computer.
Step 3: Set up domain-wide delegation
Configure domain-wide delegation so the service account can run queries on behalf of each user, respecting their existing BigQuery permissions:
On the Details tab of the service account you created, select the Unique ID value and copy it.
Click Add new to create a domain-wide delegation with the Client ID you copied in the previous step.
Enter the following OAuth scope:
To copy it, click the block then click the Copy button that appears.
https://www.googleapis.com/auth/bigquery.readonly
Click Authorize.
Step 4: Connect BigQuery in Super
Click Data Sources in the left sidebar.
Find the BigQuery option and click Connect BigQuery.
A popup will appear. Paste the JSON service account key file you downloaded earlier.
Click Connect to BigQuery.
The initial data sync will begin.
Once the initial sync is complete, BigQuery will be available as a source when you ask questions in Super.
Step 5: Add your BigQuery tables in Super
Once the initial sync has been completed, BigQuery tables you have access to in the connected project will appear in the Available Sources section, paginated and searchable by name.
Check the tables you want to make available and click Sync N sources to add them. You can also hover a single row and click Add to sync just that one.
To find a specific table quickly, you can start typing its name in the search bar at the top, where it says "Filter sources...".
If a table you expect to see is missing, see the Frequently asked questions at the bottom of this article.
How Super Indexes Your BigQuery Data
What We Sync
Super indexes your BigQuery table metadata — schema, column types, row counts, partitioning, clustering, and any table or column descriptions added in BigQuery or in Super. For text, integer, and boolean columns, Super also samples distinct values: if a column has 50 or fewer unique values, all of them are stored as possible values; otherwise a handful of examples are stored. This helps the agent understand what kind of data each column holds — for example, that a
status column takes values like pending, paid, refunded.Super does not index row-level data. Instead, once the agent identifies the right table using the metadata above, it runs a live query against BigQuery to fetch real, up-to-date results at the time you ask your question.
Refresh Rate
Table metadata is synced automatically every 24 hours, but since queries run live against BigQuery, you always get the most current data when you ask a question. You can also trigger a manual sync at any time — open the three-dot menu on a synced table and select Sync manually.
Improving answer quality
Schema alone often isn't enough for the agent to understand what a table is for, especially in warehouses with cryptic column names, custom event schemas, or many similar-looking tables. Two practices significantly improve answer quality.
1. Add table descriptions
You can add a description to any synced table in Super. Open the Data Sources panel, find the table in the Synced list, click the three-dot menu on its row, and select Add table description. Descriptions are indexed alongside the schema and used by the agent at search and query time.
A good description tells the agent things schema alone can't — what the table is for, what one row represents, what units are used, and any quirks. For example: "Daily MRR snapshot. One row per workspace per day. Currency is always USD. Includes both active and churned workspaces; filter by
status = 'active' for current MRR."2. Use purpose-built views for complex schemas
If your warehouse has many tables that need to be joined to answer common questions, the agent will struggle to choose the right joins on its own. Instead, create views in BigQuery that match the kinds of questions you'll ask — pre-joined, with clean column names — and sync those views as your sources. This puts your data team in control of how Super sees the data and gives the agent a much cleaner surface to work with.
Access Control & Privacy
BigQuery is a Mirrored source: Super honors each user's individual BigQuery permissions. When you ask a question, Super impersonates your Google identity (via the domain-wide delegation set up earlier) and runs the query against BigQuery on your behalf. Google's own IAM rules — including row-level security, authorized views, and group-based access — are enforced natively. Super never bypasses them.
What permissions does a user need?
For a user to query a synced BigQuery table from Super, they need:
- BigQuery Data Viewer access to the specific table (or to the dataset/project it sits in). This controls whether they can see the table's contents.
- BigQuery User (or another role that includes
bigquery.jobs.create) at the project level. This is what allows queries to be run. Without it, the user will see a "permission denied" error even if they can see the table.
If you use Google Groups to manage BigQuery access, Super will respect those group-based permissions automatically.
What permissions are needed to set up new tables?
To list and sync new tables in the picker, the connecting user needs BigQuery Metadata Viewer access at the organization or project level. This is separate from the ability to query already-synced tables — once a table is synced, anyone with appropriate BigQuery permissions can query it without needing metadata viewer rights.
Frequently asked questions
I just synced a table but Super can't find it when I ask questions. What's wrong?
After syncing a new table there's a short delay (typically up to an hour) before it becomes queryable, while Super refreshes the list of tables you have access to. Wait a little and try again. If the table is still missing after that, check that you have BigQuery access to it.
What are common use cases for BigQuery in Super?
Teams typically use the BigQuery integration for questions that pull from warehouse data rather than from individual tools. Common patterns:
- Revenue and MRR tracking — querying billing and subscription data (often Stripe replicated into BigQuery). For example: "What's the evolution of MRR from our Stripe data?" or "Give me a week-over-week chart of usage volume for this account."
- Product analytics and usage insights — querying product event tables to understand how customers use the product. For example: "Week-over-week volume of
sq_javascript_eventsfor this org, then a breakdown of event names from the last 30 days." - CRM and pipeline queries — going beyond what HubSpot or Salesforce expose natively, by querying a BigQuery replica of CRM data for broader revenue and pipeline analyses.
- HR and recruitment aggregations — natural-language questions over HR data in the warehouse. For example: "How many candidates are currently in the interview stage?"
- Replacing manual SQL workflows — replacing the cycle of running BigQuery queries by hand and pasting results into Google Sheets, or triggering SQL via Zapier.
Can I query BigQuery through the Super API?
Yes. You can call the Super API from external tools — for example, from a Clay spreadsheet column or a Zapier step — to query BigQuery without setting up a separate BigQuery connector in those tools.
Can I use BigQuery as a source in an Assistant?
Yes. BigQuery can be enabled as a source on any Assistant, the same way you'd enable any other connected data source.