Dokumentace mapování dat

Formát ParseMapper pro mapování a transformaci dat z různých zdrojů

[navigate:/devdoc/test-mapper|Test Mapper|play|right]

Přehled

Formát ‘import’ ParseMapper je konfigurační syntaxe pro mapování a transformaci dat z různých strukturovaných zdrojů (jako jsou XML, JSON, CSV atd.) do normalizované interní reprezentace. Tento formát se používá k definování způsobu, jakým jsou pole ze zdrojových dat mapována, transformována a vztažena k cílovým entitám.

Klíčové komponenty

Definice proměnných Volitelné deklarace proměnných pomocí direktivy @variable

Deklarace typu Určuje typ zdrojových dat (XML, JSON, CSV atd.)

Globální direktivy Volitelná nastavení, která ovlivňují chování při parsování

Mapování entit Definice pro extrahování a mapování entit a polí

Struktura souboru

Typický soubor mapování importu se skládá z definic proměnných, deklarace typu, globálních direktiv a mapování entit:

@variable default_vat_rate = {
    name: "Default VAT Rate"
    type: "number"
    defaultValue: "21"
}

type XML

@atomic = "false"
@strict = false
@language = "en"

products = '$.SHOP.SHOPITEM[*]' {
    id[code] = 'CODE'
    name = 'NAME'
    // ... more field mappings ...
    variants = 'VARIANTS.VARIANT' {
        code = 'CODE'
        // ... nested field mappings ...
        @removeAll = "true"
    }
    // ... more nested entities ...
}

Syntaxe cesty

Jednoduchá tečkovaná cesta

Přímočará tečková notace bez úvodního $ nebo @.

LOGISTIC.WEIGHT

Používá se pro přímý, statický přístup k polím

JSONPath

Výkonná syntaxe pro navigaci ve strukturách JSON. Označeno úvodním $ nebo @.

$.SHOP.SHOPITEM[*]

Podporuje pokročilé selektory, zástupné znaky a přístup k polím

Odkaz na rodiče ($parent) [badge:New|secondary|right]

Přístup k polím z nadřazeného objektu vnořených struktur pomocí předpony $parent.

$parent.orderId                 // Přístup k poli rodiče
$parent.customer.name           // Přístup k vnořenému poli rodiče
$parent["field-name"]           // Se speciálními znaky

Příklad použití:

orders = '$.orders[*]' {
    orderId = '$.id'
    items = '$.items[*]' {
        productName = '$.name'
        orderId = '$parent.id'
        orderDate = '$parent.date'
    }
}

Užitečné, když podřízené záznamy potřebují odkazovat na informace na úrovni rodiče

Více alternativních cest

Použijte operátor || k určení náhradních cest. Bude použita první cesta, která vrátí hodnotu.

name = '$.NAME' || '$.ALT_NAME' || "STATIC"

Referenční příručka syntaxe

1. Deklarace typu

Definuje typ zdrojových dat:

type XML

Podporované typy: XML, JSON, CSV, YAML, XLSX, XLS

2. Globální direktivy

Řídí chování parseru:

@atomic = "false"
@strict = false
@language = "en"

• @atomic: Zda má být import atomický
• @strict: Zda má být vynuceno striktní mapování
• @language: Výchozí jazyk pro importy

3. Definice proměnných

Definujte proměnné pro konfigurovatelné parametry importu:

@variable default_vat_rate = {
    name: "Default VAT Rate"
    description: "Variable description"
    type: "number"
    defaultValue: "21"
}

Typy proměnných

• “number” - Číselné hodnoty
• “string” - Textové hodnoty
• “boolean” - Pravda/nepravda
• “relation” - Odkazy na entity

Přeložitelná pole

name:
  - en: "English Name"
  - cs: "Czech Name"

4. Mapování entit

Definuje, jak extrahovat entity ze zdrojových dat:

entityName = 'jsonpath' {
    field1 = 'SOURCE_FIELD'
    field2 = 'NESTED.PATH'
    manufacturer[code] = 'MANUFACTURER'
    status = "active"
    // ... more fields ...
}

