BigQuery Setup

Overscore connects to BigQuery through a Google Cloud service account. This guide walks you through creating the service account, granting the right permissions, and connecting it in the Hub.

Overview

The connection flow works like this:

  1. You create a service account in Google Cloud
  2. You grant it read access to your BigQuery datasets
  3. You download the JSON key file
  4. You upload the key in the Overscore Hub
  5. Your dashboards can now query BigQuery

Your credentials stay on the server. The service account key is never sent to the browser or included in your deployed dashboard bundles. All queries are executed server-side, and only the results are returned to the client.

Step 1: Create a Service Account

  1. Go to the Google Cloud Console
  2. Select the project that contains your BigQuery datasets
  3. Navigate to IAM & Admin → Service Accounts
  4. Click Create Service Account
  5. Give it a descriptive name, e.g., overscore-reader
  6. Click Create and Continue

Step 2: Grant BigQuery Roles

On the "Grant this service account access to project" step, add the following roles:

  • BigQuery Data Viewer (roles/bigquery.dataViewer) — allows reading data from tables and views
  • BigQuery Job User (roles/bigquery.jobUser) — allows running queries

These two roles together give the service account read-only access to your data and the ability to execute queries. It cannot modify or delete anything.

If you only want the service account to access specific datasets (rather than all datasets in the project), you can grant BigQuery Data Viewer at the dataset level instead:

  1. Go to BigQuery in the Cloud Console
  2. Click on the dataset you want to share
  3. Click Sharing → Permissions
  4. Add the service account email and assign the BigQuery Data Viewer role

You'll still need BigQuery Job User at the project level regardless, since that's required to run queries.

Step 3: Download the JSON Key

  1. After creating the service account, click on it in the service accounts list
  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 computer. This file contains the private key for the service account — keep it secure and don't commit it to version control.

The JSON file looks something like this:

{
  "type": "service_account",
  "project_id": "your-gcp-project",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "overscore-reader@your-gcp-project.iam.gserviceaccount.com",
  "client_id": "...",
  ...
}

Step 4: Upload in the Hub

  1. Sign in to the Overscore Hub
  2. Open your project
  3. Go to the Settings tab
  4. Under BigQuery Connection, click Upload Service Account Key
  5. Select the JSON file you downloaded
  6. Click Save

The key is encrypted and stored securely. Only server-side query execution uses it.

Step 5: Test the Connection

After uploading your key, you can verify the connection works:

  1. Navigate to any dashboard in your project
  2. Go to the Queries section
  3. Create a test query, for example:
SELECT 1 as test_value
  1. Click Run to execute the query

If the connection is working, you'll see the result. If there's an error, check the following:

  • The service account has the correct roles assigned
  • The BigQuery API is enabled in your Google Cloud project
  • The project_id in the JSON key matches the project containing your datasets

Security Model

Overscore is designed so that your BigQuery credentials never touch the browser:

  • Service account keys are stored encrypted on the server. They are never included in API responses or dashboard bundles.
  • Query execution happens server-side. The Overscore API receives a query request, authenticates the user, runs the query against BigQuery, and returns only the results.
  • Cached results are stored as Parquet files. Dashboards load these Parquet files into DuckDB-WASM for fast local access — no direct BigQuery connection from the browser.
  • API keys authenticate dashboard requests. Each deployed dashboard uses an API key (set via environment variable) to authorize data requests. The API key identifies which project and dashboard the request is for, but does not contain or expose BigQuery credentials.

This means even if someone inspects your deployed dashboard's JavaScript bundle, they will not find any database credentials.

Troubleshooting

"Permission denied" errors

Make sure the service account has both BigQuery Data Viewer and BigQuery Job User roles. If you granted Data Viewer at the dataset level, confirm you're querying the correct dataset.

"BigQuery API not enabled"

Go to the API Library in Google Cloud Console and enable the BigQuery API for your project.

"Invalid key" when uploading

Ensure you're uploading the original JSON file downloaded from Google Cloud. The file must be valid JSON with a type field set to "service_account".

Next Steps