Google Ads connector reference

Important

This feature is in Beta.

This page provides reference information for the managed Google Ads connector in Lakeflow Connect, including supported tables, column definitions, and data types.

Supported tables

The Google Ads connector supports the following types of tables:

  • Resource tables: Configuration data about your Google Ads account, like campaigns, ad groups, and ads. These tables are fully refreshed on each pipeline run.
  • Report tables: Performance metrics, like impressions, clicks, and conversions. These tables support incremental ingestion.
  • Event tables: Individual events such as calls, lead form submissions, and Local Services leads. These tables are fully refreshed on each pipeline run.

Resource tables

Table name Description
customer Information about Google Ads accounts.
campaign Campaign configuration and settings.
campaign_budget Budget settings for campaigns.
campaign_criterion Targeting criteria for campaigns.
ad_group Ad group configuration.
ad_group_criterion Targeting criteria for ad groups.
ad Individual ad details and settings.

Report tables

Table name Description
customer_report Account-level performance metrics.
campaign_report Campaign-level performance metrics.
ad_group_report Ad group-level performance metrics.
ad_report Ad-level performance metrics.
keyword_report Keyword-level performance metrics.
search_query_report Search query-level performance metrics.
customer_hourly_report Account-level performance metrics broken down by hour.
campaign_hourly_report Campaign-level performance metrics broken down by hour.
ad_group_hourly_report Ad group-level performance metrics broken down by hour.
audience_report Audience-level (ad group criterion) performance metrics.
click_report Click-level metrics keyed by Google Click ID (gclid).
landing_page_report Landing page (expanded final URL) performance metrics.
search_keyword_report Keyword-level performance metrics from the keyword view.

Event tables

Table name Description
call_view Calls tracked from call extensions and call-only ads.
lead_form_submission Lead form submissions. Requires Standard or Admin access to the Google Ads account.
local_services_lead Local Services Ads leads. Only returns rows for Local Services accounts.
local_services_lead_conversation Conversations on Local Services Ads leads. Only returns rows for Local Services accounts.

Data type conventions

Money storage (micros)

Google Ads stores monetary values in micros to avoid rounding issues. One million micros equals one unit of currency:

  • 1,000,000 micros = $1.00 USD
  • 5,500,000 micros = $5.50 USD

Fields with _micros suffix contain values stored in micros. Divide by 1,000,000 to convert to your currency.

Primary keys

Tables use (Primary Key) notation to indicate columns that form the primary key. Composite primary keys are indicated by multiple columns marked as (Primary Key).

The call_view, lead_form_submission, local_services_lead, and local_services_lead_conversation tables use a synthetic _databricks_row_id column (a per-row UUID) as the primary key, because their source keys are not unique per row. Each sync fully refreshes these tables.

Resource table schemas

customer

Information about Google Ads accounts.

Column Data type Description
id long Primary key. Customer account ID.
auto_tagging_enabled boolean Whether auto-tagging is enabled for the account.
currency_code string Currency code for the account.
descriptive_name string Human-friendly name for the Google Ads account.
final_url_suffix string URL suffix appended to final URLs for tracking.
manager boolean Whether the customer is a Manager Account (MCC).
optimization_score double Optimization score for the account.
pay_per_conversion_eligibility_failure_reasons array<string> Reasons the account is ineligible for pay-per-conversion bidding.
test_account boolean Whether the customer is a test account.
time_zone string Time zone of the account.
tracking_url_template string URL template for constructing tracking URLs.

campaign

Campaign configuration and settings.

Column Data type Description
id long Primary key. Campaign ID.
name string Campaign name.
status string Campaign status.
advertising_channel_type string Advertising channel type.
start_date string Campaign start date.
end_date string Campaign end date.
campaign_budget_id long ID of the associated campaign budget.

campaign_budget

Budget settings for campaigns.