Speciální funkce

• Vyhledávací pole: field[key] = ‘SOURCE’
• Statické hodnoty: field = “static”
• Vnořené entity s @removeAll
• Tabulky pro nahrazení polí
• Tabulky pro nahrazení specifické pro cestu

Výrazy

total = ${price + vat}

Příklady

Import XML e-shopu

Komplexní import XML s vnořenými entitami a vyhledávacími poli:

type XML

@atomic = "false"
@strict = false

products = '$.SHOP.SHOPITEM[*]' {
    id[code] = 'CODE'
    name = 'NAME'
    description = 'DESCRIPTION'
    unit[name] = 'UNIT'
    manufacturer[code] = 'MANUFACTURER'
    variants = 'VARIANTS.VARIANT' {
        code = 'CODE'
        priceWithVat = 'PRICE_VAT'
        @removeAll = "true"
    }
    images = 'IMAGES.IMAGE' {
        url = '_'
        description = '$["$"].description'
        @removeAll = "true"
    }
    categories = 'CATEGORIES' {
        category[id] = 'CATEGORY.$.id'
        category[name] = 'CATEGORY._'
        @removeAll = "true"
    }
}

Příklad nahrazení pole

Mapování specifických zdrojových hodnot na různé cílové hodnoty:

taxRateLevel = 'TAX_RATE_LEVEL' ['high' = 'standard', 'low' = 'reduced']
status = 'state' ['active' = 'enabled', 'inactive' = 'disabled']

Tabulky pro nahrazení specifické pro cestu [badge:New|secondary|right]

Použijte tabulky pro nahrazení na jednotlivé cesty ve výrazech s více cestami:

// Smíšené: Žádné nahrazení na první cestě, nahrazení na druhé cestě
visibility = 'VISIBILITY' || ('VISIBLE' ['1' = 'visible', '0' = 'hidden'])

// Individuální: Různé tabulky pro nahrazení pro každou cestu
status = ('STATUS' ['A' = 'active', 'I' = 'inactive']) || ('STATE' ['1' = 'enabled', '0' = 'disabled'])

// Zpětně kompatibilní: Tabulka pro nahrazení na úrovni pole (stávající chování)
type = 'TYPE' || 'TYPE_CODE' ['premium' = 'PREMIUM', 'basic' = 'STANDARD']

Smíšené globální/lokální Použijte nahrazení pouze na specifické cesty, zatímco ostatní ponecháte beze změny

Individuální tabulky cest Každá cesta může mít svá vlastní pravidla transformace

Zpětně kompatibilní Stávající syntaxe na úrovni pole nadále funguje

Přeložitelná pole s dynamickými jazykovými klíči [badge:New|secondary|right]

Mapování vícejazyčného obsahu s dynamickým řešením jazykového klíče

Přeložitelná pole mohou dynamicky určovat cílový jazyk ze zdrojových dat, což umožňuje efektivní vícejazyčné importy z jednotlivých zdrojových záznamů.

Jednoduchý jazykový klíč cesty

name['LANG'] = 'TEXT'

Jazykové pole ve stejném záznamu určuje jazyk

Jazykový klíč JSONPath

name['$.language.code'] = 'TEXT'

Použijte složité výrazy cesty k nalezení identifikátoru jazyka

Statický jazykový klíč

name["en"] = 'NAME_EN' || 'NAME'

Explicitně mapujte na konkrétní jazyk s náhradou

Jazykový klíč výrazu

name[${LOWER(langCode)}] = 'TEXT'

Vypočítaný jazykový klíč pomocí výrazů

Kompletní příklad

products = '$.items[*]' {
    code = 'CODE'
    
    // Dynamické jazykové klíče ze zdrojových dat
    name['LANG'] = 'TEXT' @loop '$.TEXTS[*]'
    description['LANG'] = 'DESCRIPTION' @loop '$.TEXTS[*]'
    
    // Statické jazykové klíče s náhradou
    shortName["en"] = 'SHORT_NAME_EN' || 'NAME'
    shortName["cs"] = 'SHORT_NAME_CS' || 'NAME'
}

