BigQuery

Connect a Google BigQuery dataset and ask questions about it in plain English. BigQuery connects with a Google Cloud service account, not a Google sign-in.

Before you start

You’ll need:

• A Google Cloud project with the BigQuery API enabled.
• A service account that can read your dataset, and its JSON key file.
• Admin rights in your Terno workspace, to see the option to add a datasource.

Connect BigQuery

1. Click Add Data Connectors, open the Datasources tab, and choose BigQuery.
2. Choose Standard Setup or Connection URI at the top of the form.
3. Leave Start exploring my database ticked (it’s on by default). Right after connecting, Terno opens a background chat that explores the database and learns its tables, joins, and metrics. You’ll find it in your chat history and can open it any time.
4. Enter a Display Name and an optional Description, then fill in the fields below.
5. Click Add Connection. Terno tests the connection before saving it. If the test fails, you’ll see what went wrong, and nothing is saved.

Connection fields

Display Name required

A name for this connection, such as Production DB or Sales warehouse. It can be up to 40 characters and must be unique.

Description optional

A short note on what the data is about, such as Orders, customers, and payments for our online store. Up to 1024 characters. Terno uses it to understand when to use this source.

Standard Setup

PROJECT_ID required

The Google Cloud project that holds your dataset, such as acme-analytics.

DATASET_ID required

The BigQuery dataset to analyse, such as sales.

SERVICE_ACCOUNT_JSON required

Paste the contents of the service account’s .json key file, or upload the file. In Google Cloud, go to IAM & Admin → Service Accounts, pick the account, open Keys, and choose Add key → Create new key → JSON.

Connection URI

bigquery://project_id/dataset_id

Add the service account JSON alongside it. It’s marked optional in the form, but BigQuery needs it to connect.

Create a read-only user

BigQuery doesn’t use database users. Instead, give the service account read-only roles in Google Cloud:

• BigQuery Job User (roles/bigquery.jobUser) on the project, so it can run queries.
• BigQuery Data Viewer (roles/bigquery.dataViewer) on the dataset, so it can read tables.

Terno checks the connection by listing and opening your dataset, so the account needs at least these roles. You can grant Data Viewer on individual datasets to keep access narrow.

After you connect

Terno reads your tables, columns, primary keys, foreign keys, and row counts. You’ll get a DataSource Ready notification when it’s done, and the new source appears in the sidebar’s Data Connectors panel. Expand it to see its tables.

Ask questions

Start a chat and ask in plain English, for example:

• “Which 10 customers spent the most this year?”
• “What’s the average order value by month?”
• “Show a chart of new sign-ups per week this quarter.”

Terno writes the SQL for BigQuery, runs it, and replies with tables, charts, and an explanation. You don’t need to know SQL.

Keep query costs down

BigQuery charges by how much data a query scans, not by how many rows it returns. A few habits help:

• Give a time range: “daily sales for the last 3 months” scans far less than “sales trends”.
• Be specific: name the metrics and segments you need instead of “analyse everything”.
• Start small, then drill down: ask for the top 5 categories, then dig into one.
• Use summary tables when you have them, and say so: “Using monthly_revenue_summary, …”.
• Partition and cluster large tables by date so BigQuery can skip data it doesn’t need.

Security

• Credentials are encrypted at rest and used only to connect to your database.
• The AI never sees your password or connection string.
• SQLShield allows only a single read-only SELECT per query. Inserts, updates, deletes, and schema changes are blocked.
• Admins can hide tables, columns, and rows from groups of users. See Access control.

Troubleshooting

Connection timed out, or Terno can’t reach the server

• Check the host and port.
• Make sure the database accepts connections from outside your network, and that no firewall or security group blocks it.
• Use a real hostname or IP address. localhost and 127.0.0.1 point to Terno’s own servers, not yours.
• Check the database is running.

Authentication failed

• Check the username and password. Watch for extra spaces when pasting.
• Make sure the user is allowed to log in to this database.
• If you used a Connection URI, special characters in the password (like @, /, :) must be URL-encoded.

The database does not exist

Check the spelling of the database name. It’s the database inside the server, not the server name.

Terno can’t find my tables

• Make sure the user has SELECT permission on the tables.
• Check you connected to the right database and dataset, and that the service account can see it.
• An admin may have hidden some tables. See Access control.

See Connection errors for the full list of messages.

Best practices

• Use a read-only user created just for Terno, with access to only the data you want to analyse.
• Try a staging or replica database first before connecting production.
• Add a description and table descriptions so Terno picks the right tables. See Add context.
• Watch database load when asking for large, unfiltered results on production systems.
• Work with your database administrator on network access and permissions.