Column Data type Description
id long Primary key. Budget ID.
resource_name string Google Ads resource name.
name string Budget name.
amount_micros long Budget amount in micros. Divide by 1,000,000 to convert to currency.
delivery_method string How Google spends the daily budget (standard or accelerated).
period string Budget period.
status string Budget status.
total_amount_micros long Total amount of the budget in micros. Divide by 1,000,000 to convert to currency.

campaign_criterion

Targeting criteria for campaigns.

Column Data type Description
campaign_id long Primary key. Campaign ID.
criterion_id long Primary key. Criterion ID.
resource_name string Google Ads resource name.
type string Criterion type.
status string Criterion status.
negative boolean Whether this criterion excludes an audience.
bid_modifier double Bid modifier value.

ad_group

Ad group configuration.

Column Data type Description
id long Primary key. Ad group ID.
name string Ad group name.
status string Ad group status.
campaign_id long Associated campaign ID.
type string Ad group type.
cpc_bid_micros long Cost per click bid in micros.
target_cpa_micros long Target cost per acquisition in micros.

ad_group_criterion

Targeting criteria for ad groups.

Column Data type Description
criterion_id long Primary key. Criterion ID.
ad_group_id long Primary key. Ad group ID.
resource_name string Google Ads resource name.
status string Criterion status.
type string Criterion type.
negative boolean Whether this criterion excludes an audience.
keyword_match_type string Keyword match type (exact, phrase, broad).
keyword_text string Keyword text.

Individual ad details and settings. This table corresponds to ad_group_ad in the Google Ads API.

Column Data type Description
id long Primary key. Ad ID.
ad_group_id long Primary key. Ad group ID.
status string Ad status.
ad_type string Ad type.
final_urls array<string> Landing page URLs after clicking the ad.
policy_summary_approval_status string Whether the ad is approved under Google Ads policy (APPROVED or DISAPPROVED).
policy_summary_review_status string Whether Google has finished reviewing the ad (REVIEW_IN_PROGRESS or REVIEWED).

Report table schemas

customer_report

Account-level performance metrics.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
device string Primary key. Device type.
ad_network_type string Primary key. Ad network type.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros. Divide by 1,000,000 to convert to currency.
conversions double Number of conversions.
conversions_value double Total conversion value.
ctr double Click-through rate.
average_cpc double Average cost per click.

campaign_report

Campaign-level performance metrics.

Column Data type Description
customer_id long Primary key. Customer account ID.
id long Primary key. Campaign ID.
date string Primary key. Date in YYYY-MM-DD format.
device string Primary key. Device type.
ad_network_type string Primary key. Ad network type.
campaign_name string Campaign name.
campaign_status string Campaign status.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros.
conversions double Number of conversions.

ad_group_report

Ad group-level performance metrics.

Column Data type Description
customer_id long Primary key. Customer account ID.
id long Primary key. Ad group ID.
date string Primary key. Date in YYYY-MM-DD format.
device string Primary key. Device type.
ad_network_type string Primary key. Ad network type.
ad_group_name string Ad group name.
ad_group_status string Ad group status.
campaign_id long Associated campaign ID.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros.

keyword_report

Keyword-level performance metrics.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
ad_group_criterion_criterion_id long Primary key. Criterion ID.
ad_group_id long Primary key. Ad group ID.
device string Primary key. Device type.
ad_network_type string Primary key. Ad network type.
keyword_text string Keyword text.
keyword_match_type string Keyword match type.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros.

ad_report

Ad-level performance metrics.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
ad_id long Primary key. Ad ID.
ad_group_id long Primary key. Ad group ID.
device string Primary key. Device type.
ad_network_type string Primary key. Ad network type.
campaign_id long Associated campaign ID.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros.
conversions double Number of conversions.

search_query_report

Search query-level performance metrics.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
resource_name string Primary key. Google Ads resource name.
search_term string User's search term.
search_term_match_type string How the keyword matched the search term.
ad_group_id long Associated ad group ID.
campaign_id long Associated campaign ID.
impressions long Number of impressions.
clicks long Number of clicks.

customer_hourly_report

