LinkedIn Ads connector reference

Important

This feature is in Beta. Workspace admins can control access to this feature from the Previews page. See Manage Azure 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.

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

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

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

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

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

account_user_history

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
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
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

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

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.

Additional resources

  • Last updated on