In this tutorial, we'll show you how to:

  • Connect your GCS account to Faraday using a connection.

Let's dive in.

  1. You'll need a Faraday account — signup is free!


You'll need the following details to create your connection to GCS:

  • Bucket name requiredtext
  • Project ID requiredtext

Granting access

First, you'll need Faraday access to your GCS account.

CSV is a well-known format for transferring data in large batches. Faraday can accept files up to 5gb in size. If you have more than 5gb of data, we ask that you split it into multiple files.

Faraday's CSV support is based on folders. Each CSV in a folder should have the exact same structure. There should be no more than 5000 files in a single folder.

Google Cloud Storage (GCS) can be used to send and receive files. Access is shared using Google Cloud IAM permissions. We suggest that you create a Faraday-only bucket to both send and receive data. Within this bucket, Faraday would have full read and write access. Alternatively, you can give Faraday access to certain prefixes in a shared bucket.

Which IAM account (or both) depends on use of Targets and/or Datasets:

  • Datasets: faraday-incoming@production-237317.iam.gserviceaccount.com
  • Targets: faraday-outgoing@production-237317.iam.gserviceaccount.com

  • Give service account Storage Object Admin

  • If this is a shared bucket, limit access using to specific prefixes using an object prefix IAM Condition

Here is an example object prefix condition


Faraday suggests that you use an unguessable string somewhere in the path to your data. This avoids what is called the Confused deputy problem

For example, instead of naming an S3 bucket s3://faraday-acme/, name it s3://faraday-acme-pwiiprz162ez. This guarantees that malicious actors cannot guess the name and request that Faraday import data from it into their account. The same logic applies to any path that is used to locate data.



Use a POST /connections request:

curl https://api.faraday.ai/connections --json '{
  "name": "GCS",
  "options": {
    "type": "gcp-gcs-csv",
    "bucket_name": "...",
    "project_id": "..."
  1. Wait briefly while Faraday establishes your connection. It shouldn't take long.

Your new connection is now ready to use.