Account-level performance metrics broken down by hour.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
hour int Primary key. Hour of day (0–23).
click_type string Primary key. Click type.
device string Primary key. Device type.
ad_network_type string Primary key. Ad network type.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros. Divide by 1,000,000 to convert to currency.
conversions double Number of conversions.
ctr double Click-through rate.

The hourly report tables also include additional segment columns (day_of_week, week, month, quarter, year, interaction_event_types) and metric columns (interactions, interaction_rate, average_cost, average_cpc, average_cpm, cost_per_conversion, value_per_conversion, conversions_value, conversions_from_interactions_rate, and Active View metrics).

campaign_hourly_report

Campaign-level performance metrics broken down by hour. Same columns as customer_hourly_report, plus:

Column Data type Description
id long Primary key. Campaign ID.
base_campaign string Resource name of the base campaign for experiments.

ad_group_hourly_report

Ad group-level performance metrics broken down by hour. Same columns as customer_hourly_report, plus:

Column Data type Description
id long Primary key. Ad group ID.
campaign_id long Associated campaign ID.

audience_report

Audience-level (ad group criterion) performance metrics.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
ad_group_criterion_criterion_id long Primary key. Ad group criterion (audience) ID.
ad_group_id long Primary key. Ad group ID.
device string Primary key. Device type.
ad_network_type string Primary key. Ad network type.
campaign_id long Associated campaign ID.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros. Divide by 1,000,000 to convert to currency.
conversions double Number of conversions.
conversions_value double Total conversion value.
view_through_conversions long View-through conversions.

click_report

Click-level metrics keyed by Google Click ID.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
gclid string Primary key. Google Click ID.
ad_group_id long Associated ad group ID.
campaign_id long Associated campaign ID.
clicks long Number of clicks.

landing_page_report

Landing page performance metrics keyed by expanded final URL.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
resource_name string Primary key. Google Ads resource name.
ad_group_id long Primary key. Ad group ID.
campaign_id long Primary key. Campaign ID.
unexpanded_final_url string Landing page URL before expansion.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros. Divide by 1,000,000 to convert to currency.
ctr double Click-through rate.
average_cpc double Average cost per click.
mobile_friendly_clicks_percentage double Percentage of mobile-friendly clicks.
speed_score long Mobile speed score.
valid_accelerated_mobile_pages_clicks_percentage double Percentage of valid AMP clicks.

search_keyword_report

Keyword-level performance metrics from the keyword view.

Column Data type Description
customer_id long Primary key. Customer account ID.
date string Primary key. Date in YYYY-MM-DD format.
resource_name string Primary key. Google Ads resource name.
ad_group_criterion_criterion_id long Ad group criterion (keyword) ID.
ad_group_id long Associated ad group ID.
campaign_id long Associated campaign ID.
impressions long Number of impressions.
clicks long Number of clicks.
cost_micros long Cost in micros. Divide by 1,000,000 to convert to currency.
ctr double Click-through rate.
average_cpc double Average cost per click.
conversions_value double Total conversion value.
view_through_conversions long View-through conversions.

Event table schemas

call_view

Calls tracked from call extensions and call-only ads.

Column Data type Description
_databricks_row_id string Primary key. Synthetic per-row UUID.
customer_id long Customer account ID.
resource_name string Google Ads resource name (call ID).
ad_group_id long Ad group the call is attributed to.
campaign_id long Campaign the call is attributed to.
start_call_date_time string When the call started.
end_call_date_time string When the call ended.
caller_country_code string Caller country code.
caller_area_code string Caller area code.
type string Call type.
call_status string Call status.
call_tracking_display_location string Where the call tracking number was shown.
call_duration_seconds long Call duration in seconds.

lead_form_submission

Lead form submissions. Requires Standard or Admin access to the Google Ads account.

