Google Cloud Storage (GCS) File Upload Guide
This guide defines the requirements for uploading files to our Google Cloud Storage (GCS) bucket to ensure reliable, automated processing as an alternative to using Bonsai's Connect Cards.
Supported File Types
Preferred: .csv, .csv.gz, .parquet
Not supported: Excel files (.xlsx, .xls), files with formulas, unapproved JSON formats
Encoding: UTF-8 only
File Naming Convention
Required format
<source>_<dataset or table>_<YYYYMMDD>.<extension>Example
shopify_orders_20250301.csvRules
Lowercase only
Use underscores (_), no spaces or special characters
Include a date for time-based data
Do not overwrite files unless explicitly instructed
File Structure
Single header row required
One record per row
No totals, summaries, or footers
One dataset per file only
Schema & Columns
Column names must be lowercase snake_case
Column order must remain consistent
Data types must not change over time
Use blank or NULL values for missing data
Do not use placeholders like N/A, unknown, or 0 unless required
Dates & Timestamps
Use ISO-8601 formats
Date: YYYY-MM-DD
Timestamp: YYYY-MM-DDTHH:MM:SS
Use UTC for all timestamps
Schema Changes
Please notify us before:
Renaming or removing columns
Changing data types
Changing file structure
Allowed with approval: adding new nullable columns Breaking changes may require versioned files or folders.
Delivery Expectations
Upload files on the agreed cadence (daily, weekly, ad hoc)
Files must be complete at upload time
Late or corrected data must follow the agreed backfill process
Last updated