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.
| Key | What it is | Required / default |
|---|---|---|
developer_token | The Google Ads developer token (secret) | Required |
client_id | The OAuth client id (secret) | Required |
client_secret | The OAuth client secret (secret) | Required |
refresh_token | The OAuth refresh token (secret) | Required |
login_customer_id | The manager (MCC) account the calls go through | Optional |
api_version | The API version, for example v25 | The installed library's |
The four secret keys must be secret references ({{ secrets.NAME }}). They are redacted in every log line.
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
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_streamruns the GAQL query for one customer.- Each result row is one
record. Read nested fields with paths such asrecord->>'$.campaign.id'. - For daily metrics, make the stream incremental and filter on
segments.datewith 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:
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 INin the same query. - Money is in micros: divide
cost_microsby 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]
| Key | What it does |
|---|---|
select | Field paths to return |
from | One resource, for example campaign |
where | Conditions, joined with AND. Each has field, op, type and value |
order_by | Sort fields, for example campaign.id or metrics.clicks DESC |
limit | Maximum rows |
op:=,!=,<,<=,>,>=,IN,NOT IN,LIKE,NOT LIKE,BETWEEN,IS NULL,IS NOT NULL,CONTAINS ANY,CONTAINS ALL,CONTAINS NONE.typesays howvalueis written:int,string(quoted and escaped),enum(bare names such asSEARCH) ordate(YYYY-MM-DD).IN,NOT INandCONTAINS ...take a list or a list input.BETWEENtakes[low, high].IS NULLandIS NOT NULLtake no value.skip_if_empty: truedrops 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.
| Stream | What it reads | GAQL resource |
|---|---|---|
campaigns | Campaign settings, channel types and statuses | campaign |
ad_groups | Ad groups within campaigns | ad_group |
ad_group_hierarchy | Campaigns joined with their ad groups (two requests) | campaign, ad_group |
campaign_performance | Daily impressions, clicks and cost per campaign | campaign (segmented by date) |
keywords | Keywords, match types and statuses | ad_group_criterion |
audience_targets | User list criteria and audience targeting | ad_group_criterion |
location_targets | Geographic targeting | campaign_criterion |
Write data back
A job's apply output (reverse ETL) writes to Google Ads, one operation per row.
| Operation | op | Rows per call |
|---|---|---|
*Service.mutate_* (any resource, such as CampaignService.mutate_campaigns) | create (default), update, remove | 5000 |
*UploadService.upload_* (click and call conversions, conversion adjustments) | upload | 2000 |
- Columns are field paths, with or without the resource prefix:
campaign.nameorname,campaign.network_settings.target_google_search. - Update needs
resource_name; the other columns are the update mask, so withnulls: cleara NULL clears a field. Remove readsresource_nameand needsallow_remove: true. - Arguments:
customer_id(required);partial_failure(defaulttrue: a rejected row fails alone, with its Google Ads error);validate_only(defaultfalse;truechecks 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.searchandsearch_streamtake a typedcustomer_idandquery. Theget_*andlist_*methods of any*Servicealso work, for exampleCustomerService.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_adsalso allows itsgaqlquery builder. - Retries: by default the connector retries
RESOURCE_EXHAUSTED,UNAVAILABLE,DEADLINE_EXCEEDED,INTERNAL,ABORTED,RESOURCE_TEMPORARILY_EXHAUSTED,INTERNAL_ERRORandTRANSIENT_ERROR(a Google Ads error name or gRPC status). Settingretry: { 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.