Google Ads

The google_ads connector reads reports and resources from the Google Ads API. Like all StreamWright connectors it's declarative — credentials come from secrets, account identifiers from config.

Auth

source.yaml

spec:
  config:
    customer_id: { type: string }        # the account to read
  secrets:
    google_ads_credentials: { type: string }   # OAuth + developer token (one secret)
auth:
  provider: google_ads
  customer_id: "{{ config.customer_id }}"
  credentials: "{{ secrets.google_ads_credentials }}"

Credentials are a single secret reference and are redacted in every log line.

Reading data

streams/campaigns.yaml

requests:
  - name: raw_campaigns
    sdk: google_ads
    service: GoogleAdsService
    method: search_stream
    arguments:
      customer_id: "{{ config.customer_id }}"
      query: |
        SELECT campaign.id, campaign.name, campaign.status
        FROM campaign
        WHERE segments.date DURING {{ window.start }} AND {{ window.end }}

transform:
  mode: page
  steps:
    - name: campaigns
      select: |
        SELECT
          (record->>'$.campaign.id')::BIGINT AS campaign_id,
          record->>'$.campaign.name'         AS campaign_name,
          record->>'$.campaign.status'       AS status
        FROM raw_campaigns
        WHERE status = 'ENABLED'

export:
  campaigns:
    step: campaigns
    primary_key: [campaign_id]

Queries use the Google Ads query language; incremental streams bind the window.

Reference streams (examples)

The starter template (examples/sources/ads/google_ads) includes the following reference streams:

Stream	Description	Resource / Query
campaigns	Campaign settings, channel types, and statuses	FROM campaign
ad_groups	Ad groups within campaigns	FROM ad_group
ad_group_hierarchy	Multi-request hierarchy linking campaigns with child ad groups	FROM campaign, FROM ad_group
campaign_performance	Daily delivery metrics (impressions, clicks, cost) per campaign	FROM campaign (segmented)
keywords	Targeted search keywords, match types, and statuses	FROM ad_group_criterion
audience_targets	User list criteria and audience targeting rules	FROM ad_group_criterion
location_targets	Geographic targeting locations	FROM campaign_criterion

Customizable Streams

These streams are reference examples. Because streams in StreamWright are declarative, you can customize GAQL fields, add additional resources, or adjust DuckDB SQL transformations to fit your needs.

Shared vocabulary

google_ads participates in the shared vocabulary, so one pipeline's canonical nodes (e.g. accounts, campaigns, metrics) map to this network's streams — and the same pipeline runs across Microsoft and Meta Ads too.

See the connector's folder in the repo for the full option list and exact credential fields.