Skip to main content

Google Cloud Storage

​
Google Cloud Storage

DirectionUnidirectional
Environment
WebiOSAndroidCTVAPI Direct
Capability
Connectivity
SDK RequiredNo
Product(s) Required
Core Platform

Google Cloud Storage enables publishers to import audience data stored in GCS buckets for cohort building and activation across your publisher inventory.

Setup

Troubleshooting

​
Overview

The Google Cloud Storage integration enables publishers to import audience data from GCS buckets into Permutive for cohort building and activation. Permutive offers two connection options: connecting to your own GCS bucket, or having Permutive provision a bucket for you. Key capabilities include:
  • Support for customer-owned or Permutive-provisioned buckets
  • Hive-style partitioning for efficient data organization
  • Support for Parquet (recommended) and CSV data formats
  • Self-service setup through the Permutive Dashboard

​
Environment Compatibility

EnvironmentSupportedNotes
WebYes—
iOSYes—
AndroidYes—
CTVYes—
API DirectYes—

​
Setup

Setting up the GCS integration involves preparing your bucket with the correct directory structure, granting Permutive the necessary permissions, and creating the connection in the Permutive Dashboard. You can either connect your own GCS bucket or have Permutive provision one for you.

​
Prerequisites

  • A Google Cloud Platform (GCP) account
  • For customer-owned buckets: ability to manage IAM permissions on your GCS bucket (granting roles/storage.objectViewer and roles/storage.bucketViewer to Permutive’s service account)
  • Your data organized using Hive-style partitioning (recommended) in Parquet or CSV format

​
Quick Reference

StepDescription
1. Prepare your bucketStructure your GCS bucket with a schema prefix containing table subdirectories, using Hive-style partitions where possible
2. Grant permissionsFor customer-owned buckets, grant Permutive’s service account ([email protected]) read access via IAM roles
3. Create the connectionIn the Permutive Dashboard, go to Connectivity > Catalog, select Google Cloud Storage, and enter your bucket details
4. Create an importGo to Connectivity > Imports to import data from your new connection

Full Setup Guide

Follow the complete step-by-step guide for connecting to Google Cloud Storage, including detailed bucket structure requirements, data format recommendations, IAM configuration, and connection setup for both customer-owned and Permutive-provisioned buckets.
 For more details on configuring imports, see Imports.

​
Limitations

Important limitations to be aware of:
  • Partitioning Standard: Only Hive-style partitioning is supported
  • Mixed Partitioning: Not supported in a single schema connection. All tables must either be partitioned or non-partitioned
  • Schema Evolution: Column changes (additions/removals) are not supported for GCS imports. If your column structure changes, you’ll need to create a new connection

​
Troubleshooting

Cause: The IAM permissions may not be correctly applied, or the bucket details are incorrect.Solution:
  1. Verify the IAM permissions have been correctly applied to [email protected]
  2. Check that the bucket name and project ID are correct
  3. Ensure the schema prefix exists and contains table directories
  4. Double-check your IAM settings in the Google Cloud Console
Cause: Directory structure doesn’t match the required format, or data files are missing.Solution:
  1. Verify your directory structure matches the required format
  2. Check that data files exist under each table directory
  3. Ensure the data format setting matches your actual file format
  4. Review your GCS bucket structure and ensure each table is a direct subdirectory of the schema prefix
  5. After making changes, run a schema resync in Permutive to refresh the available tables
Cause: Partitioning settings don’t match your data structure.Solution:
  1. Verify “All tables are partitioned” is selected in Data Partitioning
  2. Check that partition directories use the correct Hive format (column=value)
  3. Update your connection settings or restructure your partition directories
The bucket name is generated upon connection creation. You can find the full GCS Bucket Name on the Connection Details page immediately after setup is complete.

​
Changelog

No changes listed yet. For detailed changelog information, visit our Changelog.