LinkedIn Ads connector reference

Beta

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Databricks previews.

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

Supported tables

The LinkedIn Ads connector supports twelve tables in two categories:

• Entity tables: Configuration data about your ad accounts, such as campaigns and creatives. These tables are fully refreshed on each pipeline update.
• Prebuilt report tables: Performance and demographic metrics from LinkedIn's adAnalytics endpoint. These tables support incremental ingestion.

Each table lives in either the default namespace or a per-account namespace named after the sponsored ad-account ID. See Source namespaces.

Entity tables

Table name	Namespace	Primary key	Description
account_history	default	id	Sponsored ad accounts the authorizing token can reach.
campaign_group_history	Per-account	id	Campaign groups, including budget and objective settings.
campaign_history	Per-account	id	Campaigns, including targeting criteria, budgets, and run schedule.
creative_history	Per-account	id	Creatives, including content and review status.
account_user_history	Per-account	account, user	Per-user roles on the ad account.

Table name	Namespace	Primary key	Description
account_history	default	id	Sponsored ad accounts the authorizing token can reach.
campaign_group_history	Per-account	id	Campaign groups, including budget and objective settings.
campaign_history	Per-account	id	Campaigns, including targeting criteria, budgets, and run schedule.
creative_history	Per-account	id	Creatives, including content and review status.
account_user_history	Per-account	account, user	Per-user roles on the ad account.

Prebuilt report tables

All seven reports are per-account and support incremental ingestion.

Table name	Granularity	Primary key	Pivot
ad_analytics_by_campaign_report	Daily	campaign_id, day	CAMPAIGN
ad_analytics_by_creative_report	Daily	creative_id, day	CREATIVE
monthly_ad_analytics_by_member_company_size_report	Monthly	campaign_id, member_company_size, month	MEMBER_COMPANY_SIZE
monthly_ad_analytics_by_member_country_report	Monthly	campaign_id, member_country, month	MEMBER_COUNTRY_V2
monthly_ad_analytics_by_member_industry_report	Monthly	campaign_id, member_industry, month	MEMBER_INDUSTRY
monthly_ad_analytics_by_member_job_function_report	Monthly	campaign_id, member_job_function, month	MEMBER_JOB_FUNCTION
monthly_ad_analytics_by_member_seniority_report	Monthly	campaign_id, member_seniority, month	MEMBER_SENIORITY

Table name	Granularity	Primary key	Pivot
ad_analytics_by_campaign_report	Daily	campaign_id, day	CAMPAIGN
ad_analytics_by_creative_report	Daily	creative_id, day	CREATIVE
monthly_ad_analytics_by_member_company_size_report	Monthly	campaign_id, member_company_size, month	MEMBER_COMPANY_SIZE
monthly_ad_analytics_by_member_country_report	Monthly	campaign_id, member_country, month	MEMBER_COUNTRY_V2
monthly_ad_analytics_by_member_industry_report	Monthly	campaign_id, member_industry, month	MEMBER_INDUSTRY
monthly_ad_analytics_by_member_job_function_report	Monthly	campaign_id, member_job_function, month	MEMBER_JOB_FUNCTION
monthly_ad_analytics_by_member_seniority_report	Monthly	campaign_id, member_seniority, month	MEMBER_SENIORITY

Data type conventions

The following conventions apply across all destination tables:

• All columns are nullable except the primary-key columns.
• createdAt and lastModifiedAt are LinkedIn's audit timestamps, ingested as epoch-millisecond long values rather than as timestamps.
• targetingCriteria, content, and inlineContent are ingested as variant columns. The connector enables Delta's Variant table feature on the tables that carry them.
• Money columns are decimal and are denominated in the currency named by the column. For example, cost_in_usd is in US dollars and cost_in_local_currency is in the ad account's currency.

Entity table schemas

account_history

Column	Spark type
id	long (primary key)
name	string
currency	string
type	string
status	string
reference	string
servingStatuses	array<string>
notifiedOnCampaignOptimization	boolean
notifiedOnCreativeApproval	boolean
notifiedOnCreativeRejection	boolean
notifiedOnEndOfCampaign	boolean
notifiedOnNewFeaturesEnabled	boolean
test	boolean
version	struct<versionTag: string>
createdAt	long
lastModifiedAt	long