Direktiva @loop [badge:New|secondary|right]

Iterujte přes pole a vytvořte více záznamů nebo překladů

Direktiva @loop umožňuje iterovat přes pole nebo kolekce ve zdrojových datech a vytvářet více záznamů, překladů nebo hodnot polí.

Základní syntaxe

fieldName = 'PATH' @loop 'ITERATION_PATH'

S přeložitelnými poli

name['lang'] = 'text' @loop '$.translations[*]'

Vytvořte více jazykových překladů z pole

Vytvoření pole

tags = 'tag' @loop '$.tags[*]'

Vytvořte pole z pole zdroje

Vnořené vztahy s @loop

images = '$.images[*]' @loop '$.images[*]' {
    url = 'url'
    description['lang'] = 'alt' @loop '$.alts[*]'
    sortOrder = 'position'
}

Iterujte přes pole obrázků a vytvořte více záznamů obrázků, každý s přeloženými popisy

Kompletní příklad

products = '$.products[*]' {
    code = 'sku'
    
    // Vícejazyčné z pole překladů
    name['languageCode'] = 'title' @loop '$.translations[*]'
    description['languageCode'] = 'desc' @loop '$.translations[*]'
    
    // Jednoduché vytvoření pole
    tags = 'tag' @loop '$.tags[*]'
    
    // Vnořené vztahy
    variants = '$.options[*]' @loop '$.options[*]' {
        code = 'optionSku'
        name['lang'] = 'optionName' @loop '$.optionTranslations[*]'
        priceWithVat = 'optionPrice'
    }
}

Formáty výstupu přeložitelných polí [badge:Important|secondary|right]

Dva podporované formáty pro výstup přeložitelných polí

Mapper podporuje dva formáty výstupu pro přeložitelná pole, v závislosti na tom, jak strukturováte mapování.

Formát objektu (s @loop) [badge:Recommended|default|right]

// Syntaxe mapperu
name['LANG'] = 'TEXT' @loop 'TEXTS.ITEM'

// Výstup
{
  "name": {
    "en": "English Name",
    "cs": "České jméno",
    "de": "Deutscher Name"
  }
}

✅ Čistá, plochá struktura ✅ Lepší výkon pro vyhledávání ✅ Snadnější práce v uživatelském rozhraní ✅ Doporučeno pro většinu případů použití

Formát pole (bez @loop) [badge:Alternative|outline|right]

// Syntaxe mapperu
name = 'TEXTS.ITEM' {
    language = 'LANG'
    value = 'TEXT'
}

// Výstup
{
  "name": [
    {"language": "en", "value": "English Name"},
    {"language": "cs", "value": "České jméno"},
    {"language": "de", "value": "Deutscher Name"}
  ]
}

• Strukturovaný formát metadat • Může obsahovat další pole • Používá se pro systémy založené na polích • Kompatibilita se staršími verzemi

Kompletní příklad: Oba formáty

type XML

products = '$.SHOP.PRODUCT[*]' {
    code = 'CODE'
    
    // Formát objektu - doporučeno
    name['$.language'] = 'title' @loop 'DESCRIPTIONS.DESC'
    description['$.language'] = 'text' @loop 'DESCRIPTIONS.DESC'
    
    // Formát pole - alternativa
    alternativeName = 'DESCRIPTIONS.DESC' {
        language = '$.language'
        value = 'title'
    }
}

Kdy použít který formát

Použijte formát objektu (@loop):

• Nejběžnější scénář - čisté překlady
• Lepší integrace a výkon uživatelského rozhraní
• Standardní přístup pro nové projekty

Použijte formát pole (vnořený):

• Potřeba ukládat metadata s překlady
• Migrace ze systémů založených na polích
• Další pole kromě jazyka/hodnoty

