Connecting Google Cloud Storage on Clarisights

Google Cloud Storage (GCS) is a read-only object-store connector. Use it to land CSV, CSV.GZ, or Parquet files in a bucket and have Clarisights pick them up as a custom data source for reporting.

At a glance

Connector type	Object store (read-only)
Authentication	Service account / IAM grant
Permissions needed	Storage Object Viewer on the bucket
File formats	CSV, CSV.GZ, Parquet
Refresh cadence	Set per pipeline
Limited rollout	No

Authentication options

Clarisights reads from your bucket using a managed Google service account. There are no API keys or OAuth flows to manage on your side: you grant our service account IAM access to the bucket (or a path prefix within it), and we read from there.

• IAM grant to a Clarisights-managed service account: grant Storage Object Viewer at the bucket or prefix level. We will share the service account email during onboarding.

Setting up the connection

Step 1: Identify or create the bucket

In the Google Cloud Console, choose an existing bucket or create a new one to hold the files you want Clarisights to read. Decide on a path or prefix that will hold the dataset (for example gs://my-bucket/clarisights/orders/).

Step 2: Grant access to the Clarisights service account

Your Clarisights contact will share a service account email (it ends in .gserviceaccount.com). In the Cloud Console, open the bucket, go to Permissions, and grant that service account the Storage Object Viewer role. You can scope the grant to the whole bucket or to a prefix using IAM Conditions.

For steps to grant a principal a role on a bucket from the Permissions tab, see Google Cloud's guide: Set and manage IAM policies on buckets.

⚠ Common error: "Access denied" or HTTP 403 when Clarisights tries to read the bucket → the service account is missing the Storage Object Viewer role on the bucket or prefix → re-check the IAM binding on the bucket.

Step 3: Share the connection details with Clarisights

Send your Clarisights contact the bucket name, the path or prefix, and the file format (CSV, CSV.GZ, or Parquet). We will configure the pipeline and confirm when the first read succeeds.

⚠ Common error: "Object not found" or empty reads → the path or prefix is wrong, or files are nested under a deeper folder than configured → verify the exact gs://<bucket>/<prefix>/ URI in the Cloud Console and resend it.

Connection details exchange

You provide	Clarisights provides
Bucket name (e.g. my-bucket)	Service account email to grant access to
File path or prefix (e.g. clarisights/orders/) (may include <year>, <month>, <day_of_month> placeholders)	Confirmation once the first read succeeds
File format (CSV, CSV.GZ, or Parquet)	Pipeline configuration and refresh cadence
IAM grant of Storage Object Viewer on the bucket or prefix

What we read

• Supported formats: CSV, gzip-compressed CSV (.csv.gz), and Parquet.

• CSV header convention: the first row of every CSV file is treated as the header. Column names in that row become the field names in Clarisights.

• Multiple files: every file the path matches is read as part of one dataset and the rows are added together. Reading a folder or a pattern of files is set up by Clarisights: contact your Clarisights CSM. In a pattern, * matches any characters within one folder level, for example clarisights/orders/*.csv. New files that match are picked up on the next refresh. If no file matches the path, the run fails.

Path date placeholders

If your data is laid out by date (a common pattern for daily exports), the file path or prefix can include date placeholders that Clarisights resolves at pull time using the channel's configured timezone. This means you configure the path once, and each scheduled run reads the folder for the appropriate date automatically.

Supported tokens:

• <year>: 4-digit year (e.g. 2026)

• <month>: 2-digit month (e.g. 04)

• <day_of_month>: 2-digit day (e.g. 25)

• *::<today-Ndays>: changes which day the placeholders resolve to. Without it, placeholders resolve to yesterday's date. Write it directly after the placeholders, in the same path segment (no slash in between), for example <day_of_month>*::<today-2days> for two days ago, or <day_of_month>*::<today-0days> for today.

Unpadded variants are also available: <year_small> (for example 26), <month_small> (for example 4), and <day_of_month_small> (for example 5).

Example: if your daily exports land at gs://my-bucket/exports/2026/04/25/orders.csv, configure the path as exports/<year>/<month>/<day_of_month>/orders.csv. On each run, Clarisights substitutes yesterday's date (in the channel's timezone) and reads that day's file. To read the current day's file instead, use exports/<year>/<month>/<day_of_month>*::<today-0days>/orders.csv.

Connector specifics

• Storage class matters: Standard and Nearline buckets read with no extra latency. Coldline and Archive objects have a retrieval lag and incur additional retrieval fees on the Google side, so we recommend Standard or Nearline for actively-refreshed datasets.

• Schema must match across files in a prefix: when multiple files sit under one prefix, they are read as a single dataset. CSV columns are matched by position, using the header of one of the files, so every file must have the same columns in the same order. A file with its columns in a different order doesn't fail: its values load into the wrong columns without an error. If your files' columns can differ, contact your Clarisights CSM to set up matching by column name.

• Path conventions: files at gs://<bucket>/<prefix>/... are read as one logical dataset. Use separate prefixes for separate datasets rather than mixing them in one folder.

Limitations & known constraints

• Read-only connector: Clarisights does not write back to your bucket.

• Only CSV, CSV.GZ, and Parquet are supported. Other formats (JSON, Avro, ORC, Excel) are not read.

• All CSV files that the path matches must have the same columns in the same order, unless Clarisights has set up matching by column name for the source. Otherwise, values from a file with reordered columns load into the wrong columns without an error.

• Coldline and Archive objects are readable but slower and cost extra to retrieve; not recommended for active pipelines.

• Bucket-level encryption with customer-managed keys (CMEK) is supported as long as the Clarisights service account has the necessary key access; customer-supplied encryption keys (CSEK) are not supported.

Operating notes

• Refresh cadence is set per pipeline during onboarding. New files dropped into the prefix between refreshes are picked up on the next scheduled run.

• IAM rotation: if you ever need to revoke access, remove the Storage Object Viewer binding for the Clarisights service account on the bucket; reinstating it restores reads on the next refresh.

• Adding new files or prefixes: drop new files under the existing prefix to extend the dataset, or contact Clarisights to onboard an additional prefix as a separate source.

Need help?

To contact support, click ? at the bottom right of Clarisights and choose Send us a message, or email support@clarisights.com. Include:

• The integration name and bucket name

• The exact error message or screenshot

• The step where the issue occurred

• When the issue started