Column	Spark type
id	long (primary key)
name	string
currency	string
type	string
status	string
reference	string
servingStatuses	array<string>
notifiedOnCampaignOptimization	boolean
notifiedOnCreativeApproval	boolean
notifiedOnCreativeRejection	boolean
notifiedOnEndOfCampaign	boolean
notifiedOnNewFeaturesEnabled	boolean
test	boolean
version	struct<versionTag: string>
createdAt	long
lastModifiedAt	long

campaign_group_history

Column	Spark type
id	long (primary key)
account	string
name	string
status	string
objectiveType	string
allowedCampaignTypes	array<string>
servingStatuses	array<string>
runSchedule	struct<start: long, end: long>
totalBudget	struct<amount: decimal(19,2), currencyCode: string>
dailyBudget	decimal(19,2)
budgetOptimization	struct<bidStrategy: string, budgetOptimizationStrategy: string>
backfilled	boolean
test	boolean
createdAt	long
lastModifiedAt	long

Column	Spark type
id	long (primary key)
account	string
name	string
status	string
objectiveType	string
allowedCampaignTypes	array<string>
servingStatuses	array<string>
runSchedule	struct<start: long, end: long>
totalBudget	struct<amount: decimal(19,2), currencyCode: string>
dailyBudget	decimal(19,2)
budgetOptimization	struct<bidStrategy: string, budgetOptimizationStrategy: string>
backfilled	boolean
test	boolean
createdAt	long
lastModifiedAt	long

note

On this table, dailyBudget is a bare decimal(19,2) rather than a money struct. On campaign_history, the same column name is a struct<amount, currencyCode>. This asymmetry reflects the shape LinkedIn's API returns for each resource.

campaign_history

Column	Spark type
id	long (primary key)
account	string
campaignGroup	string
associatedEntity	string
name	string
type	string
status	string
costType	string
format	string
objectiveType	string
optimizationTargetType	string
creativeSelection	string
pacingStrategy	string
politicalIntent	string
audienceExpansionEnabled	boolean
offsiteDeliveryEnabled	boolean
connectedTelevisionOnly	boolean
test	boolean
servingStatuses	array<string>
locale	struct<country: string, language: string>
offsitePreferences	struct<iabCategories: array<string>, publisherRestrictionFiles: array<string>>
runSchedule	struct<start: long, end: long>
dailyBudget	struct<amount: decimal(19,2), currencyCode: string>
totalBudget	struct<amount: decimal(19,2), currencyCode: string>
unitCost	struct<amount: decimal(19,2), currencyCode: string>
targetingCriteria	variant
version	struct<versionTag: string>
createdAt	long
lastModifiedAt	long

Column	Spark type
id	long (primary key)
account	string
campaignGroup	string
associatedEntity	string
name	string
type	string
status	string
costType	string
format	string
objectiveType	string
optimizationTargetType	string
creativeSelection	string
pacingStrategy	string
politicalIntent	string
audienceExpansionEnabled	boolean
offsiteDeliveryEnabled	boolean
connectedTelevisionOnly	boolean
test	boolean
servingStatuses	array<string>
locale	struct<country: string, language: string>
offsitePreferences	struct<iabCategories: array<string>, publisherRestrictionFiles: array<string>>
runSchedule	struct<start: long, end: long>
dailyBudget	struct<amount: decimal(19,2), currencyCode: string>
totalBudget	struct<amount: decimal(19,2), currencyCode: string>
unitCost	struct<amount: decimal(19,2), currencyCode: string>
targetingCriteria	variant
version	struct<versionTag: string>
createdAt	long
lastModifiedAt	long

creative_history

Column	Spark type
id	string (primary key)
account	string
campaign	string
name	string
intendedStatus	string
isServing	boolean
isTest	boolean
servingHoldReasons	array<string>
content	variant
inlineContent	variant
review	struct<status: string, rejectionReasons: array<string>>
leadgenCallToAction	struct<destination: string, label: string>
createdBy	string
lastModifiedBy	string
createdAt	long
lastModifiedAt	long

