Connect BigQuery

Prerequisites

• You have access to the Google Cloud project that contains the BigQuery data.
• You can create a service account and key, or you have someone with those permissions.
• You have the BigQuery Project ID.
• You will use a dedicated service account for Skoot (recommended).

Set Shared Variables (Run Once)

Run this once in your terminal session and reuse these variables in all CLI steps below:

export PROJECT_ID="your-project-id"
export SA_NAME="skoot-readonly"
export SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"
export KEY_FILE="./skoot-bigquery-key.json"

Choose the Access Scope

Skoot supports two practical BigQuery read scopes:

1. Project-wide (broadest)
   • Grant read access at project level.
   • Easiest setup, least restrictive.
2. Dataset-level (recommended)
   • Grant read access only on selected datasets.
   • Best balance of least-privilege and reliable schema discovery in Skoot.
   • To keep discovery limited, do not grant BigQuery read roles at project level.

Step 1 — Create a Service Account

Option A: gcloud CLI

gcloud iam service-accounts create "${SA_NAME}" \
  --project "${PROJECT_ID}" \
  --display-name "Skoot BigQuery Readonly"

Service account email format:

${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

Option B: GCP Console

1. Go to IAM & Admin → Service Accounts.
2. Click Create Service Account.
3. Name it skoot-readonly (or your naming convention).
4. Click Create and Continue.
5. Skip role assignment in this wizard (we assign explicit roles below), then finish.

Step 2 — Grant Job Execution Permission (Required)

Skoot runs query jobs, so the service account needs BigQuery Job User at the project level.

Option A: gcloud CLI

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/bigquery.jobUser"

Option B: GCP Console

1. Go to IAM & Admin → IAM.
2. Click Grant Access.
3. Principal: the service account email.
4. Role: BigQuery Job User.
5. Save.

Step 3 — Grant Read-Only Data Access (Pick Scope)

Use one of the following scope patterns.

Scope A: Project-wide read access

gcloud CLI

gcloud projects add-iam-policy-binding "${PROJECT_ID}" \
  --member="serviceAccount:${SA_EMAIL}" \
  --role="roles/bigquery.dataViewer"

GCP Console

1. Go to IAM & Admin → IAM.
2. Edit the service account principal.
3. Add role BigQuery Data Viewer.
4. Save.

Scope B: Dataset-level read access (recommended)

Repeat for each dataset you want Skoot to access.

To ensure Skoot discovers only the specified dataset(s):

1. Use a dedicated service account for Skoot.
2. Keep only roles/bigquery.jobUser at project level.
3. Do not grant roles/bigquery.dataViewer or roles/bigquery.metadataViewer at project level.
4. Grant roles/bigquery.dataViewer only on the allowed dataset(s).

BigQuery SQL (GoogleSQL via bq)

DATASET_ID="dataset_name"
 
bq --project_id="${PROJECT_ID}" query --use_legacy_sql=false \
"GRANT \`roles/bigquery.dataViewer\`
 ON SCHEMA \`${PROJECT_ID}.${DATASET_ID}\`
 TO \"serviceAccount:${SA_EMAIL}\";"

GCP Console

1. Open BigQuery Studio.
2. In Explorer, select the dataset.
3. Open dataset Sharing / Permissions.
4. Add principal (service account email).
5. Role: BigQuery Data Viewer.
6. Save.

Step 4 — Create Service Account JSON Key

If your org policy blocks key creation, ask your cloud admin to allow it for this project.

Option A: gcloud CLI

gcloud iam service-accounts keys create "${KEY_FILE}" \
  --iam-account="${SA_EMAIL}" \
  --project="${PROJECT_ID}"

Option B: GCP Console

1. Go to IAM & Admin → Service Accounts.
2. Open the service account.
3. Go to Keys tab.
4. Click Add Key → Create new key.
5. Select JSON, then create and download.
6. Store the file securely.

Step 5 — Verify Before Connecting to Skoot

Set the key locally, then run smoke checks:

export GOOGLE_APPLICATION_CREDENTIALS="${KEY_FILE}"
bq --project_id="${PROJECT_ID}" query --use_legacy_sql=false 'SELECT 1'
bq --project_id="${PROJECT_ID}" query --use_legacy_sql=false \
"SELECT table_name FROM \`${PROJECT_ID}.dataset_name.INFORMATION_SCHEMA.TABLES\` LIMIT 5"

Optional visibility check (confirm only expected datasets are listed):

bq --project_id="${PROJECT_ID}" ls

Connect in Skoot App

After BigQuery setup is complete:

1. Click BigQuery in Available Data Sources section BigQuery Connection .
2. Fill these fields exactly:
   • Connection Name
   • Project ID
   • Service Account JSON
   • Query Timeout (ms) (minimum 1000)
3. Save the connection.
4. Confirm status is Connected.

Common Errors and Fixes

• Access Denied ... bigquery.jobs.create
  • Missing roles/bigquery.jobUser on project.
• Access Denied ... bigquery.tables.getData
  • Missing roles/bigquery.dataViewer on target datasets.
• Datasets or tables not visible in Skoot
  • Scope is too narrow; add roles/bigquery.dataViewer on required dataset(s).
• Unexpected extra datasets visible in Skoot
  • Keep only dataset-level roles/bigquery.dataViewer for this service account.
• Service account key creation is disabled
  • Org policy is blocking key creation; request exemption for this project.
• Invalid BigQuery service account JSON
  • Paste the full JSON key content, including client_email and private_key.

Related Pages

• Data Sources Overview
• 15-Minute Quickstart