Skip to main content

Google Ads

The google_ads connector reads reports and resources from the Google Ads API with GAQL queries. Use it to pull campaigns, keywords and daily metrics. From a job, it can also write: create, update or remove resources, and upload conversions.

Install​

sw connectors -i google_ads

Connect​

Put these keys in a source's auth: block (with provider: google_ads) or in a job's connection.

KeyWhat it isRequired / default
developer_tokenThe Google Ads developer token (secret)Required
client_idThe OAuth client id (secret)Required
client_secretThe OAuth client secret (secret)Required
refresh_tokenThe OAuth refresh token (secret)Required
login_customer_idThe manager (MCC) account the calls go throughOptional
api_versionThe API version, for example v25The installed library's

The four secret keys must be secret references ({{ secrets.NAME }}). They are redacted in every log line.

source.yaml
kind: source
name: google_ads_demo

spec:
config:
customer_id: { type: string } # the account to read
login_customer_id: { type: string, required: false }
secrets:
developer_token: { type: string }
client_id: { type: string }
client_secret: { type: string }
refresh_token: { type: string }

auth:
provider: google_ads
developer_token: "{{ secrets.developer_token }}"
client_id: "{{ secrets.client_id }}"
client_secret: "{{ secrets.client_secret }}"
refresh_token: "{{ secrets.refresh_token }}"
login_customer_id: "{{ config.login_customer_id }}"

Read data​

In a source​

streams/campaigns.yaml
requests:
- name: raw_campaigns
operation:
service: GoogleAdsService
method: search_stream
arguments:
customer_id: "{{ config.customer_id }}"
query:
gaql:
select: [campaign.id, campaign.name, campaign.status]
from: campaign
where:
- { field: campaign.status, op: IN, type: enum, value: [ENABLED, PAUSED] }
order_by: [campaign.id]

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

export:
campaigns:
step: campaigns
primary_key: [campaign_id]
  • GoogleAdsService.search_stream runs the GAQL query for one customer.
  • Each result row is one record. Read nested fields with paths such as record->>'$.campaign.id'.
  • For daily metrics, make the stream incremental and filter on segments.date with the window dates.

Performance reports​

Google Ads has no async reports: a GAQL query is the report, and it returns its rows at once. So a report is a normal request, not an async_job. One query covers the whole customer. For ad group metrics, query FROM ad_group instead of running one query per campaign:

streams/ad_group_performance.yaml
partitions:
- { name: customer_id, values: "{{ config.customer_ids }}" }
incremental: { cursor_field: date, start: "{{ config.start_date }}", window: 7d, lookback: 30d }

requests:
- name: raw_ad_group_performance
operation:
service: GoogleAdsService
method: search_stream
arguments:
customer_id: "{{ partition.customer_id }}"
query:
gaql:
select: [campaign.id, ad_group.id, segments.date, metrics.impressions, metrics.clicks, metrics.cost_micros]
from: ad_group
where:
- { field: segments.date, op: BETWEEN, type: date, value: ["{{ window.start }}", "{{ window.end }}"] }

transform:
mode: page
steps:
- name: ad_group_performance
select: |
SELECT record->>'$.campaign.id' AS campaign_id,
record->>'$.ad_group.id' AS ad_group_id,
(record->>'$.segments.date')::DATE AS date,
coalesce((record->>'$.metrics.impressions')::BIGINT, 0) AS impressions,
coalesce((record->>'$.metrics.clicks')::BIGINT, 0) AS clicks,
round((record->>'$.metrics.cost_micros')::BIGINT * 0.000001, 2) AS cost
FROM raw_ad_group_performance

export:
ad_group_performance:
step: ad_group_performance
primary_key: [ad_group_id, date]
  • Each row carries its parent's fields (campaign.id), so you can join without a second request.
  • To read only a few campaigns, filter with campaign.id IN in the same query.
  • Money is in micros: divide cost_micros by 1,000,000.

In a job​

A call step takes the same operation. Its sql reads the table records (call steps).

connections:
ads:
provider: google_ads
developer_token: "{{ secrets.developer_token }}"
client_id: "{{ secrets.client_id }}"
client_secret: "{{ secrets.client_secret }}"
refresh_token: "{{ secrets.refresh_token }}"

steps:
- name: campaigns
connection: ads
operation:
service: GoogleAdsService
method: search_stream
arguments:
customer_id: "{{ config.customer_id }}"
query:
gaql:
select: [campaign.id, campaign.name, campaign.status]
from: campaign
sql: |
SELECT (record->>'$.campaign.id')::BIGINT AS campaign_id,
record->>'$.campaign.name' AS campaign_name,
record->>'$.campaign.status' AS status
FROM records

Write GAQL queries​

query takes one of two forms.

The gaql query builder (recommended). It writes GAQL from a mapping and checks and escapes every value. Use it whenever the query uses a config, partition or window value. A list input fills an IN directly:

