Reddit Ads connector concepts

Important

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

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

How does Reddit Ads ingestion work?

The connector retrieves data from the Reddit Ads API and writes it to streaming tables. Each Reddit Ads object corresponds to a table in your destination schema. The connector supports two types of tables:

  • Entity tables: Configuration data about your Reddit Ads account, such as campaigns, ad groups, and ads. Entity tables are fully refreshed on each pipeline run and don't support history tracking (SCD type 2).
  • Report tables: Performance metrics, such as impressions, clicks, and spend. Report tables support incremental ingestion with a configurable lookback window to capture late-arriving data and attribution updates.

Connector data model

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

  • ad_account: The ad accounts accessible to the authenticated user
  • campaign, ad_group, ad: Entity objects that describe your account structure
  • Report tables (for example, campaign_report, ad_group_report, ad_report): Prebuilt performance metrics at each level of the account hierarchy
  • custom_report: A user-defined report with a configurable breakdown and field combination

For the full list of supported tables and their schemas, see Reddit Ads connector reference.

Source schemas

Reddit Ads organizes tables into source schemas (namespaces) that correspond to the account hierarchy:

  • The ad_account entity table lives in the special default schema. It lists all ad accounts accessible to the authenticated user.
  • All other tables — campaign, ad_group, ad, and all report tables — live under a schema named by the ad account ID (for example, t2_abc123). This schema name is the value you set as source_schema in your pipeline spec.

One pipeline can ingest from multiple ad account schemas, and each source_schema entry maps to one ad account.

Report tables

Report tables provide performance metrics for your advertising campaigns. The connector serves report data from approximately the last 24 months. Regardless of the sync_start_date parameter, report tables cannot retrieve data older than this window — requests for older data are rejected by Reddit. This limit applies to report tables only, not entity tables.

Custom reports

The custom_report object lets you define your own report with a configurable breakdown and field combination. You control the configuration using custom_report_options, and each custom report ingests into a separate destination_table. The breakdowns list must include at least one time dimension (DATE or HOUR), which becomes the table's incremental cursor.

For supported breakdowns and fields, see Custom report breakdowns and fields.

Connector basics

  • On the initial run of the pipeline, the connector ingests historical data from the selected objects.
  • On subsequent pipeline runs, the connector ingests newly created or modified records in report tables using incremental ingestion, and fully refreshes entity tables.
  • The connector automatically transforms Reddit 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

By default, the connector ingests two years of historical data for report tables on the first run. You can configure this using the sync_start_date parameter, which accepts a date in YYYY-MM-DD format. The parameter applies only to the first run. After the first checkpoint, changing it has no effect without a full refresh.

On subsequent runs, the connector uses incremental ingestion for report tables. Because Reddit Ads metrics can change after they are first reported — for example, when conversions or attribution are recalculated — the connector re-reads the most recent days of data on every sync. Entity tables are fully refreshed on each run.

Attribution and lookback windows

To capture late-arriving conversions and attribution updates, the connector re-reads a configurable number of recent days on every sync. By default, it re-reads the last 30 days. You can change this with the lookback_window_days parameter (any value from 1 to 30).

Set lookback_window_days to match your organization's conversion attribution window. For example, if your organization uses a 14-day attribution window, set lookback_window_days: 14.

Time zone

Report date boundaries are interpreted in the ad account's own time zone. The connector reads this automatically from the account. You do not set a time zone in the pipeline spec.

Currency

Monetary columns — for example, spend, cpc, bid_value — are stored in the ad account's currency as decimal amounts (for example, 12.34), not in micros. The account's currency code is available in the ad_account.currency column and in the report currency column.

Authentication

The connector uses OAuth 2.0 user-to-machine (U2M) authentication with PKCE to authenticate with Reddit Ads. You create a developer application in Reddit Ads Business Manager and configure OAuth settings to allow Azure Databricks to access your advertising data. The adsread scope is set automatically by Azure Databricks. Connection credentials are stored securely in Unity Catalog.

Additional resources

  • Last updated on