Google Drive Destination

Connect Google Drive as a destination to deliver pipeline output as CSV files, native Google Sheets, or Excel .xlsx workbooks.

To read files from Google Drive instead, see Google Drive Source.

Prerequisites

Before you begin, ensure you have:

• A Google Drive folder where Supaflow can write output files
• Allow Write Access enabled on the Google Drive connection

For Managed service account authentication (recommended):

• Permission to share the destination folder with the generated Supaflow service account email
• A destination folder in a Google Shared Drive
• Content manager access or higher for the generated service account
• No Google Cloud project, service account key, or JSON key upload is required

For OAuth authentication:

• A Google account with Editor access or higher on the destination folder
• Re-authorization if the connection was authorized before Google Drive write access was added

For Service account key authentication:

• A Google Cloud Platform (GCP) project with the Google Drive API enabled
• The Google Sheets API enabled when using native Google Sheets output
• A GCP Service Account with a JSON key file
• A destination folder in a Google Shared Drive
• Content manager access or higher for the service account

Output Formats and Layout

Choose Destination Output independently from the source-side Source File Type setting.

CSV Files

For CSV output, each destination table has a child folder under the configured folder:

Configured Drive folder
+-- customers/
|   +-- customers_<timestamp>_<job-id>_part_0.csv
|   +-- customers_<timestamp>_<job-id>_part_1.csv
+-- orders/
    +-- orders_<timestamp>_<job-id>_part_0.csv

If the pipeline namespace is included in the mapped table name, Supaflow folds it into the table folder name, for example crm_contacts.

Google Sheets and Excel

Spreadsheet output supports two layouts:

• File per object (default) creates one Google Sheet or Excel workbook for each selected object.
• Single workbook creates one pipeline workbook and one managed worksheet for each selected object. Use this layout for pipelines with a small number of objects.

Single-workbook files include a short pipeline identifier in their initial display name. You can rename a managed file or worksheet later; Supaflow continues to identify it by its stored identity instead of its visible name.

Write Semantics

The destination supports:

• Append — adds rows after existing destination data. CSV output adds new part files; spreadsheet output reuses the same file and worksheet without duplicating the header.
• Truncate and load — replaces the managed rows with the rows supplied by the current run. CSV output publishes a replacement table folder; spreadsheet output keeps the same file and worksheet.

For spreadsheet snapshots, Truncate and load is usually the clearest choice. It replaces only the data supplied by that run; configure the source to provide a complete snapshot if the worksheet must always show the complete current table.

For CSV output, the first run uses fail-if-present behavior: if the target table folder already contains files, the run fails instead of appending into an existing folder. Spreadsheet files are resolved by their Supaflow-managed identity, so an unrelated Drive file with the same display name is not adopted.

Using a folder dedicated to pipeline output makes ownership easier to understand. If you need a clean replacement, reset the target from Supaflow rather than manually deleting files during an active run.

Spreadsheet Preservation

Supaflow owns the managed header and source-data columns for each object worksheet. Standard user changes outside that managed range are preserved, including:

• user-created worksheets
• worksheet order and user-renamed managed worksheets
• header styling, column widths, row heights, frozen panes, filters, and data validation
• custom columns and formulas to the right of the managed columns

Append preserves existing values in the managed range and adds new rows. Truncate and load replaces managed values and clears stale managed rows, while leaving a header-only worksheet for a zero-row result. Supaflow does not automatically fill adjacent formulas into newly appended rows.

Avoid placing notes or formulas inside the managed source columns or below their active data. Those cells follow the selected load mode and may be replaced.

Renaming a worksheet can invalidate title-based formulas in other files, including IMPORTRANGE formulas that contain the old worksheet title as text. Use a Google Sheets named range when external references must survive worksheet renames.

Spreadsheet Limits

• Google Sheets output enforces a 5 million managed-cell limit per object.
• A single Google Sheets workbook is checked against 10 million allocated cells and a 50-worksheet limit. Empty allocated rows and columns count toward that total.
• Supaflow fails an oversized Google Sheets write with a recommendation to use file-per-object layout, Excel, or CSV. It does not split one object across unexpected overflow worksheets.
• Excel output follows the .xlsx row and column limits, has a 512 MB in-place update limit, and must fit in the agent's available memory and temporary disk space.

Reading Destination Output Back

CSV destination output can be read back by creating a Google Drive source that points to the same configured folder and uses CSV as its source file type.

The round-trip behavior follows the Google Drive source's CSV rules:

• Each child folder becomes a source table
• Files inside that folder become rows for the table
• The source re-infers column types from sampled CSV files
• Empty table folders are not discovered as source tables until data files exist

Google Sheets and Excel output can be read with the matching Google Drive source file type. For spreadsheet sources, each worksheet is discovered as a separate source object, so the selected workbook layout affects the resulting object names.

Authentication Setup

Managed Service Account

Supaflow provisions the service account email for you.

1. Choose Managed service account as the authentication method
2. Copy the generated Service account email from the destination form
3. Open the destination folder in Google Drive
4. Share the folder with the generated service account email
5. Grant Content manager access or higher
6. Return to Supaflow and test the connection

For managed service account destinations, the folder must be in a Google Shared Drive. Regular My Drive folders can fail because service accounts do not have their own Drive storage quota.

OAuth

OAuth uses a Google account that already has write access to the destination folder.

1. Choose OAuth as the authentication method
2. Click Authorize
3. Sign in with the Google account that can write to the destination folder
4. Complete the Google consent flow
5. Return to Supaflow and test the connection

