Skip to content
M↓ View as Markdown ↗

BigQuery

Connect a Google BigQuery dataset to Actian AI Analyst so you can build Models on its tables and let your AI Analysts query them.

Availability

  • Who can do this: members with the Edit capability in the active Workspace. If your organization turns on Restrict connection management, you also need the Manage organization capability.
  • Plan: available unless your organization's plan excludes the BigQuery connector.
  • Deployment: Actian SaaS and self-managed deployments, unless the deployment's operator has turned the BigQuery connector off.

Read-only access depends on the service account

BigQuery has no read-only session mode that AI Analyst can switch on, so AI Analyst cannot enforce read-only access itself. Read-only protection depends on the roles you grant the service account. Grant only BigQuery Data Viewer and BigQuery Job User. See Read-only access.

How a BigQuery connection is scoped

A BigQuery connection covers one dataset in one project. AI Analyst lists and queries only the tables in that dataset, and there is no schema picker after you connect. To expose another dataset, add another connection for it.

1. Create a service account

  1. In the Google Cloud console, go to IAM & Admin → Service Accounts.
  2. Click Create service account.
  3. Name it something like analyst-access.
  4. Skip granting roles here. Step 2 covers them.

2. Grant read-only permissions

Read access to the dataset

Give the service account access to the dataset you want AI Analyst to query:

  1. In BigQuery, open your dataset.
  2. Open its sharing or permissions settings.
  3. Add the service account's email address (for example, analyst-access@your-project.iam.gserviceaccount.com).
  4. Assign the role BigQuery Data Viewer (roles/bigquery.dataViewer).

This gives the service account read-only access to the dataset's tables, views and metadata.

Permission to run queries

AI Analyst runs each query as a BigQuery job in the project you enter in Project ID. Grant the service account BigQuery Job User (roles/bigquery.jobUser) on that project.

Note

Without BigQuery Job User, the service account cannot run queries, even if it can read the dataset.

3. Create a JSON key

  1. Open the service account.
  2. On the Keys tab, click Add key → Create new key, and choose JSON.
  3. Save the downloaded file. You paste its contents into AI Analyst in the next step.

Warning

The key file grants access to your data. Store it securely and delete local copies you no longer need.

4. Set up the connection in AI Analyst

  1. In Studio, open Connections and click the plus button (Add connection).
  2. Under Warehouses, select BigQuery.
  3. Under Connection details, enter a Name and, optionally, a Description. Select Private to this Workspace if only the current Workspace should use the connection. See Connections and Workspaces.
  4. Under Credentials, fill in:
    • Project ID: the Google Cloud project that contains the dataset, such as my-gcp-project.
    • Dataset ID: the single dataset this connection exposes, such as analytics.
    • Location (optional): the BigQuery job location, such as europe-west1. Leave it blank to detect it from the dataset.
    • Service account JSON: open the key file in a text editor and paste its full JSON contents. There is no file upload.
  5. Click Test connection.
  6. When the test succeeds, click Save connection.

Note

  • Save connection stays unavailable until the test passes. A successful test is valid for five minutes, and changing a connection field resets it. If either happens, test again.
  • BigQuery has no Paste a connection string option, because a service account key does not fit in a one-line connection string.
  • The service account JSON is encrypted at rest and never shown again after you save.

Query limits

Each query AI Analyst runs on BigQuery is capped at 10 GiB of billed bytes. BigQuery rejects a query that would bill more than that. If this happens, narrow the query (for example, with filters on partitioned columns) or model on smaller tables or views. For other limits, see Query limits.

Network access

AI Analyst reaches BigQuery through Google Cloud APIs with the service account, not through a host and port, so you usually do not need a firewall rule. If your organization restricts BigQuery API access by network (for example, with VPC Service Controls), check with your Google Cloud administrator. See also Network access.

Troubleshooting

When a test fails, the form shows a short summary, such as Authentication failed or Could not reach the warehouse. Expand it to see the error that the warehouse returned.

Symptom Likely cause What to do
The test fails because the credentials are invalid The pasted JSON is incomplete, or the key was deleted or disabled. Paste the full contents of a valid key file.
The test fails with an access or permission error The service account has no BigQuery Data Viewer access to the dataset, or the dataset is not in the project you entered. Check the dataset permissions and the Project ID and Dataset ID values.
The test fails because the configured location does not match the dataset location Location is set to a different region from the dataset's. Correct Location, or leave it blank to detect it automatically.
Queries fail although the test passed The service account cannot run jobs, or a query exceeds the 10 GiB billing cap. Grant BigQuery Job User on the project. See Query limits.

For connections that already exist, see Manage connections and Data source health monitoring.

Next steps

Create Models on the tables you want to analyze (see Creating models) and add them to an AI Analyst (see Models).