> AI agents: this is one page from Mammoth Analytics documentation. The index of all pages as Markdown is https://docs.mammoth.io/llms.txt. Append `.md` to any docs URL, or send `Accept: text/markdown`, to get Markdown.

# Google BigQuery connector

> Connect Mammoth to Google BigQuery with a service account JSON key: required roles, how to connect, and how to import a table or query as a dataset.

The Google BigQuery connector imports data from your BigQuery data warehouse into Mammoth as a dataset. Authentication uses a Google Cloud service account key file—no OAuth sign-in is required.

## Before you start

You need:

- A Google Cloud project with BigQuery enabled
- A service account with the **BigQuery Data Viewer** role (or equivalent)
- The service account's JSON key file downloaded to your computer

### Create a BigQuery service account

1. In the [Google Cloud Console](https://console.cloud.google.com), go to **IAM & Admin → Service Accounts**
2. Click **Create Service Account**
3. Give it a name (e.g., `mammoth-bigquery`)
4. Grant the role **BigQuery Data Viewer** (for read access) and **BigQuery Job User** (to run queries)
5. Click **Done**
6. Open the service account, go to **Keys**, click **Add Key → Create new key**, and select **JSON**
7. Save the downloaded JSON file—you'll upload it to Mammoth in the next step

## Step 1: Select the BigQuery connector

1. In Mammoth, go to **Data Library** and click **+ New Dataset**
2. Select **Connectors**
3. Search for **BigQuery**
4. Click the **Google BigQuery** tile

## Step 2: Create a connection

Click **New Connection**. BigQuery uses a service account file rather than username/password.

![Google BigQuery New Connection dialog with the Upload service account file button](https://docs.mammoth.io/api/v1/images/20260615_094036_Bigquery_screen_11.jpg)

1. Click **Upload service account file**
2. Select the JSON key file you downloaded from Google Cloud Console

![BigQuery New Connection dialog with a service account JSON file attached and the Connect button enabled](https://docs.mammoth.io/api/v1/images/20260615_094058_Bigquery_screen_2_uploaded_json.png1.jpg)

3. Mammoth reads the credentials from the file
4. Click **Connect** to validate and save the connection

> **Keep your key file secure.**
> The service account JSON key grants access to your BigQuery project. Store it securely and do not share it. If you need to revoke access, delete the key in Google Cloud Console under **IAM & Admin → Service Accounts → {your account} → Keys**.

## Step 3: Select a BigQuery dataset and query your data

In BigQuery, data is organized into **datasets** (equivalent to schemas). After connecting:

- Your BigQuery datasets appear as profiles, named `project - dataset`, under your connection in **Existing Connections**
- Click a profile to open it and see its tables in the **List of tables** panel
- Click a table to load a `SELECT *` query for it and its preview

![BigQuery Existing Connections list showing the service account and its project - dataset profiles](https://docs.mammoth.io/api/v1/images/20260615_094122_Bigquery_screen_3_profiles1.jpg)

### Write a custom BigQuery query

```sql
SELECT order_id, customer_id, amount, created_at
FROM `my-project.analytics.orders`
WHERE DATE(created_at) >= DATE_SUB(CURRENT_DATE(), INTERVAL 90 DAY)
  AND status = 'completed'
```

BigQuery uses backtick-quoted fully qualified table names: `project.dataset.table`.

See [Understanding data preview & query](https://docs.mammoth.io/learn/connectors/understanding-data-preview-query/) for a full guide.

## Step 4: Save the BigQuery dataset

1. Enter a **dataset name** in the **Save table as** field (e.g., `Hokulani_Data`)
2. Check the **Update Method** (the default is **Replace all data**). To change it, click the edit icon, pick an option, and click **Save changes**:
   - **Replace all data**—Replaces all existing data
   - **Add new data**—Adds new data based on a unique sequential column
   - **Replace with new data**—Replaces existing data with new data based on a unique sequential column
   For **Add new data** and **Replace with new data**, also choose a **Key column**—a numeric or date column with incrementing values, such as an ID or a date.
3. Click **Save as dataset**. When the dataset is saved, click **Done**

![Google BigQuery New Dataset dialog with table list, SELECT query, data preview, Save table as, and Update Method](https://docs.mammoth.io/api/v1/images/20260615_094153_Bigquery_screen_4_dataset1.jpg)

After saving, your dataset appears in the Data Library.

![Hokulani_Data dataset details showing its BigQuery query and a Google BigQuery batch with state Active](https://docs.mammoth.io/api/v1/images/20260615_094213_Screenshot2026-05-211231511.jpg)

To refresh data from BigQuery, create a **Dataset Refresh** automation, which you can run manually or on a schedule.

## Troubleshoot BigQuery connections

### Permission denied errors

- Confirm the service account has both **BigQuery Data Viewer** and **BigQuery Job User** roles
- For table-level access instead of project-level, grant the roles directly on the BigQuery dataset in **BigQuery → {dataset} → Sharing → Permissions**

### Project not visible

- The service account must belong to the same Google Cloud project, or be granted access cross-project through IAM

---
Source: https://docs.mammoth.io/learn/connectors/bigquery.md · Updated: 2026-10-13