Direktiva @if [badge:New|secondary|right]

Podmíněně zahrňte pole na základě běhových podmínek

Direktiva @if umožňuje podmíněně zahrnout pole nebo vztahy na základě běhových podmínek vyhodnocených ze zdrojových dat.

Základní syntaxe

fieldName = 'PATH' @if ${condition}

Jednoduchá podmínka

discount = 'DISCOUNT' @if ${hasDiscount == 'true'}

Zahrňte slevu pouze v případě, že produkt má slevu

Složitá podmínka

price = 'BULK_PRICE' @if ${isB2B == 'true' && price > 100}

Více podmínek s operátory AND/OR

Podporované operátory

Porovnání ==, !=, >, <, >=, <=

Logické && (AND), || (OR)

Typy řetězce, čísla, booleovské hodnoty

Podmíněné vnořené vztahy

// Vytvořte obrázky pouze v případě, že je produkt má
images = '$.images[*]' @loop '$.images[*]' @if ${hasImages == 'true'} {
    url = 'url'
    description = 'alt'
    sortOrder = 'position'
}

Kompletní příklad

products = '$.products[*]' {
    code = 'sku'
    name = 'title'
    basePrice = 'price'
    
    // Podmíněná pole
    discount = 'discountPercent' @if ${hasDiscount == 'true'}
    weight = 'weightKg' @if ${isPhysical == 'true'}
    downloadUrl = 'fileUrl' @if ${isDigital == 'true'}
    
    // Rozšířený popis pouze pro prémiové produkty
    extendedDesc = 'detailedText' @if ${productType === 'premium'}
    
    // Podmíněné vztahy
    variants = '$.options[*]' @loop '$.options[*]' @if ${isConfigurable == 'true'} {
        code = 'optionSku'
        priceWithVat = 'optionPrice'
    }
}

Kombinace @loop a @if [badge:Advanced|secondary|right]

Kombinujte direktivy pro výkonné podmíněné zpracování polí

Můžete kombinovat direktivy @loop a @if pro sofistikované podmíněné zpracování a filtrování polí.

Podmíněný vícejazyčný import

products = '$.items[*]' {
    code = 'CODE'
    
    // Importujte překlady pouze v případě, že jsou k dispozici
    name['LANG'] = 'TEXT' @loop '$.TEXTS[*]' @if ${HAS_TRANSLATIONS == 'true'}
    description['LANG'] = 'DESC' @loop '$.TEXTS[*]' @if ${HAS_TRANSLATIONS == 'true'}
    
    // Náhrada, pokud nejsou k dispozici žádné překlady
    name = 'NAME' @if ${HAS_TRANSLATIONS != 'true'}
    description = 'DESCRIPTION' @if ${HAS_TRANSLATIONS != 'true'}
}

Filtrované zpracování polí

products = '$.products[*]' {
    code = 'sku'
    name['lang'] = 'title' @loop '$.translations[*]'
    
    // Importujte obrázky pouze v případě, že je produkt má
    images = '$.images[*]' @loop '$.images[*]' @if ${hasImages == 'true'} {
        url = 'url'
        description['lang'] = 'alt' @loop '$.alts[*]'
        sortOrder = 'position'
    }
    
    // Specifikace pouze pro elektroniku
    specifications = '$.specs[*]' @loop '$.specs[*]' @if ${category === 'electronics'} {
        name['lang'] = 'specName' @loop '$.nameTranslations[*]'
        value = 'specValue'
        unit = 'specUnit'
    }
}

Doporučené postupy

• Pokud je to možné, použijte @if před @loop pro včasné filtrování
• Udržujte podmínky jednoduché a testovatelné
• Testujte s reprezentativními vzorovými daty
• Vyhněte se hluboce vnořeným smyčkám (max. 2-3 úrovně)
• Dokumentujte složitou obchodní logiku pomocí komentářů

Syntaxe pole pro pole kolekcí [badge:New|secondary|right]

