---
title: GCS bucket
description: Connect GCS bucket, understand its sync behavior, and query every table and column it writes.
species: reference
---
# GCS bucket

Connect GCS bucket with a bucket path plus the target schema and file options. The source writes tables discovered from JSON, CSV, or Parquet files under `titan.{schema_name}`.
## Connect GCS bucket

1. Open **Apps**, choose **Connect app**, and select **GCS bucket**.
2. Enter a bucket path plus the target schema and file options.
3. Review the tables, then save the source.
4. Watch **Sync history** until the first run completes.

Credentials are stored as secrets. They never become lake columns or appear in query results.

## Sync behavior

Each discovered file group becomes a table. You choose the id column, delimiter, optional file glob, and optional partition sort column. Use a custom glob such as `**/*.gz` when compressed files do not have the format's normal extension. For second-level partitioned sources, an incremental sync also revisits the partition immediately before its cursor. This bounded overlap captures objects that arrive after the producer has already opened its next lexicographic partition. Rows remain idempotent when the configured id column is stable.

A new source syncs when you connect it and then follows its schedule. The default recurring interval is 4 hours. An interrupted run keeps its completed progress and retries safely.

Every lake table also has the [system columns](/docs/concepts/your-lake#the-system-columns) `_synced_at` and `_deleted`; the column reference below lists source columns only.

## Table reference

Supernova discovers this reference from the connected account. Supernova reads headers and samples from the configured bucket prefix. The resulting column reference depends on those files.

Open **Apps → GCS bucket → Tables** after the first discovery run to see every exact table name, column name, type, and sync selection. Dynamic fields cannot be listed truthfully before an account is connected.

## Deletes and history

Rows are merged by their source key. When the source can prove that a row was deleted, Supernova keeps the row and sets `_deleted` so queries can choose whether to include history. Filter current-state queries with `where not _deleted`.