Skip to main content
Field mapping defines how each column from your warehouse SQL maps to a destination field. Clear mappings reduce runtime errors, make audits easier, and keep sync behavior stable when analysts rename warehouse columns (use views or aliases to shield the sync from renames).

​
Mapping strategies

Map each warehouse column directly to a single destination field. Use this when names and semantics already align (email → Email, mrr_usd → MonthlyRevenue).
You can reorder mappings for readability; execution order follows destination API requirements, not the order shown in the UI.

​
Type conversion

Planasonix coerces common warehouse types into types the destination expects:
Warehouse typeTypical destination handling
String / VARCHARTrimmed text; respect max length on the API
Integer / BIGINTWhole numbers; watch for overflow on 32-bit fields
Numeric / DECIMALRounded or scaled per field metadata
Booleantrue/false or vendor-specific enums
Timestamp / TZNormalized to UTC or destination-local rules per connector
When coercion fails for a row, that row is reported as an error or routed to the dead letter queue depending on sync settings.
Cast explicitly in SQL when you need stable formatting: dates as ISO-8601 strings, booleans as 0/1 only if the API documents that convention.

​
Required fields

Destinations mark some fields as required for create or upsert operations. The mapper highlights them. Before the first run:
  1. Ensure your SQL returns a non-null value for each required mapped field.
  2. Confirm identifiers exist for update and upsert modes.
  3. Preview a sample batch to catch nulls and type mismatches early.
Use COALESCE or CASE in SQL to substitute defaults only when the business approves; do not mask missing data silently if compliance requires explicit nulls.
Check whether the connector expects delimited strings, native arrays, or JSON arrays, and shape the warehouse column accordingly.

​
Validation and testing

After you save mappings, run a limited preview against a handful of keys, then a full sync in a sandbox destination when possible. Compare counts between warehouse and destination using the same key definition you used in the sync.

Syncs

SQL source configuration and sync modes.

Monitoring

Find and fix mapping-related errors in run logs.