> For the complete documentation index, see [llms.txt](https://docs.rootcause.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rootcause.ai/data-connectors/google-cloud-storage.md).

# Google Cloud Storage

Connect RootCause to Google Cloud Storage to import files from your GCS buckets. This connector is currently in **Beta**.

***

### Prerequisites

Before connecting, ensure you have:

* Google Cloud project ID
* A service account with read access to the buckets and objects you want to import
* The service account's JSON key file (or its private key PEM and email)

***

### Setting Up the Connection

1. Navigate to **Sources** in your workspace and click **Import data**
2. In the Import Manager, find **Google Cloud Storage** and click **Setup**
3. Enter your connection details:

| Field                     | Description                                                                         | Example                                   |
| ------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------- |
| Project ID                | Google Cloud project ID                                                             | `my-project-123`                          |
| Service Account Email     | Service account email address                                                       | `service@project.iam.gserviceaccount.com` |
| Private Key               | Private key (PEM) from the service account JSON — or paste the entire JSON key file | `-----BEGIN PRIVATE KEY-----...`          |
| Default Bucket (Optional) | Bucket to use when imports don't specify one                                        | `my-data-bucket`                          |

If you paste the entire JSON key file into **Private Key**, the service account email is read from it automatically.

4. Click **Test Connection** to verify your credentials
5. Click **Save** to create the connector

***

### Importing Data

Once your connector is saved:

1. Click **Import Data** on the connector
2. Select a **Bucket** (RootCause lists the buckets your service account can see, or uses the default bucket)
3. Enter the **Object Path** within the bucket:
   * Specific file: `data/sales.parquet`
   * Directory prefix: `data/2024/`
   * Full GCS URI: `gs://bucket/data/`
4. Enable **Recursive** to include files in subdirectories
5. Select **Formats** to import (Parquet, CSV, JSON)

**Supported File Formats:**

| Format  | Description                                             |
| ------- | ------------------------------------------------------- |
| Parquet | Columnar storage format, recommended for large datasets |
| CSV     | Comma-separated values                                  |
| JSON    | Newline-delimited JSON (`.jsonl`, `.ndjson`)            |

***

### What Happens When You Import

1. RootCause connects to your GCS bucket
2. Objects matching your path and format criteria are listed
3. Files are downloaded and parsed
4. Multiple files are combined into a single dataset
5. Schema is automatically detected from the file content
6. Data is stored in your workspace's data lake

The imported dataset becomes available for use in [Data Views](/user-guide/data-views.md) and [Ontology](/core-technologies/ontology.md) mapping.

***

### Live Data Sync

You can configure automatic syncing to keep your dataset current:

* **Manual** – Only sync when you click "Sync Now"
* **Hourly** – Refresh every hour
* **Daily** – Refresh once per day
* **Weekly** – Refresh once per week
* **Monthly** – Refresh once per month

When a sync runs, the GCS path is re-scanned and data is refreshed.

***

### Service Account Permissions

Create a dedicated service account for RootCause with minimum required permissions:

1. In the Google Cloud Console, go to **IAM & Admin** → **Service Accounts** → **Create Service Account**
2. Grant the **Storage Object Viewer** role (`roles/storage.objectViewer`) on the buckets you want to import from
3. If you don't set a default bucket, the connector lists buckets in the project — this additionally requires the `storage.buckets.list` permission at the project level
4. Create a key for the service account (**Keys** → **Add key** → **JSON**) and paste it into the connector

***

### Troubleshooting

**Access Denied / 403**

* Verify the service account has the Storage Object Viewer role on the bucket
* Check that the project ID matches the project that owns the service account
* Ensure the key hasn't been deleted or disabled

**Bucket not found**

* Verify the bucket name is spelled correctly
* Check that the bucket belongs to a project the service account can access

**No files found**

* Verify the object path prefix is correct
* Check that files exist in the specified location
* Ensure the selected formats match your file types

**Invalid credentials**

* Paste the entire service account JSON key file, or the private key PEM together with the service account email
* Check for missing line breaks or truncation in the pasted key