If an existing OAuth connection was authorized before write access support was added, click Authorize again so the stored grant includes the current Drive permission.

Service Account Key

These steps are only needed when you choose Service account key authentication and upload your own Google Cloud service account JSON key.

1. Create or choose a Google Cloud project
2. Enable the Google Drive API
3. Enable the Google Sheets API if you plan to write native Google Sheets
4. Create a service account
5. Create and download a JSON key
6. Share the destination folder with the service account email
7. Grant Content manager access or higher
8. Upload the JSON key in Supaflow and test the connection

For service account key destinations, the folder must be in a Google Shared Drive. Regular My Drive folders can fail because service accounts do not have their own Drive storage quota.

Configuration

In Supaflow, create a new Google Drive destination with these settings:

Authentication

Authentication Method*

Select how Supaflow authenticates with Google Drive.
Options:

• managed_service_account - Supaflow generates a service account email. Share the destination folder with that email.
• oauth - Sign in with a Google account that can write to the destination folder.
• service_account - Upload your own Google Cloud service account JSON key.

Default: managed_service_account

Service account email

Supaflow generates this email automatically. Share the destination folder with the generated service account email, then test the connection.

Authorize

Click Authorize to open the Google sign-in flow. Sign in with a Google account that has write access to the destination folder.

Service Account Key*

Upload your Google service account JSON key file.
Stored encrypted

Allow Write Access

Write access is off by default on new Google Drive connections and must be enabled for destination use. Leave it disabled only when the connection should remain read-only.

Configuration

Folder URL*

Google Drive destination folder URL or folder ID. You can paste the full URL from your browser or just the folder ID.
Example: https://drive.google.com/drive/folders/1jPbXXTs_ZYmb...

Destination Output

Destination Output*

Select the format Supaflow writes.
Options:

• CSV_FILES — plain CSV files in one table folder per object
• GOOGLE_SHEETS — native Google Sheets
• EXCEL_WORKBOOK — Excel .xlsx workbooks

Default: CSV_FILES

Workbook Layout*

Choose how spreadsheet objects are grouped.
Options:

• FILE_PER_OBJECT — one workbook per selected object
• SINGLE_WORKBOOK — one pipeline workbook with one worksheet per object

Default: FILE_PER_OBJECT

Workbook Name*

Initial display name for single-workbook output. You can rename the created file later without breaking managed identity.
Default: Supaflow Data

Test & Save

After configuring all required properties, click Test & Save to verify the connection, folder access, and write permissions.

Rate Limiting

Google Drive and Google Sheets apply API rate limits. Supaflow retries transient rate limiting with backoff, but large jobs can take longer or may need narrower scope or off-peak scheduling. See Google's Drive API limits and Sheets API limits for current guidance.

Troubleshooting

Destination write fails with service account storage quota error

Problem:

• Destination setup or sync fails with a message like "service accounts cannot create files because they do not have Drive storage quota"
• Upload fails even though the folder was shared with the service account as Editor

Solutions:

1. Move or create the destination folder in a Google Shared Drive.
2. Grant the managed service account email or service account key email Content manager access or higher.
3. Use OAuth if the destination must remain in a regular My Drive folder.
4. Re-test the connection after changing folder location or permissions.

Connection test fails with write permission error

Problem:

• Test & Save reports that Supaflow cannot write to the configured folder
• Destination runs fail with an insufficient-permissions message

Solutions:

1. Confirm Allow Write Access is enabled.
2. For OAuth, click Authorize again and sign in with an account that can edit the destination folder.
3. For managed service account or service account key auth, confirm the folder is in a Shared Drive and the service account has Content manager access or higher.
4. Confirm the folder URL points to the folder you intend to write to, not a file or shortcut.

First run fails because the table folder already contains files

Problem:

• The first destination run fails because the target table folder is not empty

Solutions:

1. Use a new empty folder for the pipeline.
2. Remove unrelated files before the first run.
3. If you intentionally want to replace prior pipeline output, reset the target from Supaflow.

Spreadsheet write reports a worksheet collision

Problem:

• A run cannot create or rename a managed worksheet because the required title is already occupied

Solutions:

1. Check for a user-created worksheet with the same title, including differences in capitalization.
2. Rename the unrelated worksheet and retry.
3. Do not delete or rename the hidden Supaflow metadata worksheet in Excel workbooks.

Google Sheets workbook is too large

Problem:

• The run reports that the projected workbook exceeds the allocated-cell or worksheet limit

Solutions:

1. Switch Workbook Layout to FILE_PER_OBJECT.
2. Remove unused rows, columns, or worksheets from a single workbook.
3. Use EXCEL_WORKBOOK or CSV_FILES for larger output.

Excel workbook changed during publication

Problem:

• The run reports that the Excel workbook changed while Supaflow was preparing its update

Solutions:

1. Wait for active editors or other automations to finish.
2. Retry the sync. Supaflow does not publish the stale local copy over the newer workbook.

Google Drive source does not discover a destination-written table

Problem:

• A Google Drive source pointed at the destination folder does not show an expected table

Solutions:

1. Confirm the source is configured with File Type set to CSV.
2. Confirm the table folder contains at least one CSV data file.
3. Re-run schema discovery after the destination run finishes.
4. Empty table folders are not discovered by the Google Drive source until data files exist.

Support

Need help? Contact us at support@supa-flow.io