Column Data type Description
_databricks_row_id string Primary key. Synthetic per-row UUID.
customer_id long Customer account ID.
id string Lead form submission ID.
ad_group_id long Ad group the submission is attributed to.
campaign_id long Campaign the submission is attributed to.
resource_name string Google Ads resource name.
submission_date_time string When the form was submitted.
ad_id long Ad that generated the submission.
gclid string Google Click ID.
lead_form_submission_fields array<string> Submitted standard field values.
custom_lead_form_submission_fields array<string> Submitted custom field values.

local_services_lead

Local Services Ads leads. Only returns rows for Local Services accounts.

Column Data type Description
_databricks_row_id string Primary key. Synthetic per-row UUID.
customer_id long Customer account ID.
id long Lead ID.
creation_date_time string When the lead was created.
category_id string Service category ID.
service_id string Service ID.
locale string Lead locale.
lead_charged boolean Whether the advertiser was charged for the lead.
lead_status string Lead status.
lead_type string Lead type.
credit_details_credit_state string Credit state, if disputed.
credit_details_credit_state_last_update_date_time string When the credit state was last updated.
note_description string Note text.
note_edit_date_time string When the note was last edited.

local_services_lead_conversation

Conversations on Local Services Ads leads. Only returns rows for Local Services accounts.

Column Data type Description
_databricks_row_id string Primary key. Synthetic per-row UUID.
customer_id long Customer account ID.
id long Conversation ID.
event_date_time string When the conversation event occurred.
local_services_lead_id long ID of the parent lead.
conversation_channel string Conversation channel.
participant_type string Who initiated the conversation.
message_details_text string Message text.
message_details_attachment_urls array<string> Attachment URLs.
phone_call_details_call_duration_millis long Call duration in milliseconds.
phone_call_details_call_recording_url string Call recording URL.

Incremental ingestion

Report tables support incremental ingestion with a configurable lookback window. The connector uses the date column as the cursor column for tracking incremental updates. Resource tables and event tables are fully refreshed on each pipeline run.

For more information about incremental ingestion and lookback windows, see Google Ads connector concepts.

Custom report configuration options

Custom reports let you select any Google Ads resource with a combination of resource fields, segments, and metrics. The destination_table name is required.

Set source_table to custom_report and provide custom_report_options under connector_options.google_ads_options:

Option Required Description
resource Yes The Google Ads resource to query (for example, ad_group_ad, keyword_view, search_term_view). The resource must support metrics.
resource_fields No Resource fields to select, in fully qualified GAQL form (for example, ad_group_ad.ad.id, ad_group_ad.status). The resource name is added by default.
segments No Segment fields to select (for example, segments.date, segments.device). You must include at least one timeline segment — segments.date, segments.week, or segments.month — which becomes the table's incremental cursor.
metrics No Metric fields to select (for example, metrics.clicks, metrics.cost_micros).

Notes:

  • Destination columns omit the standard metrics. and segments. prefixes; for resource fields, periods are converted to underscores (for example, ad_group_ad.ad.id becomes ad_group_ad_ad_id).
  • The resource_name attribute is always included to identify each row.
  • The primary key is every selected resource_name plus all selected segments. That means the report resource's own resource_name, and one resource_name for each attributed resource — a resource other than the one named in resource, such as campaign on an ad_group_ad report. No other field is part of the primary key: resource_name already identifies the row, and keying on a value that changes upstream (such as campaign.name) would add a duplicate row instead of updating the existing one.
  • To select fields from an attributed resource, also select that resource's resource_name. For example, a report on ad_group_ad that selects campaign.id must also select campaign.resource_name. Google Ads returns one row per attributed value, so without that resource_name those rows share a primary key and the update fails. Pipeline planning checks this and lists the resource_name fields to add.
  • Ingestion for custom reports is incremental, based on the lookback window.
  • Google Ads retains daily- and weekly-segmented data for only 37 months. Custom reports using segments.date or segments.week cannot sync data older than this window; use segments.month for older data.
  • Pipeline planning validates field names against Google Ads. Missing timeline segments or invalid fields cause update failures. Use the validate_only setting to test configurations without moving data.
  • Last updated on