query:
gaql:
select: [campaign.id, campaign.name, campaign.advertising_channel_type]
from: campaign
where:
- {field: campaign.advertising_channel_type, op: IN, type: enum,
value: "{{ config.channels }}", skip_if_empty: true} # e.g. --set channels=SEARCH,SHOPPING
order_by: [campaign.id]
KeyWhat it does
selectField paths to return
fromOne resource, for example campaign
whereConditions, joined with AND. Each has field, op, type and value
order_bySort fields, for example campaign.id or metrics.clicks DESC
limitMaximum rows
  • op: =, !=, <, <=, >, >=, IN, NOT IN, LIKE, NOT LIKE, BETWEEN, IS NULL, IS NOT NULL, CONTAINS ANY, CONTAINS ALL, CONTAINS NONE.
  • type says how value is written: int, string (quoted and escaped), enum (bare names such as SEARCH) or date (YYYY-MM-DD).
  • IN, NOT IN and CONTAINS ... take a list or a list input. BETWEEN takes [low, high]. IS NULL and IS NOT NULL take no value.
  • skip_if_empty: true drops the condition when its value is missing or empty.

GAQL text. It is sent exactly as written, so it suits fixed queries. It may not contain {{ }} references:

query: |
SELECT campaign.id, campaign.name, campaign.advertising_channel_type
FROM campaign
WHERE campaign.advertising_channel_type IN ('SEARCH', 'SHOPPING')
ORDER BY campaign.id

Both forms work in sources and in DuckDB and Spark job call steps. The full builder reference is also available from the MCP server: get_connector_guide("google_ads", "Query builder").

Starter streams​

The starter template (examples/sources/ads/google_ads) has these streams. Copy them and change the fields or SQL to fit your needs.

StreamWhat it readsGAQL resource
campaignsCampaign settings, channel types and statusescampaign
ad_groupsAd groups within campaignsad_group
ad_group_hierarchyCampaigns joined with their ad groups (two requests)campaign, ad_group
campaign_performanceDaily impressions, clicks and cost per campaigncampaign (segmented by date)
keywordsKeywords, match types and statusesad_group_criterion
audience_targetsUser list criteria and audience targetingad_group_criterion
location_targetsGeographic targetingcampaign_criterion

Write data back​

A job's apply output (reverse ETL) writes to Google Ads, one operation per row.

OperationopRows per call
*Service.mutate_* (any resource, such as CampaignService.mutate_campaigns)create (default), update, remove5000
*UploadService.upload_* (click and call conversions, conversion adjustments)upload2000
  • Columns are field paths, with or without the resource prefix: campaign.name or name, campaign.network_settings.target_google_search.
  • Update needs resource_name; the other columns are the update mask, so with nulls: clear a NULL clears a field. Remove reads resource_name and needs allow_remove: true.
  • Arguments: customer_id (required); partial_failure (default true: a rejected row fails alone, with its Google Ads error); validate_only (default false; true checks every row and changes nothing).
  • Cut-short calls: conversion uploads are sent again, because Google deduplicates them. A mutate_* call is held for you to decide (unknown outcomes).
  • Results: each applied row keeps what Google returned, such as the new resource_name.
outputs:
- name: upload
connection: ads
step: valid_conversions
operation:
service: ConversionUploadService
method: upload_click_conversions
arguments:
customer_id: "{{ config.customer_id }}"
validate_only: "{{ config.validate_only }}" # true: a dry run
apply: {on_row_error: continue}

Complete jobs (create campaigns and conversion actions, upload conversions) are in examples/google_ads.

Good to know​

  • Engines: sources (streamwright run), and DuckDB and Spark jobs through call steps. Writes run only in job apply outputs.
  • Read operations: GoogleAdsService.search and search_stream take a typed customer_id and query. The get_* and list_* methods of any *Service also work, for example CustomerService.list_accessible_customers; their request fields are vendor arguments. The installed Google Ads library decides which methods exist.
  • Vendor arguments: any other request field goes to Google unchanged, for example return_total_results_count: true.
  • Case-sensitive values: GAQL enums are upper case (ENABLED, SEARCH); field paths are lower case (segments.date).
  • Allow-listing: --allow-connector google_ads also allows its gaql query builder.
  • Retries: by default the connector retries RESOURCE_EXHAUSTED, UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, ABORTED, RESOURCE_TEMPORARILY_EXHAUSTED, INTERNAL_ERROR and TRANSIENT_ERROR (a Google Ads error name or gRPC status). Setting retry: { codes: [RESOURCE_EXHAUSTED] } on a stream replaces that list.

See also​

  • Apply outputs: how writes are delivered, logged and retried.
  • Call steps: reading from a connector inside a job.
  • Shared vocabulary: run one pipeline across Google, Microsoft, Meta and other ad networks.