Připojte více hodnot k polím kolekcí z nezávislých zdrojů

Syntaxe pole (fieldName[]) umožňuje připojit více hodnot ke stejnému poli kolekce, místo aby se nahradilo. To je zvláště užitečné, když potřebujete naplnit pole z více nezávislých zdrojů nebo podmínek.

Základní syntaxe

fieldName[] = 'PATH' {
    // field mappings
}

Když použijete příponu [] na název pole, každá instance se připojí ke kolekci, místo aby nahradila předchozí hodnoty.

Problém: Vícenásobné přiřazení

Bez syntaxe pole nemůžete přiřadit ke stejnému poli vícekrát:

❌ Not Supported - Parser Error

flags = 'LABELS.LABEL' {
    flag[code, name] = 'NAME'
}
flags = {
    flag[code] = 'new'
} @if ${NEW_YN === '1'}
flags = {
    flag[code] = 'special'
} @if ${SPECIAL_YN === '1'}

Řešení: Syntaxe pole

✅ Correct - Appends to Collection

// First clear existing flags
flags = 'LABELS.LABEL' {
    flag[code, name] = 'NAME'
    @removeAll = "true"
}

// Then append conditionally
flags[] = {
    flag[code] = 'new'
} @if ${NEW_YN === '1'}

flags[] = {
    flag[code] = 'special'
} @if ${SPECIAL_YN === '1'}

flags[] = {
    flag[code] = 'sellout'
} @if ${SELLOUT_YN === '1'}

Kompletní příklad s @removeAll

Běžným vzorem je nejprve vymazat stávající data a poté připojit nové položky:

products = '$.SHOP.SHOPITEM[*]' {
    code = 'CODE'
    
    // First, clear all existing flags and import from primary source
    flags = 'LABELS.LABEL' {
        flag[code, name] = 'NAME'
        @removeAll = "true"
    }
    
    // Then append additional flags based on conditions
    flags[] = {
        flag[code] = 'new'
        flag[name] = 'New Product'
    } @if ${NEW_PRODUCT === 'true'}
    
    flags[] = {
        flag[code] = 'clearance'
        flag[name] = 'Clearance Sale'
    } @if ${CLEARANCE === 'true'}
}

Syntaxe pole s jednoduchými hodnotami

products = '$.products[*]' {
    code = 'id'
    
    // Base tags from primary field
    tags[] = 'primaryTag'
    
    // Add category-based tags
    tags[] = 'electronics' @if ${category === 'ELECTRONICS'}
    tags[] = 'apparel' @if ${category === 'CLOTHING'}
    
    // Add promotional tags
    tags[] = 'featured' @if ${isFeatured == 'true'}
    tags[] = 'bestseller' @if ${salesRank <= 10}
}

Kdy použít syntaxi pole

✅ Použijte syntaxi pole, když:

• Více nezávislých zdrojů
• Podmíněné přidání
• Postupné vytváření
• Smíšená statická a dynamická data

❌ Nepoužívejte, když:

• Jeden zdroj (použijte @loop)
• Chcete nahradit, nikoli připojit
• Jednoduché jedno přiřazení

Doporučené postupy

• Nejprve vymažte, poté připojte: Použijte @removeAll při prvním přiřazení, poté použijte [] pro následné přidání
• Použijte @if pro podmíněné položky: Kombinujte s direktivou @if a přidávejte položky pouze v případě, že jsou splněny podmínky
• Udržujte pořadí řazení: Zvažte přidání explicitních polí pro pořadí řazení při použití syntaxe pole s více zdroji
• Důkladně testujte: Ověřte, zda jsou všechny položky pole vytvořeny správně se vzorovými daty

Direktiva vyhledávacího pole [badge:New|secondary|right]

Řídí chování a zachycuje chybějící data při řešení vyhledávacích polí

Při mapování vyhledávacích polí (vztahů) tyto direktivy řídí, co se stane, když nelze odkaz vyřešit, a umožňují vám shromažďovat data pro vytváření chybějících záznamů.

