Trillboards Attribution Data Model Ontology

version 1.0.0

Machine-readable schema definitions for the 6-layer DOOH attribution data model. These schemas map directly to PostgreSQL tables created in migrations 092-096.

Data Flow: From Signal to Insight

Layer 1: Signal Ingestion
  device_signals (Intuizi mobile pings) + poi_reference (brand locations)
      |
Layer 2: Exposure Matching
  exposure_device_matches (PostGIS ST_DWithin: device near screen during ad play)
      |
Layer 3: Attention Enrichment
  attention_exposure_matches (FEIN edge AI: face count, gaze, emotion per exposure)
      |
Layer 4: Identity Resolution
  identity_nodes + identity_edges + household_clusters (cross-device graph)
      |
Layer 5: Attribution
  touchpoint_events + attribution_chains (multi-touch credit across channels)
      |
Layer 6: Measurement
  incrementality_experiments + incrementality_results (Bayesian uplift)
  creative_attribution_performance (creative x outcome correlation)
  campaign_attribution_summary (daily rollup)

Data Handling

• Attribution tables key each mobile device by a hash of its MAID (maid_hash). The identity graph links MAIDs to the device keys sensed at screens and, through them, to the person identifiers built from face-identity templates
• FEIN inference runs on the device. The screen sends Trillboards a record for each detected person, speech transcripts, the radio identifiers of nearby devices and its GPS position, and sends selected camera frames for cloud analysis
• Attribution tables join hashed MAIDs, with each device's location at the time of the match, to screen exposures
• Partitioned tables with 90-400 day retention and automatic partition pruning; Trillboards' encrypted archive keeps the data with no scheduled deletion

Partitioning Strategy

Three tables are range-partitioned by timestamp for performance:

• device_signals — partitioned by observed_at (monthly, 90-day hot)
• device_visitation — partitioned by visited_at (monthly, 90-day hot)
• exposure_device_matches — partitioned by matched_at (monthly, 400-day)
• attention_exposure_matches — partitioned by matched_at (monthly)
• touchpoint_events — partitioned by occurred_at (monthly)

Schemas

16 schemas. Every one is derived from docs/openapi/attribution-data-models.yaml at request time.

AttentionCampaignMetrics · AttentionExposureMatch · AttributionChain · CampaignAttributionSummary · CreativeAttributionPerformanceRecord · DataProviderIngestionLog · DeviceSignal · DeviceVisitation · ExposureDeviceMatch · HouseholdCluster · IdentityEdge · IdentityNode · IncrementalityExperiment · IncrementalityResultRecord · POIReference · TouchpointEvent

AttentionCampaignMetrics

Daily rollup of attention-weighted campaign metrics. One row per campaign + creative + date. Used for aCPM calculations and attention timeseries visualizations.

Table: attention_campaign_metrics Migration: 243_create_attention_attribution_tables.sql

AttentionExposureMatch

Exposure match enriched with FEIN edge AI inference signals. Joins exposure_device_matches with inference_outcomes to attach attention, emotion, and demographic data to each exposure.

What the row MODELS, stated precisely: a device-to-play match from exposure_device_matches, carrying the edge-AI inference recorded for that play — face count, gaze, emotion classification and dwell. It is a join, not an independent observation: the exposure leg and the attention leg are produced by different subsystems, and a row exists only where both fired for the same play.

Population is a property of the deployment, not of the schema. Before building on any field here, count the table for your own environment and check matched_at freshness — a schema contract cannot tell you whether the pipeline that fills it is running.

Table: attention_exposure_matches (partitioned monthly by matched_at) Migration: 243_create_attention_attribution_tables.sql

AttributionChain

Complete user journey from DOOH exposure to conversion. Links multiple touchpoint_events into a sequence with multi-touch credit allocation.

Table: attribution_chains Migration: 096

CampaignAttributionSummary

Daily rollup of campaign-level attribution metrics. This is the aggregate view consumed by the campaign summary endpoint.

Table: campaign_attribution_summary Migration: 093

CreativeAttributionPerformanceRecord

Links creative execution to attribution outcomes. One row per campaign + creative + variant + date.

Answers: "Which creative x venue x daypart x weather combination drives the most store visits at the lowest cost?"

Table: creative_attribution_performance Migration: 096

DataProviderIngestionLog

Audit trail for batch data ingestion runs. Tracks file processing status, row counts, and rejection reasons.

Table: data_provider_ingestion_log Migration: 092

DeviceSignal

Mobile device location observation from Intuizi. Each row = one device location ping (MAID + lat/lng + timestamp). MAIDs are stored as SHA-256 hashes (maid_hash).

Table: device_signals (partitioned monthly by observed_at) Migration: 092

DeviceVisitation

Observed visit to a POI by a mobile device (from Intuizi visitation data).

This table holds TWO different attribution legs and visit_role is the discriminator. Always filter by it. conversion_poi rows are the outcome leg — the device visited the advertiser's location. screen_exposure rows are the exposure leg — the device was near one of our screens. They answer opposite halves of the question, and a query that omits the predicate silently mixes them.

The column is NOT NULL DEFAULT 'conversion_poi' with a CHECK constraint (migration 20260618061000_add_device_visitation_visit_role.sql), and the table carries a dedicated partial index per role, which is the clearest statement that both are expected to be queried separately.

visit_role was absent from this schema entirely until 2026-09-01, so the document described the whole table as the outcome leg.

Table: device_visitation (partitioned monthly by visited_at) Migration: 092 (visit_role added in 20260618061000_add_device_visitation_visit_role.sql)

ExposureDeviceMatch

Core truth table: device X was near screen Y during ad play Z. Created by the exposure matching service using PostGIS ST_DWithin to join device_signals with play_logs based on spatial and temporal proximity.

Table: exposure_device_matches (partitioned monthly by matched_at) Migration: 093

HouseholdCluster

Pre-computed household grouping from co-location analysis. Multiple MAIDs that consistently appear at the same location (same geohash, same time windows) are clustered into households.

Table: household_clusters Migration: 243_create_attention_attribution_tables.sql

IdentityEdge

Relationship between two identity nodes in the graph.

Table: identity_edges Migration: 243_create_attention_attribution_tables.sql

IdentityNode

Vertex in the identity graph. Each node represents a device, household, FEIN cluster, pixel visitor, or other identity type.

Table: identity_nodes Migration: 243_create_attention_attribution_tables.sql

IncrementalityExperiment

Experiment definition for causal incrementality measurement. Supports geo-holdout, ghost ads, PSA control, and matched market designs.

Table: incrementality_experiments Migration: 096

IncrementalityResultRecord

Daily measurement result for an incrementality experiment. Contains both Bayesian and frequentist statistical results.

Table: incrementality_results Migration: 096

POIReference

Advertiser/brand point-of-interest location from Intuizi. Used as the "destination" in footfall attribution — did an exposed device later visit one of these POIs?

The catalogue is scoped to the brands under active measurement, not to Intuizi's whole POI universe. A volume figure is deliberately not quoted here: this document is a schema contract, and the previous "~500K locations" parenthetical overstated the live table by more than an order of magnitude. Count poi_reference if you need the current size.

Table: poi_reference Migration: 092

TouchpointEvent

Normalized cross-channel event from any attribution source. All channels (DOOH, mobile, web, app, store, purchase) are represented in a single table for unified multi-touch attribution.

Table: touchpoint_events (partitioned monthly by occurred_at) Migration: 096