Data Mapping

Configure how data transforms between external systems and Hyperfold.

Overview

Data mapping defines how fields from external systems (Shopify, Salesforce, etc.) translate to Hyperfold's unified schema. Proper mapping ensures agents have consistent, clean data regardless of the source system.

Hyperfold auto-detects common field mappings. Review and customize mappings for your specific data structure.

Field Mapping

# Define field mappings between systems
$ hyperfold integrate map shopify \
  --source=product \
  --target=catalog
AUTO-DETECTED MAPPINGS
SOURCE (Shopify)           TARGET (Hyperfold)      CONFIDENCE
title                      name                    100%
body_html                  description             100%
vendor                     brand                   95%
product_type               category                90%
variants.price             base_price              100%
variants.sku               sku                     100%
variants.inventory_qty     inventory               100%
images[0].src              primary_image           90%
tags                       semantic_tags           85%
Accept auto-mappings? [Y/n] y
# Manual field mapping
$ hyperfold integrate map shopify \
  --source=product \
  --target=catalog \
  --mapping='[
    {"source": "title", "target": "name"},
    {"source": "body_html", "target": "description", "transform": "strip_html"},
    {"source": "variants.price", "target": "base_price", "transform": "cents_to_dollars"},
    {"source": "metafields.custom.floor_price", "target": "negotiation.floor_price"}
  ]'

Mapping Options

Option	Description
`source`	Field path in source system (dot notation)
`target`	Field path in Hyperfold schema
`transform`	Transformation to apply during sync
`default`	Default value if source is null

Transformations

# Available transformations
$ hyperfold integrate map --list-transforms
TRANSFORMATIONS
STRING
  uppercase            "hello" → "HELLO"
  lowercase            "HELLO" → "hello"
  trim                 " hello " → "hello"
  truncate(n)          "hello world" → "hello..." (n=8)
  strip_html           "<p>hello</p>" → "hello"
NUMERIC
  round(n)             3.14159 → 3.14 (n=2)
  cents_to_dollars     1299 → 12.99
  dollars_to_cents     12.99 → 1299
DATE/TIME
  format(pattern)      ISO → "Jan 20, 2025"
  timezone(tz)         UTC → America/Los_Angeles
ARRAY
  split(delim)         "a,b,c" → ["a","b","c"]
  join(delim)          ["a","b"] → "a, b"
SPECIAL
  lookup(table)        "gold" → 3 (via lookup table)
  default(value)       null → "default"
  boolean              "yes" → true

Computed Fields

Create new fields by combining or processing source data:

# Computed fields from multiple sources
$ hyperfold integrate map shopify \
  --source=product \
  --target=catalog \
  --computed='[
    {"target": "full_name", "expression": "{{vendor}} {{title}}"},
    {"target": "search_text", "expression": "concat(title, \" \", vendor, \" \", join(tags, \" \"))"},
    {"target": "margin_percent", "expression": "((variants.price - metafields.cost) / variants.price) * 100"},
    {"target": "in_stock", "expression": "variants.inventory_quantity > 0"}
  ]'
# Conditional computed fields
$ hyperfold integrate map shopify \
  --computed='[
    {"target": "tier_discount", "expression": "case(customer.tier, {\"gold\": 0.10, \"silver\": 0.05, \"default\": 0})"},
    {"target": "shipping_class", "expression": "if(weight > 50, \"freight\", if(fragile, \"special\", \"standard\"))"}
  ]'

Expression Functions

Function	Description
`concat()`	Join strings together
`sum()`	Sum numeric values
`count()`	Count records
`if()`	Conditional expression
`case()`	Switch/case expression

Validation

# Configure field validation
$ hyperfold integrate map shopify \
  --validation='[
    {"field": "sku", "rule": "required"},
    {"field": "sku", "rule": "unique"},
    {"field": "base_price", "rule": "positive"},
    {"field": "base_price", "rule": "max", "value": 100000},
    {"field": "email", "rule": "email"},
    {"field": "category", "rule": "enum", "values": ["footwear", "apparel", "equipment"]}
  ]'
# Test mappings with sample data
$ hyperfold integrate map shopify --test
# Validate against production data
$ hyperfold integrate map shopify --validate --sample=100

Validation Rules

Rule	Description
`required`	Field must not be null/empty
`unique`	Value must be unique across records
`positive`	Number must be greater than 0
`email`	Valid email format
`enum`	Value in allowed list
`regex`	Match regular expression

Always test mappings with --test and validate with --validate before enabling production sync.

Configure sync scheduling with integration map.

Search Documentation