Skip to main content
Last updated on

Meta Ads connector concepts

Beta

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

The Meta Ads connector allows you to ingest advertising data from Meta Ads using Databricks Lakeflow Connect.

How does Meta Ads ingestion work?​

The connector retrieves data from the Meta Ads APIs and writes it to streaming tables. The ad_insights object uses the Insights API. The ads, ad_sets, and campaigns objects use the Marketing API. Each Meta Ads object corresponds to a table in your destination schema.

Connector data model​

The Meta Ads connector can ingest the following objects from your Meta Ads account:

  • ads: Individual ads in your campaigns
  • ad_sets: Ad sets that group ads together
  • campaigns: Top-level campaign objects
  • ad_images: Images used in ads
  • ad_insights: Performance metrics and analytics data
  • ad_creatives: Creative elements used in ads
  • custom_audiences: Custom audience definitions
  • ad_videos: Video assets used in ads
  • custom_conversions: Custom conversion event definitions

ad_insights object​

The ad_insights object provides performance metrics for your advertising campaigns. You can configure breakdowns and action breakdowns to analyze performance at different levels:

  • Granularity levels: account, campaign, adset, or ad
  • Breakdown dimensions: Age, gender, country, placement, device platform, and more
  • Action breakdowns: Action type, action destination, and other conversion-related dimensions
  • Time increment: all_days, monthly, or a custom number of days. The Insights API doesn't support hourly time increments.
  • Action report time: Whether the connector reports action statistics by impression, conversion, mixed, and lifetime.
  • Lookback window: How many days the connector reingests on each sync to capture late-arriving conversions.

For details on each option, see ad_insights configuration options.

Connector basics​

  • On the initial run of the pipeline, the connector ingests all of the data from the selected objects.
  • On subsequent pipeline runs, the connector ingests newly created or modified records using incremental ingestion.
  • The connector automatically transforms Meta Ads data types to Delta-compatible data types.
  • Each destination table is a streaming table, which is a Delta table with extra support for incremental data processing.

Incremental ingestion​

The Meta Ads connector uses incremental ingestion to improve pipeline efficiency. On the first run of your pipeline, it ingests all of the selected data from the source. On subsequent runs, the connector uses cursor-based change tracking to ingest only the data that changed since the prior run.

The connector uses the updated_time field (when available) as the cursor column to detect changes. For objects without an updated_time field, the connector uses full refresh ingestion.

Attribution settings​

By default, the Meta Ads connector uses your Meta Ads account's attribution settings when retrieving ad_insights data. You can override this by setting action_attribution_windows to specify one or more attribution windows (for example, 7d_click or 1d_view). For supported values, see Attribution windows.

Because conversion events can be reported after the impression or click occurs, data for recent dates might be incomplete until the configured attribution window closes. The connector automatically reingests this data on subsequent pipeline runs.

Supported advertising platforms​

In Beta, the connector supports only Facebook Ads. Instagram Ads aren't supported.

Authentication​

The connector uses OAuth 2.0 to authenticate with Meta Ads. You create a Meta app in the Meta Developer Portal and configure OAuth settings to allow Databricks to access your advertising data. The connection credentials are stored securely in Unity Catalog.

Next steps​

On this page