project
Required
Type:
string
Description: GCP project ID that holds the BigQuery dataset.
Notes:
location
Type:
string
Description:
GCP region the dataset lives in, for example US, EU, or asia-southeast1.
Notes:
bucket_name
Required
Type:
string
Description: Staging GCS bucket RudderStack writes event files to before loading them into BigQuery. The bucket must already exist, and should be co-located with the dataset so loads don’t cross regions.
Notes:
[a-z0-9][a-z0-9-._]{1,61}[a-z0-9].goog, contain google, look like an IP address, or contain consecutive dots.prefix
Type:
string
Description: Folder prefix inside the staging bucket. RudderStack creates a folder with this prefix and writes all staged files beneath it.
Notes:
namespace
Immutable
Type:
string
Description: Dataset RudderStack creates its tables in. Defaults to the source name, snake-cased, when omitted.
Notes:
pg_ in any capitalization.credentials
RequiredSecret
Type:
string
Description: GCP service account JSON key. The account needs BigQuery dataset, table, and job permissions, plus read and write access to the staging bucket.
Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.
See Setting up the service account for RudderStack for the exact roles.
sync_frequency
Required
Type:
string
Description: How often RudderStack syncs staged events into the dataset, in minutes. Written as a string, not a number.
Notes:
5, 10, 15, 30, 60, 180, 360, 720, or 1440.180. Rudder CLI requires it explicitly.sync_start_at
Type:
string
Description:
Time of day, in UTC, that anchors the sync schedule. Subsequent syncs are computed from it at sync_frequency intervals. Written as HH:MM — the dashboard offers 15-minute steps.
Notes:
exclude_window
Type:
object
Description: Daily window, in UTC, during which RudderStack doesn’t sync. Omit the block entirely to sync around the clock.
Notes:
start_time — string, when the window opens, HH:MMend_time — string, when the window closes, HH:MMexclude_window:
start_time: "02:00"
end_time: "03:00"skip_users_table
Type:
boolean
Default value:
true
Description:
Send identify events only to the identifies table, skipping the users table. The users table holds one row per unique user and is maintained with a merge, which can add significant time to each sync.
false to populate both tables. See Warehouse Schema.
skip_tracks_table
Type:
boolean
Default value:
false
Description:
Skip sending events to the tracks table. Per-event tables are unaffected.
skip_views
Immutable
Type:
boolean
Default value:
false
Description:
Skip creating the <table_name>_view deduplication view alongside each table. The views cover the last 60 days and exist so queries don’t return duplicate events. Skip them only if you deduplicate another way.
Notes:
partition_column
Immutable
Type:
string
Default value:
_PARTITIONTIME
Description: Column BigQuery partitions each table on:
Notes:
_PARTITIONTIME — ingestion time, when BigQuery received the dataloaded_at — when RudderStack loaded the data into the warehousereceived_at — when RudderStack received the eventtimestamp — event time corrected for client-side clock skewsent_at — when the client sent the event to RudderStackoriginal_timestamp — when the event was generated at the sourcepartition_type
Immutable
Type:
string
Default value:
day
Description:
Granularity of the partition: hour or day.
Notes:
partition_column.json_paths
Type:
string
Description:
Comma-separated dot-notation paths whose values are stored as JSON columns instead of being flattened into separate columns. Applies to every track event sent to this destination.
Notes:
json_paths: context.traits,properties.metadataSee JSON Column Support.
cleanup_object_storage_files
Type:
boolean
Default value:
false
Description: Delete staged files from the GCS bucket after a sync completes successfully.
underscore_divide_numbers
ImmutableInternal
Type:
boolean
Default value:
false
Description:
When false, numeric suffixes in column names are preserved: v3 stays v3 rather than being split into v_3.
allow_users_context_traits
ImmutableInternal
Type:
boolean
Default value:
false
Description:
When false, context.traits.* fields aren’t promoted to top-level traits and are stored only as context_traits_* columns.
connection_mode
Type:
object
Description: Maps each source type you connect to the mode its events reach BigQuery in, using the modes in Source types.
Notes:
connection_mode:
web: cloud
android_kotlin: cloudconsent_management
Type:
object
Description:
Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.
| Version | Change |
|---|---|
| v0.29.0 | Breaking: A null config value, written as key: null, key: ~, or key: with no value, fails validate with '<key>' must not be null; set a value or remove the key. Earlier releases accepted it: a top-level null planned an update on every apply, and a null inside a list item failed at the API.What to do: Remove the key to leave it unset, or give it a value. |
| v0.29.0 | Breaking: An empty string, "", on a key that takes one of a fixed set of values fails validate with '<key>' must be one of [...], unless "" is one of the key’s values. Earlier releases accepted it, and the API rejected it at apply.What to do: Remove the key to leave it unset, or set one of the listed values. |
| v0.29.0 | Changed: validate warns when a secret key holds anything but one {{ .VAR }} reference with no default, and when one variable fills two secret keys. It also masks secret values in the lines it prints. |
| v0.29.0 | Changed: rudder-cli import writes each secret reference single-quoted, as '{{ .VAR }}', so a value containing double quotes, like a JSON key file, substitutes as a string. A single quote in a value that fills such a reference is written as ''.What to do: In a spec imported by an earlier release, quote each reference to a JSON value by hand: '{{ .VAR }}'. |
| v0.29.0 | Changed: validate reports a value of the wrong type once per key, such as 'email' must be a string, instead of one raw decoding error. |