Data 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"}
  ]'

# 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)
  regex_replace        "foo-bar" → "foo_bar"
  template             "{first} {last}" → "John Doe"
 
NUMERIC
  round(n)             3.14159 → 3.14 (n=2)
  floor                3.7 → 3
  ceil                 3.2 → 4
  cents_to_dollars     1299 → 12.99
  dollars_to_cents     12.99 → 1299
  percentage           0.15 → "15%"
 
DATE/TIME
  format(pattern)      ISO → "Jan 20, 2025"
  timezone(tz)         UTC → America/Los_Angeles
  relative             ISO → "2 hours ago"
 
ARRAY
  split(delim)         "a,b,c" → ["a","b","c"]
  join(delim)          ["a","b"] → "a, b"
  first                ["a","b"] → "a"
  last                 ["a","b"] → "b"
  flatten              [[a],[b]] → [a,b]
 
SPECIAL
  strip_html           "<p>hello</p>" → "hello"
  markdown             "**bold**" → "<b>bold</b>"
  lookup(table)        "gold" → 3 (via lookup table)
  default(value)       null → "default"
  hash(algo)           "secret" → "5e884898..."
  boolean              "yes" → true
 
# Apply transformation
$ hyperfold integrate map shopify \
  --field=body_html \
  --transform='[
    {"type": "strip_html", "preserve": ["b", "i", "ul", "li"]},
    {"type": "truncate", "length": 500}
  ]'

# 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"))"
    }
  ]'
 
# Aggregations from related records
$ hyperfold integrate map salesforce \
  --source=Contact \
  --target=customer \
  --computed='[
    {
      "target": "lifetime_value",
      "expression": "sum(Opportunities[Stage="Closed Won"].Amount)"
    },
    {
      "target": "order_count",
      "expression": "count(Opportunities[Stage="Closed Won"])"
    },
    {
      "target": "avg_order_value",
      "expression": "lifetime_value / order_count"
    }
  ]'

# 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
 
Testing Shopify → Hyperfold mapping...
 
SAMPLE SOURCE RECORD
{
  "title": "Running Shoes Pro",
  "body_html": "<p>Professional <b>running shoes</b></p>",
  "vendor": "Nike",
  "variants": [{"price": "12999", "sku": "SHOE-001"}]
}
 
TRANSFORMED RESULT
{
  "name": "Running Shoes Pro",
  "description": "Professional running shoes",
  "brand": "Nike",
  "base_price": 129.99,
  "sku": "SHOE-001",
  "search_text": "Running Shoes Pro Nike"
}
 
VALIDATION
  ✓ sku: required (passed)
  ✓ base_price: positive (passed)
  ✓ name: not empty (passed)
 
All validations passed.
 
# Validate against production data
$ hyperfold integrate map shopify --validate --sample=100
 
Validating 100 sample records...
 
VALIDATION RESULTS
  Passed:           97
  Warnings:         2
  Errors:           1
 
ISSUES FOUND
  Record 45: body_html contains <script> (will be stripped)
  Record 67: tags is empty array (semantic_tags will be null)
  Record 89: variants.price is 0 (validation error: must be positive)
 
Fix issues before enabling sync.