Direktiva @if-not-found

Řídí chování, když nelze najít odkaz na vyhledávací pole v databázi.

skip Přeskočí celý záznam (výchozí)

create Shromažďuje data pro vytváření chybějících záznamů

ignore Ponechá pole null, pokračuje ve zpracování

error Vyvolá chybu, zastaví import

products = '$.SHOPITEM[*]' {
    code = 'CODE'
    name = 'NAME'
    
    // Přeskočí celý produkt, pokud nebyl nalezen výrobce (výchozí)
    manufacturer[code] = 'MANUFACTURER_CODE'
    
    // Shromažďuje data pro vytváření chybějících kategorií
    category[code]@if-not-found = 'create' = 'CATEGORY_ID'
    
    // Pokračuje, i když nebyla nalezena jednotka (pole bude null)
    unit[name]@if-not-found = 'ignore' = 'UNIT_NAME'
}

Direktiva @create-as

Při použití @if-not-found='create' tato direktiva určuje, jaká data se mají shromažďovat pro vytváření chybějících vyhledávacích záznamů.

products = '$.SHOPITEM[*]' {
    code = 'CODE'
    name = 'NAME'
    
    // Shromažďuje data kategorie pro vytvoření, pokud nebyla nalezena
    category[code]@if-not-found = 'create' = 'CATEGORY_ID'
    category[code]@create-as = {
        code = 'CATEGORY_ID'
        name = 'CATEGORY_TITLE'
        description = 'CATEGORY_DESC' || 'CATEGORY_TITLE'
        sortOrder = 'CATEGORY_ORDER'
    }
}

Pokročilé příklady

Alternativní cesty a tabulky pro nahrazení

category[code]@if-not-found = 'create' = 'CATEGORY_ID' || 'CATEGORY_CODE'
category[code]@create-as = {
    code = 'CATEGORY_ID' || 'CATEGORY_CODE'
    name = 'CATEGORY_NAME' || 'CATEGORY_TITLE' || 'CATEGORY_ID'
    type = 'CATEGORY_TYPE' ['MAIN' = 'primary', 'SUB' = 'secondary']
}

Statické hodnoty

manufacturer[code]@if-not-found = 'create' = 'MANUFACTURER_CODE'
manufacturer[code]@create-as = {
    code = 'MANUFACTURER_CODE'
    name = 'MANUFACTURER_NAME'
    country = "CZ"
    isActive = "true"
}

Vnořené vztahy

products = '$.SHOPITEM[*]' {
    code = 'CODE'
    name = 'NAME'
    
    category[code]@if-not-found = 'create' = 'CATEGORY_ID'
    category[code]@create-as = {
        code = 'CATEGORY_ID'
        name = 'CATEGORY_NAME'
        
        // Vnořené vztahy v bloku create-as
        productPrices = 'PRICES.PRICE' {
            priceWithVat = 'PRICE_VAT'
            priceWithoutVat = 'PRICE_BASE'
            validFrom = 'DATE_FROM'
            @removeAll = "true"
        }
    }
}

Jak to funguje

1. Během importu se systém pokusí vyřešit každý odkaz na vyhledávací pole
2. Pokud nebyl nalezen a @if-not-found='create', shromažďují se data
3. Shromážděná data jsou uložena s klíčem fieldName@create-as
4. Importní úloha obsahuje importované záznamy i data pro vytvoření
5. Poté můžete vytvořit chybějící záznamy a znovu spustit import

Doporučené postupy

• Použijte create pro kritické odkazy, jako jsou kategorie, výrobci
• Použijte ignore pro volitelná pole, která lze vyplnit později
• Použijte skip, když chybějící odkazy indikují neplatná data
• Použijte error, když musí být zaručena kvalita dat
• Poskytněte alternativní cesty a náhrady v blocích @create-as
• Zahrňte dostatek polí pro vytvoření platných záznamů (zkontrolujte požadavky metamodelu)
• Testujte s daty obsahujícími chybějící odkazy