Column	Spark type
id	string (primary key)
account	string
campaign	string
name	string
intendedStatus	string
isServing	boolean
isTest	boolean
servingHoldReasons	array<string>
content	variant
inlineContent	variant
review	struct<status: string, rejectionReasons: array<string>>
leadgenCallToAction	struct<destination: string, label: string>
createdBy	string
lastModifiedBy	string
createdAt	long
lastModifiedAt	long

account_user_history

Column	Spark type
account	string (primary key)
user	string (primary key)
role	string
createdAt	long
lastModifiedAt	long

Column	Spark type
account	string (primary key)
user	string (primary key)
role	string
createdAt	long
lastModifiedAt	long

Report table schemas

Every report carries the same 114 metric columns plus its own leading key columns. Metric columns are all nullable, because LinkedIn omits all-zero rows and leaves absent metrics null.

All seven reports carry a _sync_timestamp column, which is part of each report's cursor. LinkedIn revises a period's metrics in place as late conversions arrive, so a re-fetched row keeps the same day or month. Without a strictly increasing companion value, the destination MERGE would treat the revision as unchanged and drop it. The timestamp advances on every update, so the newer version always wins.

Daily reports

Each daily report carries exactly one entity column, named after the dimension it pivots on.

Column	Spark type	Notes
Entity column	long (primary key)	The pivot value. See the following table.
day	string (primary key)	ISO date, yyyy-MM-dd.
_sync_timestamp	timestamp	Generated by the connector on each update.
114 metric columns	long, decimal, or double

Column	Spark type	Notes
Entity column	long (primary key)	The pivot value. See the following table.
day	string (primary key)	ISO date, yyyy-MM-dd.
_sync_timestamp	timestamp	Generated by the connector on each update.
114 metric columns	long, decimal, or double

Report	Entity column	Spark type	Value form
ad_analytics_by_campaign_report	campaign_id	long	Bare ID from the pivot URN.
ad_analytics_by_creative_report	creative_id	long	Bare ID from the pivot URN.

Report	Entity column	Spark type	Value form
ad_analytics_by_campaign_report	campaign_id	long	Bare ID from the pivot URN.
ad_analytics_by_creative_report	creative_id	long	Bare ID from the pivot URN.

Monthly member-demographic reports

Each demographic report carries exactly one member column, named after the dimension it pivots on.

Column	Spark type	Notes
campaign_id	long (primary key)	Attributed from the campaign the connector queried.
Member dimension column	long or string (primary key)	The pivot value. See the following table.
month	string (primary key)	Zero-padded year and month, yyyy-MM.
_sync_timestamp	timestamp	Generated by the connector on each update.
114 metric columns	long, decimal, or double

Column	Spark type	Notes
campaign_id	long (primary key)	Attributed from the campaign the connector queried.
Member dimension column	long or string (primary key)	The pivot value. See the following table.
month	string (primary key)	Zero-padded year and month, yyyy-MM.
_sync_timestamp	timestamp	Generated by the connector on each update.
114 metric columns	long, decimal, or double

Report	Member column	Spark type	Value form
monthly_ad_analytics_by_member_company_size_report	member_company_size	string	Literal enum, such as SIZE_11_TO_50.
monthly_ad_analytics_by_member_country_report	member_country	long	Bare ID from the pivot URN.
monthly_ad_analytics_by_member_industry_report	member_industry	long	Bare ID from the pivot URN.
monthly_ad_analytics_by_member_job_function_report	member_job_function	long	Bare ID from the pivot URN.
monthly_ad_analytics_by_member_seniority_report	member_seniority	long	Bare ID from the pivot URN.

Report	Member column	Spark type	Value form
monthly_ad_analytics_by_member_company_size_report	member_company_size	string	Literal enum, such as SIZE_11_TO_50.
monthly_ad_analytics_by_member_country_report	member_country	long	Bare ID from the pivot URN.
monthly_ad_analytics_by_member_industry_report	member_industry	long	Bare ID from the pivot URN.
monthly_ad_analytics_by_member_job_function_report	member_job_function	long	Bare ID from the pivot URN.
monthly_ad_analytics_by_member_seniority_report	member_seniority	long	Bare ID from the pivot URN.

Metric columns

