> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zwiron.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Cloud Storage Connector

> Read files from or write files to Google Cloud Storage in Zwiron pipelines.

Google Cloud Storage is object storage on Google Cloud. Zwiron can read files from GCS (as a source) or write files to GCS (as a destination). Supported formats include CSV, JSON, JSONL, Parquet, TSV, Excel, Avro, XML, and YAML.

Setup is the same shape as [Amazon S3](/connectors/files/s3): bucket + optional prefix + credentials.

***

## Supported sync modes

| As source | Full Refresh | Incremental                            | CDC |
| --------- | ------------ | -------------------------------------- | --- |
|           | ✅            | N/A (no native date-filtered list API) | N/A |

| As destination | Write modes       |
| -------------- | ----------------- |
|                | Append, Overwrite |

***

## Connection details

| Field                | Required         | Description                                                   |
| -------------------- | ---------------- | ------------------------------------------------------------- |
| Bucket               | Yes              | GCS bucket name                                               |
| Project ID           | Yes              | Google Cloud project ID                                       |
| Auth method          | Yes              | `json` (paste key — hosted UI) or `file` (path on agent host) |
| Service account JSON | When auth = json | Full contents of the service account JSON key                 |
| Service account file | When auth = file | Absolute path to the JSON key on the agent machine            |
| Path prefix          | No               | Optional prefix to scope reads/writes (e.g. `data/exports/`)  |
| Emulator host        | No               | Leave blank in production                                     |

***

## IAM permissions

Grant the connecting principal:

### For source (read-only)

* `storage.objects.list`
* `storage.objects.get`
* `storage.buckets.get`

Equivalent predefined role: `roles/storage.objectViewer` plus `storage.buckets.get` (or `roles/storage.legacyBucketReader`).

### For destination (read-write)

* `storage.objects.list`
* `storage.objects.get`
* `storage.objects.create`
* `storage.objects.delete`
* `storage.buckets.get`

Equivalent predefined role: `roles/storage.objectAdmin`.

***

## Reading from GCS (source)

Zwiron lists objects in the configured bucket and prefix. Each recognized file becomes a stream. Format is auto-detected from the extension unless you set **Format**.

### Supported formats

| Format                | Notes                              |
| --------------------- | ---------------------------------- |
| CSV / TSV             | Configurable delimiter, header row |
| JSON / JSONL / NDJSON | JSON array or one object per line  |
| Parquet               | Schema is read from file metadata  |
| Excel (XLSX)          | First sheet                        |
| Avro / XML / YAML     | Shared file codec registry         |

***

## Writing to GCS (destination)

Zwiron writes one object per stream. Overwrite replaces the object for that stream; append writes an additional object. Files are named from the stream name and format.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Access Denied">
    Confirm the service account (or ADC identity) has `storage.objects.list` and `storage.buckets.get` on the bucket. Object-level roles alone are not enough to list.
  </Accordion>

  <Accordion title="Files not being detected">
    Check the path prefix — it must match exactly. GCS object names are case-sensitive. Also ensure the file extension matches the configured format filter.
  </Accordion>

  <Accordion title="Using a GCS emulator">
    Set **Emulator host** to `host:port` (no scheme), for example `localhost:4443`. Production connections should leave this blank.
  </Accordion>
</AccordionGroup>