Odkaz na rodiče ($parent) [badge:New|secondary|right]

Přístup k polím nadřazeného objektu ve vnořených strukturách

Při práci s vnořenými entitami můžete odkazovat na pole z nadřazeného objektu pomocí předpony $parent. To je zvláště užitečné, když podřízené záznamy potřebují zahrnovat informace z nadřazené úrovně.

Syntaxe

$parent.field                   // Přímé pole rodiče
$parent.nested.field            // Vnořené pole rodiče
$parent["field-name"]           // Se speciálními znaky

Příklad: Položky objednávky s informacemi o nadřazené objednávce

type JSON

orders = '$.orders[*]' {
    orderId = '$.id'
    orderDate = '$.date'
    customer = '$.customer'
    
    items = '$.items[*]' {
        productName = '$.name'
        price = '$.price'
        quantity = '$.quantity'
        // Reference parent order fields
        orderId = '$parent.id'
        orderDate = '$parent.date'
        orderCustomer = '$parent.customer'
    }
}

Každá položka bude obsahovat orderId, orderDate a orderCustomer z nadřazeného objektu objednávky.

Příklad: Varianty produktu s informacemi o nadřazeném produktu

products = '$.products[*]' {
    productId = '$.id'
    productName = '$.name'
    category = '$.category'
    brand = '$.brand'
    
    variants = '$.variants[*]' {
        variantCode = '$.sku'
        variantSize = '$.size'
        variantColor = '$.color'
        stockLevel = '$.stock'
        // Include parent product information
        productId = '$parent.id'
        productName = '$parent.name'
        category = '$parent.category'
        brand = '$parent.brand'
    }
}

Příklad: Položky faktury

invoices = '$.invoices[*]' {
    invoiceNumber = '$.number'
    invoiceDate = '$.date'
    currency = '$.currency'
    customer[code] = '$.customer.code'
    
    lineItems = '$.lines[*]' {
        itemCode = '$.code'
        description = '$.description'
        amount = '$.amount'
        quantity = '$.qty'
        // Reference parent invoice data
        invoiceNumber = '$parent.number'
        invoiceDate = '$parent.date'
        currency = '$parent.currency'
        customerCode = '$parent.customer.code'
    }
}

Důležité poznámky

• $parent odkazuje na bezprostřední nadřazený objekt v hierarchii mapování
• Kontext rodiče je k dispozici pouze ve vnořených strukturách (objekty s vnořenými mapováními polí)
• Pokud je použit na kořenové úrovni, kde neexistuje žádný rodič, bude pole nedefinované
• V direktivách @loop se položka smyčky stane aktuálním zdrojem a původní zdroj se stane rodičem
• Můžete přistupovat k vnořeným polím rodiče: $parent.customer.name

Případy použití

Denormalizace Zahrňte informace o rodiči do podřízených záznamů pro snadnější dotazování a vytváření sestav

Obohacení dat Přidejte kontext z nadřazených entit, aby byly podřízené záznamy soběstačné

Sledování odkazů Udržujte odkazy mezi souvisejícími záznamy pro integritu dat

Auditní stopa Zahrňte časová razítka a identifikátory na úrovni rodiče do podřízených záznamů

Tipy a doporučené postupy

Tipy pro syntaxi

• Používejte jednoduché uvozovky pro cesty ke zdroji
• Používejte dvojité uvozovky pro statické hodnoty
• Používejte vnořené bloky pro pole/objekty
• Přidejte @removeAll pro vnořené entity
• Používejte syntaxi JSONPath ($.path[*]) v @loop
• Používejte $parent k odkazování na pole rodiče ve vnořených strukturách
• Udržujte podmínky @if jednoduché

Výkon

• Testujte s velkými datovými sadami
• Používejte vyhledávací pole pro vztahy
• Plánujte zpracování chyb
• Dokumentujte složité transformace
• Používejte @if k filtrování v rané fázi zpracování
• Minimalizujte hloubku vnoření pro smyčky