Mappings and Transformations
This document outlines the API operations available for managing and applying mappings and transformations to product data.
Queries
applyMapping
Applies a saved mapping to transform data from a source into a specified target format. Specify both the source data and the mapping configuration to be used.
applyMapping(
source: SourceInput!,
mapping: MappingInput!,
targetFormat: TargetFormatInput
): [JSON!]
If no target format is provided, the default target format will be used.
Example:
query {
applyMapping(
source: {
id: "source123",
data: [
{
"product_name": "Wireless Mouse",
"product_price": "29.99",
"brand": "TechGear",
"in_stock": true
}
]
},
mapping: {
id: "mapping123"
},
targetFormat: {
id: "format123"
}
)
}
generateMapping
Generates a mapping based on provided sample data and the desired target format. Use this to create a new mapping configuration by analyzing the structure and fields in the sample data.
generateMapping(
sampleData: SourceInput!,
targetFormat: TargetFormatInput
): [JSON!]
If no target format is provided, the default target format will be used.
Example:
query {
generateMapping(
sampleData: {
data: [
{
"product_name": "Ergonomic Chair",
"product_price": 199.99,
"brand": "ComfortSeating",
"in_stock": true
}
]
},
targetFormat: {
data: {
"name": { "type": "string" },
"price": { "type": "number" },
"manufacturer": { "type": "string" },
"availability": { "type": "boolean" }
}
}
)
}
Additional Mapping Functions
Complex Field Mapping
Use advanced features like array selectors, nested field access, and constant values to customize data mapping.
query {
applyMapping(
source: {
data: {
"product": {
"title": "Gaming Laptop",
"variants": [
{
"price": "999.99",
"inventory_quantity": 5
}
],
"images": [
"https://example.com/image1.jpg",
"https://example.com/image2.jpg"
]
}
}
},
mapping: {
data: [
{
"sourceField": "product.title",
"targetField": "name"
},
{
"sourceField": "product.variants[0].price",
"targetField": "price"
},
{
"sourceField": "product.images[0]",
"targetField": "mainImage"
},
{
"sourceField": "product.variants[0].inventory_quantity",
"targetField": "inStock",
"transform": "value > 0"
}
]
},
targetFormat: {
data: {
"name": { "type": "string" },
"price": { "type": "number" },
"mainImage": { "type": "string" },
"inStock": { "type": "boolean" }
}
}
)
}
Transformation Functions
Use transformation functions to modify data as part of the mapping process. These functions manipulate and convert field values, providing flexibility in how data is processed.
Function | Description | Example |
---|---|---|
capitalize() | Capitalizes the first letter of each word. | "product name" -> "Product Name" |
trim() | Removes whitespace from both ends of a string. | " product " -> "product" |
toNumber() | Converts a string to a number. | "123.45" -> 123.45 |
toBoolean() | Converts a value to a boolean. | "true" -> true, "1" -> true, "false" -> false, "0" -> false |
toString() | Converts a value to a string. | 123 -> "123" |
removeHTMLTags() | Strips HTML tags from a string. | "<p>Product description</p>" -> "Product description" |
convert(fromUnit, toUnit) | Converts between units. | convert("cm", "in") applied to "100" -> "39.37" |
split(separator, index) | Splits a string and returns the specified index. | split(",", "1") applied to "red,green,blue" -> "green" |
slice(start, end?) | Returns a portion of an array or string. | slice("1", "3") applied to "abcdef" -> "bcd" |
match(regex) | Returns the first match of a regular expression. | match("\\d+") applied to "Product123" -> "123" |
replace(search, replacement) | Replaces all occurrences of a substring. | replace("old", "new") applied to "old product" -> "new product" |
join(separator) | Joins array elements into a string. | join(", ") applied to ["red", "green", "blue"] -> "red, green, blue" |
Example usage of transformation functions in a mapping:
{
"sourceField": "product.description",
"targetField": "cleanDescription",
"transform": "removeHTMLTags().trim().capitalize()"
}
Choice Mappings
Use choice mappings to standardize and map specific source values to predefined target values, making it easier to handle categorical data or enumerations.
{
"sourceField": "product.status",
"targetField": "productStatus",
"choices": {
"active": ["in_stock", "available", "1"],
"inactive": ["out_of_stock", "unavailable", "0"],
"discontinued": ["retired", "end_of_life"]
}
}
Combining choice mappings with transformation functions:
{
"sourceField": "product.category",
"targetField": "mainCategory",
"transform": "trim().toLowerCase()",
"choices": {
"electronics": ["tech", "gadgets", "devices"],
"clothing": ["apparel", "fashion", "wear"],
"home": ["household", "interior", "domestic"]
}
}
More complex example:
{
"sourceField": "product.attributes",
"targetField": "productType",
"transform": "join(', ').toLowerCase()",
"choices": {
"smartphone": ["mobile", "phone", "cellular"],
"laptop": ["notebook", "computer", "pc"],
"tablet": ["ipad", "slate", "pad"],
"other": [""]
}
}