Field Mapping

Field mapping defines how columns from your source model map to fields in the destination. When you create a sync, SignalSmith presents a mapping editor where you pair each source column with a destination field.

How Field Mapping Works

Source Model Column  →  Destination Field
─────────────────────────────────────────
email                →  Email
first_name           →  FirstName
last_name            →  LastName
lifetime_value       →  Custom_LTV__c

Each row in the mapping editor has two sides:

• Source Column (left) — A column from your model’s SQL query result
• Destination Field (right) — A field in the destination object or table

Required Mapping Fields

Some destinations declare required mapping fields that must be present in every sync. These appear as pre-filled, non-removable rows in the mapping editor. You only need to select the source column.

Required fields vary by destination and object type. For example:

Conditional Required Fields

Required fields can be conditional on the destination configuration. For example, Salesforce requires LastName when syncing to the Contact object but requires Name when syncing to the Account object. The mapping editor automatically adjusts based on your destination settings.

Default Destination Fields

Many destinations provide a curated list of default destination fields that populate the right-side dropdown. These are common fields for the selected object type, so you do not need to type field names manually.

For example, when syncing to HubSpot Contacts, the dropdown includes: email, firstname, lastname, phone, company, and other standard HubSpot contact properties.

Schema Introspection

Destinations that support schema introspection automatically discover the available fields from the destination API. Instead of a static list, SignalSmith queries the destination to retrieve the actual fields, their types, and whether they are nullable.

Destinations with introspection support include:

• CRM: Salesforce, HubSpot, Dynamics 365, Zendesk, Freshdesk
• Warehouses: Snowflake, BigQuery, Databricks, PostgreSQL, MySQL, Redshift
• Other: Google Sheets

When introspection is available, the destination field dropdown shows live fields from your account, including any custom fields you have created.

Mapping Editor

Adding a Mapping

1. Click Add Field in the mapping editor
2. Select a source column from the left dropdown
3. Select or type a destination field on the right
4. Repeat for each field you want to sync

Removing a Mapping

Click the x button next to any mapping row to remove it. Required mapping fields cannot be removed.

Field Type Compatibility

SignalSmith automatically handles type conversions between source and destination:

Primary Key / Identifier Fields

For upsert and update sync modes, you must designate at least one field as the identifier or primary key. This field is used to match source records against existing destination records.

Common identifier fields:

• Email — For CRM contacts and marketing tools
• External ID — For platforms like Braze and Intercom
• Customer ID — For advertising audience matching
• Record ID — For database primary keys

Destinations Without Field Mapping

Some destinations do not support field mapping because they use a fixed payload format. These include:

• Advertising platforms (Google Ads, LinkedIn Ads, TikTok Ads, Snapchat Ads, etc.) — Data is sent in the platform’s audience upload format
• Streaming destinations (Kafka, Kinesis, Pub/Sub, SQS) — Entire rows are serialized as JSON messages
• GA4 — Events are sent using the Measurement Protocol format
• Webhook — The full row is sent as a JSON payload
• Slack — Messages are generated from a template with {{field_name}} placeholders

For these destinations, all columns from your model are included automatically.