Google Cloud Storage setup guide

Follow these steps to connect files in a GCS bucket to Auxia. Setup takes about 10 minutes.

Prerequisites

Access to the Auxia Console with permission to create connections
A GCS bucket holding your data, laid out as described in File source requirements
Permission to change IAM on that bucket (storage.buckets.setIamPolicy, for example through the Storage Admin role)

Setup instructions

Start a new connection

In the Auxia Console, go to Configuration → Connections, click Add New Connection, and choose Google Cloud Storage. Enter your bucket name — 3 to 63 lowercase letters, numbers, dots, or hyphens, without gs://.The wizard first asks you to confirm four statements. They’re the contract your sync relies on:

Statement	What it means
Files are Parquet, CSV, or newline-delimited JSON	CSV must have a header row and be comma-separated
You know whether files land in date folders	Each day in its own folder (such as `dt=2026-10-02`), or everything in one folder
Data is append-only	New data is written as new files, never by rewriting existing ones
You can edit permissions	In the Google Cloud project that owns the bucket

Grant Auxia read access

Click Generate access command. Under Run this in your Google Cloud project, the wizard shows two commands that grant the service account two read-only roles on the bucket. Both are needed:

Role	Why
Storage Object Viewer (`roles/storage.objectViewer`)	Lists and reads your files
Storage Legacy Bucket Reader (`roles/storage.legacyBucketReader`)	Lets the transfer service look up the bucket’s location before copying

With only Storage Object Viewer, Check Access passes but the first sync fails with “Failed to obtain the location of the GCS bucket”. Grant both roles.

Always copy the commands from the wizard. The service account is resolved from your Auxia project. Never type or edit it by hand — a mistyped identity can grant access to a different Auxia project.

Command line
Google Cloud console

The commands have this shape, with your bucket and service account filled in:

gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET \
  --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
  --role=roles/storage.objectViewer

gcloud storage buckets add-iam-policy-binding gs://YOUR_BUCKET \
  --member=serviceAccount:SERVICE_ACCOUNT_EMAIL \
  --role=roles/storage.legacyBucketReader

add-iam-policy-binding adds to the bucket’s existing permissions; it doesn’t replace them. No local gcloud? Run the commands in Google Cloud Shell.

Then click Check Access. Auxia lists the bucket and confirms: “Access confirmed. We listed your bucket and can read it, N entries visible.” Access is reported per permission, so if a check fails you’ll see exactly which permission is missing.

IAM changes can take a few minutes to propagate. If the check fails right after you grant access, wait and retry.

Configure your tables

Choose what to sync

Browse your bucket and tick the folders that are tables — one folder per table. Folders can sit several levels deep, the way warehouse exports usually do; type a prefix to jump straight to one instead of opening down to it.

Select the folder for each table, not a parent folder that holds several tables. See One folder per table.

Folder status	Meaning
Ready	Auxia can read this folder
Issue detected	Readable, but something needs attention — the row explains what
Incompatible	Can’t be ingested as it stands

A folder that’s already set up is marked as ingested and can’t be selected again. If one table’s user ID comes from a lookup table (see the next step), select the lookup table’s folder now too.Click Continue with Mapping.

Map

Auxia reads the selected folders and works out what each table holds.Check what was detected. For each table, confirm the file format, the date partitioning, and the column schema Auxia read. This is the most important review in the wizard — compact date folders such as dt=20261002 are the most likely to be misread. Each table also shows a confidence level:

Confidence	What to do
High — recognized schema	Review and continue
Medium — “Looks like … please check”	Verify the table type and mapping
Low — not a recognized schema	Map the columns yourself

Map Primary User ID. Pick the column that identifies a person across your tables. See Understanding the primary user ID.Match Fields to Auxia Schema. Map user ID, event name, and event timestamp on event tables. Attribute tables have no event name; map the user attributes and their update timestamp instead. If a table has no event-name column, type a name and Auxia applies it to every row. Resolve anything flagged — for example Schema type needed (say whether the table holds events or user attributes) or No timestamp.Tables with no user ID. Device, session, or order events often carry only a device or session key, with a separate lookup table mapping that key to the user. When the wizard asks how to resolve the user ID, point it at the lookup table on the shared key, and choose the column that resolves to the user ID.

The lookup table must be selected in the same setup as the events table that joins to it.
A lookup table’s timestamp usually records when the mapping was made, not when an event happened. Don’t map it as the event timestamp.

Filter rows (optional)

Auxia ingests every row of every table unless you add a rule to leave some out. Build conditions on any column and group them with AND / OR.Your files are still copied in full: a filter decides what this source reads into Auxia, not what leaves your bucket.

Schedule

File sources check for new data every day. Tell Auxia how your date folders are named so each run reads the right day:

Partition folder — the prefix before = in your folder names, such as dt. Prefix only: no =, /, or spaces.
Date format — read from your folder names where possible (“Read from your folder names, such as …”). If the names read both ways (for example 03-04-2026), you must confirm the format before continuing. If Auxia can’t read a pattern, pick the one that matches.

If a table has no date folders, the whole folder is copied each run. Supported date formats →

Review and start ingestion

Check each table’s Table name in Auxia, type, columns, schedule, and row filter. Table names may use letters, digits, and underscores, and must not start with a digit or repeat another table’s name.Click Start ingestion. Auxia creates one configuration per table, sets up the copy, and switches ingestion on — this can take a few minutes. A day’s data appears the morning after the first daily run. Monitoring with Data Health →Tables that are already set up are skipped (nothing is created for them), and so is a table whose folder another table already reads — two tables over the same files would ingest everything twice.

If you see “Your configurations were created but Auxia couldn’t switch them on”, contact Auxia before trying again. Retrying creates duplicate configurations.

​Prerequisites

​Setup instructions

​Configure your tables

​Related articles

Prerequisites

Setup instructions

Configure your tables

Related articles