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

# Import files from Google Cloud Storage into Mammoth

> Connect Mammoth to a Google Cloud Storage bucket with a service account JSON key, open a CSV, Excel or Parquet file, and collect new files on a schedule.

The Google Cloud Storage (GCS) connector opens a file from a bucket and saves it in Mammoth as a dataset. It signs in with a Google Cloud service account, with no OAuth popup. Open it from **Data Library** > **New dataset** > **Connectors** and search for **Google Cloud Storage**. Project Admins create the connection; Project Editors can start datasets from a connection the project already has. Which connectors you can add depends on your plan.

## What you can bring in from Google Cloud Storage

Files in any bucket the service account can see, of these types: `.txt`, `.csv`, `.tsv`, `.psv`, `.xls`, `.xlsx`, `.xlsm`, `.zip`, `.bz2`, `.gz`, `.tar`, `.7z`, `.parquet`, `.json`.

A spreadsheet file opens to its tabs.

## Before you connect Google Cloud Storage

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 for GCS

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, for example `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.

## Connect Google Cloud Storage to Mammoth

1. Go to the **Data Library**, click **New dataset**, and choose **Connectors**.
2. Search for **Google Cloud Storage** and click its tile. The connector workspace opens with the **Chat** connecting Google Cloud Storage.
3. Click **Upload service account file**, select the JSON key file, and connect.

If you already have a GCS connection, pick it under **Your connections** in the launcher instead. See [Connect a database or app](https://mammoth.io/docs/learn/get-data-in/connect-a-source/) for the shared steps.

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

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


## Open a file from your GCS bucket

1. In the left panel, open a bucket and browse to the file you want. A spreadsheet opens to its tabs.
2. Tick the columns you want. They gather in **Your table**.
3. If a file can't open in the panel yet, ask the agent in the **Chat** to import it.

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


## Save a GCS file as a dataset

1. Click **Save as dataset**.
2. Enter a **Dataset name** and pick the folder under **Save in**.
3. Click **Save**.

A dataset from a GCS file is saved once. Mammoth shows **Saved once. Scheduled refresh for files is coming.** A [Dataset Refresh](https://mammoth.io/docs/learn/automate/refresh-a-dataset/) automation can't re-read GCS files.

## Bring in new GCS files on a schedule

If your bucket receives new files regularly, such as daily exports named `orders_2024-01-15.csv`, use two automations:

1. A **File Collection** automation collects new files from the bucket into Mammoth on a schedule. See [What you can automate](https://mammoth.io/docs/learn/automate/).
2. A [Data Consolidation](https://mammoth.io/docs/learn/automate/consolidate/) automation adds the collected files to your dataset.

### Future pulls mode in the older import dialog

The older **Google Cloud Storage - New Dataset** dialog, which Mammoth still opens in some cases, shows a **Future pulls mode** list after you select a file:

| Option | What it does |
| --- | --- |
| **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. Choose the **Folder to pull from** and enter a **File pattern**. |

In a file pattern, put a date format inside `<>`. For the file `sftp_Tue-01-November-2022_daily.csv`, the pattern is `sftp_<dy>-<dd>-<mon>-<yyyy>_daily.csv`.

- Supported date formats: `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.
- The pattern must match the selected file name.

## Troubleshoot Google Cloud Storage connections

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| "Permission denied" | The service account can't list buckets | Grant it a role that includes `storage.buckets.list` and access to the bucket's objects. Check permissions in **GCS**, then the bucket, then **Permissions**. |
| "Invalid service account file. Please upload a valid JSON key file." | The file isn't a service account JSON key | Download a new key from **Keys** in Google Cloud Console and upload it |
| "Authentication failed. Please verify your service account JSON file." | Google rejected the key | Confirm the key still exists and the service account is enabled |
| "No buckets found for this service account." | The service account can't see any bucket | Give it access to the bucket |
| "No supported files found in bucket" | The bucket is empty or holds only unsupported types | Add files of a supported type (see above) |

## Related

- [Google BigQuery](https://mammoth.io/docs/learn/get-data-in/connectors/bigquery/): query warehouse tables with a service account.
- [Connect a database or app](https://mammoth.io/docs/learn/get-data-in/connect-a-source/): the shared connector workspace steps.
- [What you can automate](https://mammoth.io/docs/learn/automate/): set up a File Collection automation.
- [Combine incoming data](https://mammoth.io/docs/learn/automate/consolidate/): add collected files to one dataset.
- [Manage saved connections](https://mammoth.io/docs/learn/get-data-in/connections/): reuse or remove this connection.

---
Source: https://mammoth.io/docs/learn/get-data-in/connectors/google-cloud-storage.md · Updated: 2026-11-08