> 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 Cloud Storage connector

> Connect Mammoth to Google Cloud Storage with a service account JSON key, pick a file from a bucket, and refresh it by name pattern or as the same file.

The Google Cloud Storage (GCS) connector imports files from your GCS bucket into Mammoth as a dataset. Authentication uses a Google Cloud service account—no OAuth popup required. Supports a wide range of file formats including CSV, Excel, Parquet, JSON, compressed archives, and more.

## Before you start

You need:

- A GCS bucket with the files you want to import
- A Google Cloud service account that can list buckets (the `storage.buckets.list` permission) and read the objects in your bucket
- The service account's JSON key file downloaded to your computer

### Create a Google Cloud service account

1. In [Google Cloud Console](https://console.cloud.google.com), go to **IAM & Admin → Service Accounts**
2. Click **Create Service Account** and give it a name (e.g., `mammoth-gcs`)
3. Grant a role that includes `storage.buckets.list` and read access to the bucket's objects
4. Under **Keys**, click **Add Key → Create new key → JSON** and download the file

## Step 1: Select the Google Cloud Storage connector

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

## Step 2: Create a connection

Click **New Connection**. GCS uses a service account file for authentication.

![Google Cloud Storage New Connection dialog with a service account file attached and the Connect button enabled](https://docs.mammoth.io/api/v1/images/20260826_090841_googleCloudStorage-newConnection.png)

1. Click **Upload service account file**
2. Select the JSON key file you downloaded from Google Cloud Console
3. Mammoth reads the credentials from the file
4. Click **Connect** to validate and save the connection

![Google Cloud Storage Existing Connections list showing one service account connection and the New Connection button](https://docs.mammoth.io/api/v1/images/20260826_090948_GoogleCloudStorage-CreatedConneciton.png)

## Step 3: Select your Google Cloud Storage file

After connecting, select the connection under **Existing Connections**. Mammoth lists your buckets as **Profile** entries; click a bucket, then browse the file tree and select the file you want to import.

### Supported Google Cloud Storage file formats

`.txt` · `.csv` · `.tsv` · `.psv` · `.xls` · `.xlsx` · `.zip` · `.bz2` · `.gz` · `.tar` · `.7z` · `.parquet` · `.json`

![Google Cloud Storage New Dataset dialog with file tree, Exact Sheet name, Future pulls mode, and Create new dataset](https://docs.mammoth.io/api/v1/images/20260826_091010_GoogleCloudeStorage-NewDS.png)

### Choose a future pulls mode

After you select a file, a **Future pulls mode** list appears:

- **Pull same file**—Every refresh re-reads the file you selected
- **Pull next file based on name pattern**—Available only when a single file is selected. Every refresh looks for the next file that matches a date pattern in the file name. Choose the **Folder to pull from** and enter a **File pattern**. For example, for the file `sftp_Tue-01-November-2022_daily.csv` the pattern is `sftp_<dy>-<dd>-<mon>-<yyyy>_daily.csv`

In a file pattern, put a date format inside `<>`. The supported formats are `dd`, `mm`, `yyyy`, `yy`, `month`, `mon`, `day`, `dy`, `hh`, `mi`, and `ss`, in full lower case, upper case, or capitalized. The selected file name must contain at least one date format, and the pattern must match the selected file name.

If the file is an Excel workbook (`.xls`/`.xlsx`), also enter the **Exact Sheet name** to import.

## Step 4: Create the Google Cloud Storage dataset

Click **Create new dataset**. Mammoth does not ask you to choose an update method for this connector.

## Keep Google Cloud Storage data up to date

Set up a **Dataset Refresh** automation to re-import the file from GCS on a schedule.

If your GCS bucket receives new files regularly (for example, daily export files named `orders_2024-01-15.csv`), choose **Pull next file based on name pattern** when you create the dataset so each refresh picks up the next matching file.

## Troubleshoot Google Cloud Storage connections

### Permission denied

- Mammoth shows "Permission denied" when the service account can't list buckets. Grant it a role that includes `storage.buckets.list` and access to the target bucket's objects
- Check permissions in **GCS → {bucket} → Permissions**

### Invalid service account file

- "Invalid service account file. Please upload a valid JSON key file." means the uploaded file isn't a service account JSON key. Download a new key from **Keys** in Google Cloud Console and upload it again
- "Authentication failed. Please verify your service account JSON file." means Google rejected the key. Confirm the key still exists and the service account is enabled

### No buckets or files appear

- "No buckets found for this service account." means the service account can't see any bucket
- "No supported files found in bucket" means the bucket is empty or contains only file types outside the supported list above

---
Source: https://docs.mammoth.io/learn/connectors/google-cloud-storage-connector.md · Updated: 2026-10-13