/setup-bigquery.en

description: "Lesson command"
duration: "~15 min"
prerequisites: ["Have a Google account", "Browser available"]
level: "beginner"
tags: ["setup", "bigquery", "gcp", "gcloud"]
nonInteractiveMode: incompatible

BigQuery / GCP Authentication Setup

Step 0: Check Setup Progress

**What the AI auto-runs:** 1. Run `uv run python tools/setup_progress.py show --current setup-bigquery` to display progress 2. Auto-detect existing gcloud CLI installation:

• Run `gcloud --version`
• If gcloud CLI is already installed and authenticated, skip to Step 4 (connection test)
• If not installed, start from Step 1

What You'll Do in This Session

| Item | Details | |------|---------| | Goal | Install gcloud CLI, authenticate with Application Default Credentials (ADC), and run SQL queries in BigQuery | | Duration | ~15 minutes | | Prerequisites | Have a Google account and a browser available | | Skill Level | A few CLI commands + browser authentication (AI guides you through the steps) |

**Session flow:** 1. Install gcloud CLI (AI guides you through the steps) 2. Log in with your Google account (browser opens automatically) 3. Set up a GCP project (AI guides you) 4. Set up Application Default Credentials (one command) 5. BigQuery connection test (AI runs automatically)

> **About costs**: BigQuery offers up to 1 TB of free queries per month. The training uses public datasets, so costs are virtually zero. Google will notify you before exceeding the free tier. > > **Hint**: If the AI's response stops midway, type "please continue" or "it stopped" to resume.

---

Readiness Check

**AskQuestion configuration:**

{
  "title": "Pre-session confirmation",
  "questions": [{
    "id": "readiness",
    "prompt": "Are you ready?",
    "options": [
      {"id": "ready", "label": "Ready! Let's start"},
      {"id": "check_prereq", "label": "I want to check the prerequisites"},
      {"id": "different_lesson", "label": "I want to go to a different lesson"}
    ]
  }]
}

(ready -> Proceed to Step 1) (check_prereq -> Guide: "If you can log in to a browser with a Google account, you're ready. BigQuery is free for up to 1 TB of queries per month, so usage during the training is virtually free.") (different_lesson -> Display module list)

---

Step 1: Install gcloud CLI

**What the AI does:** 1. Auto-detect the OS (Mac / Windows / Linux) 2. Run `gcloud --version` to check if it's already installed 3. If already installed, skip to Step 2 4. If not installed, guide the user through OS-specific installation steps

**Mac (Homebrew recommended):**

brew install google-cloud-sdk

**Mac (if Homebrew is unavailable) / Windows:** Download the installer via browser:

# Mac:
open https://cloud.google.com/sdk/docs/install
# Windows:
start https://cloud.google.com/sdk/docs/install

**Post-installation verification:**

gcloud --version

**AskQuestion configuration:**

{
  "title": "Step 1: gcloud CLI Installation",
  "questions": [{
    "id": "install_status",
    "prompt": "Please tell us the status of your gcloud CLI installation:",
    "options": [
      {"id": "installed", "label": "Installed (or already had it installed)"},
      {"id": "homebrew_issue", "label": "Can't use Homebrew (Mac)"},
      {"id": "windows_help", "label": "I need help with Windows instructions"},
      {"id": "install_error", "label": "I got an error during installation"}
    ]
  }]
}

(installed -> Verify with `gcloud --version`, then proceed to Step 2) (homebrew_issue -> Guide: "Open https://cloud.google.com/sdk/docs/install in your browser and download the macOS installer. Extract the downloaded file and run ./install.sh to install.") (windows_help -> Guide: "Open https://cloud.google.com/sdk/docs/install in your browser and download the Windows installer (.exe). Double-click the downloaded file and follow the on-screen instructions. After installation, open a new WSL terminal (Ubuntu).") (install_error -> Check the error message and identify the cause. If PATH is not configured, guide user to run `source ~/.zshrc` or open a new terminal)

---

Step 2: GCP Project Setup

**What the AI does:** 1. Run `gcloud auth login` to start Google authentication in the browser 2. The browser opens automatically, prompting you to log in with your Google account

gcloud auth login

**Browser authentication instructions for the user:**

The browser will open automatically. Follow these steps to authenticate:

┌─────────────────────────────────────────────────────────────┐
│ 1. Select your Google account and log in via browser        │
│ 2. "Google Cloud SDK is requesting access"                  │
│    → Click "Allow"                                          │
│ 3. When "Authentication complete" appears, close the browser│
│ 4. Return to the terminal to see the success message        │
└─────────────────────────────────────────────────────────────┘

**After authentication, set up the project:**

# List existing projects
gcloud projects list

# Set the project (replace PROJECT_ID with your actual ID)
gcloud config set project PROJECT_ID

**AskQuestion configuration:**

{
  "title": "Step 2: GCP Project Setup",
  "questions": [{
    "id": "auth_status",
    "prompt": "Did you complete the Google account authentication in the browser?",
    "options": [
      {"id": "auth_done", "label": "Authentication complete!"},
      {"id": "browser_not_open", "label": "The browser didn't open"},
      {"id": "auth_denied", "label": "I got an error on the authentication screen"},
      {"id": "no_project", "label": "I don't have a GCP project (I want to create one)"}
    ]
  }]
}

(auth_done -> Display the project list with `gcloud projects list`. If an existing project is available, guide user to run `gcloud config set project PROJECT_ID` and proceed to Step 3) (browser_not_open -> Guide: "Copy the URL displayed in the terminal and paste it into your brows