All seven reports return the same metric set. Column names are snake_case renamings of LinkedIn's camelCase metric names. For example, costInLocalCurrency becomes cost_in_local_currency. The following table groups the metrics by theme:

Group	Example columns
Core performance	impressions, clicks, cost_in_local_currency, cost_in_usd, approximate_member_reach, audience_penetration
Engagement	likes, comments, shares, reactions, follows, total_engagements, other_engagements, comment_likes
Clicks by surface	landing_page_clicks, company_page_clicks, text_url_clicks, headline_clicks, card_clicks, ad_unit_clicks, action_clicks, download_clicks, subscription_clicks
Video	video_views, video_starts, video_completions, video_first_quartile_completions, video_midpoint_completions, video_third_quartile_completions, video_watch_time, average_video_watch_time
Events	event_views, event_views_over_15_seconds, event_views_over_30_seconds, event_views_over_2_minutes, event_watch_time, cost_per_event_view
Documents	document_completions, document_first_quartile_completions, document_midpoint_completions, document_third_quartile_completions
Leads, registrations, and jobs	one_click_leads, one_click_lead_form_opens, qualified_leads, cost_per_qualified_lead, valid_work_email_leads, talent_leads, registrations, post_click_registrations, post_view_registrations, post_click_job_applications, post_view_job_apply_clicks
Conversions	external_website_conversions, conversion_value_in_local_currency
Viral	Every viral_-prefixed counterpart of the metrics above, such as viral_impressions, viral_clicks, viral_likes, viral_video_views, and viral_one_click_leads

Group	Example columns
Core performance	impressions, clicks, cost_in_local_currency, cost_in_usd, approximate_member_reach, audience_penetration
Engagement	likes, comments, shares, reactions, follows, total_engagements, other_engagements, comment_likes
Clicks by surface	landing_page_clicks, company_page_clicks, text_url_clicks, headline_clicks, card_clicks, ad_unit_clicks, action_clicks, download_clicks, subscription_clicks
Video	video_views, video_starts, video_completions, video_first_quartile_completions, video_midpoint_completions, video_third_quartile_completions, video_watch_time, average_video_watch_time
Events	event_views, event_views_over_15_seconds, event_views_over_30_seconds, event_views_over_2_minutes, event_watch_time, cost_per_event_view
Documents	document_completions, document_first_quartile_completions, document_midpoint_completions, document_third_quartile_completions
Leads, registrations, and jobs	one_click_leads, one_click_lead_form_opens, qualified_leads, cost_per_qualified_lead, valid_work_email_leads, talent_leads, registrations, post_click_registrations, post_view_registrations, post_click_job_applications, post_view_job_apply_clicks
Conversions	external_website_conversions, conversion_value_in_local_currency
Viral	Every viral_-prefixed counterpart of the metrics above, such as viral_impressions, viral_clicks, viral_likes, viral_video_views, and viral_one_click_leads

Rates and durations are double and counts are long. For the authoritative meaning of each metric, see LinkedIn's Ads Reporting schema.

Report configuration options

Configure reports per table through connector_options.linkedin_ads_options:

Option	Default	Bounds	Purpose
sync_start_date	Two years before today	Must not be in the future, and must not be older than the report's retention horizon	The first date the initial update fetches
lookback_window_days	7	0 to 365	How far back each incremental update re-reads to catch revisions

Option	Default	Bounds	Purpose
sync_start_date	Two years before today	Must not be in the future, and must not be older than the report's retention horizon	The first date the initial update fetches
lookback_window_days	7	0 to 365	How far back each incremental update re-reads to catch revisions

Retention horizons differ by report family. These are LinkedIn's limits, not the connector's:

Family	Retention	Effect
Daily performance reports	10 years	A sync_start_date earlier than 10 years before today is rejected.
Monthly member-demographic reports	2 years	A sync_start_date earlier than 2 years before today is rejected.

Family	Retention	Effect
Daily performance reports	10 years	A sync_start_date earlier than 10 years before today is rejected.
Monthly member-demographic reports	2 years	A sync_start_date earlier than 2 years before today is rejected.

Additional resources

• LinkedIn Ads connector concepts
• LinkedIn Ads connector limitations
• Ingest data from LinkedIn Ads