Implementation:Mage ai Mage ai Twitter Ads Transform

Knowledge Sources	Mage Integrations Twitter Ads API
Domains	Data_Integration, Twitter_Ads, Transform
Last Updated	2026-02-09 00:00 GMT

Overview

Data transformation functions for the Mage Twitter Ads source connector, handling report data denormalization from time-series arrays into flat records and MD5 hash key generation for dimensions.

Description

This module provides two transformation functions used during the Twitter Ads sync process:

• transform_report - The main report transformation function. Twitter Ads analytics API returns metric values as time-series arrays where each index corresponds to a time interval. This function denormalizes the data by:

 1. Extracting request parameters (entity, granularity, placement, segmentation_type, country, platform, start_time, end_time)
 2. Computing time intervals based on granularity (DAY = 1 day, HOUR = 1 hour, TOTAL = 0 days)
 3. Iterating through entity ID records and their associated data
 4. For each time interval, extracting the indexed value from each metric array
 5. Grouping metrics into nested categories: billing (billed_*), media (media_*), video (video_*), web_conversion (conversion_*), mobile_conversion (mobile_conversion_*), and engagement (everything else)
 6. Generating an MD5 hash key (__sdc_dimensions_hash_key) from sorted JSON dimensions for deduplication
 7. Only appending records that have at least one non-null metric value

• transform_record - A pass-through function for endpoint records (currently returns the record unmodified).

• hash_data - Utility that creates an MD5 hexdigest from a data representation.

Usage

Called during the sync_report process to transform raw Twitter Ads analytics API responses into flat, timestamped records.

Code Reference

Source Location

• Repository: mage-ai
• File: mage_integrations/mage_integrations/sources/twitter_ads/tap_twitter_ads/transform.py
• Lines: 1-166

Signature

def hash_data(data):
def transform_report(report_name, report_data, account_id):
def transform_record(stream_name, record):

Import

from mage_integrations.sources.twitter_ads.tap_twitter_ads.transform import (
    transform_report, transform_record,
)

I/O Contract

Key Functions

Function	Inputs	Output	Description
transform_report(report_name, report_data, account_id)	report_name (str), report_data (dict), account_id (str)	list[dict]	Denormalizes time-series report data into flat records with dimension hash keys
transform_record(stream_name, record)	stream_name (str), record (dict)	dict	Pass-through transformation for endpoint records
hash_data(data)	data (any)	str	MD5 hexdigest of data representation

Report Record Structure

Each transformed report record contains:

Field	Type	Description
__sdc_dimensions_hash_key	str	MD5 hash of sorted dimension JSON for deduplication
start_time	str	ISO datetime string for interval start
end_time	str	ISO datetime string for interval end
dimensions	dict	Contains report_name, account_id, entity, entity_id, granularity, placement, segmentation_type, segment_name, segment_value, country, platform
billing	dict	Metrics prefixed with billed_
media	dict	Metrics prefixed with media_
video	dict	Metrics prefixed with video_
engagement	dict	All other metrics
web_conversion	dict	Metrics prefixed with conversion_
mobile_conversion	dict	Metrics prefixed with mobile_conversion_

Granularity Intervals

Granularity	Interval
DAY	1 day
HOUR	1 hour
TOTAL	0 days (single interval)

Usage Examples

from mage_integrations.sources.twitter_ads.tap_twitter_ads.transform import transform_report

report_records = transform_report(
    report_name='campaign_report',
    report_data=api_response,
    account_id='abc123',
)
for record in report_records:
    singer.write_record('campaign_report', record)

Related Pages

Implements Principle

• Principle:Mage_ai_Mage_ai_Singer_Message_Emission

Requires Environment

• Environment:Mage_ai_Mage_ai_Python_3_9_Runtime