The Expanded Record Format
When data is fetched from the DX Graph, it can be returned in the Expanded Record Format. This format is a JSON object that contains two properties: values and relationships. The values property contains the values for the record. The relationships property contains the related records for each configured relationship. Related records are returned in an array of entities
JSON Structure
The following is an example of a product record in the Expanded Record Format that has a category and skus relationship. Each sku record has a countriesSoldIn relationship.
Sample JSON
{
"values": {
"product_id": "123",
"name": "iPhone 12",
"category_id": "123",
"brand_id": "apple",
"brand": "Apple",
"sku_ids": ["iphone_12_red", "iphone_12_blue", "iphone_12_black"]
},
"relationships": {
"skus": {
"entities": [
{
"values": { "sku_id": "iphone_12_red", "name": "iPhone 12 Red", "color": "red", "price": 799.99 },
"relationships": {
"countriesSoldIn": {
"entities": [
{
"values": { "country_id": "us", "name": "United States" },
"relationships": {}
},
{
"values": { "country_id": "ca", "name": "Canada" },
"relationships": {}
}
]
}
}
},
{
"values": { "sku_id": "iphone_12_blue", "name": "iPhone 12 Blue", "color": "blue", "price": 799.99 },
"relationships": {
"countriesSoldIn": {
"entities": [
{
"values": { "country_id": "us", "name": "United States" },
"relationships": {}
},
{
"values": { "country_id": "ca", "name": "Canada" },
"relationships": {}
},
{
"values": { "country_id": "uk", "name": "United Kingdom" },
"relationships": {}
}
]
}
}
},
{
"values": { "sku_id": "iphone_12_black", "name": "iPhone 12 Black", "color": "black", "price": 799.99
},
"relationships": {
"countriesSoldIn": {
"entities": [
{
"values": { "country_id": "us", "name": "United States" },
"relationships": {}
},
{
"values": { "country_id": "ca", "name": "Canada" },
"relationships": {}
},
{
"values": { "country_id": "uk", "name": "United Kingdom" },
"relationships": {}
}
]
}
}
}
]
},
"category": {
"entities": [
{
"values": { "category_id": "123", "name": "Electronics"
},
"relationships": {}
}
]
}
}
}
Functions
The following functions can be used to access the data:
| Function | Description |
|---|---|
| values(opts) | Returns an object representing all the fields of the current entity. If chained onto a relatedRecords(), it returns an array of objects of all the related entities. If opts.unique is true, the returned array will be a unique set. |
| relatedRecords(relationshipCode) | Returns the related entities for the specified relationship. This is meant to be chained with values, pick or get in order to provide usable values. It can also be chained with relatedRecords to traverse relationships. |
| pick(fields, opts) | Returns an object with the specified fields. If chained onto relatedRecords(), then it returns an array of objects of all the related entities. If opts.unique is true, the returned array will be a unique set. |
| get(field, opts) | Returns the value of the specified field. If chained onto relatedRecords(), then it returns an array of values of the specified field. If opts.unique is true, the returned array will be a unique set. |
| json() | Returns the record in the Expanded Record Format as a JSON object. |
Given the JSON structure above, the following examples show how to access the data using JavaScript expressions in the transformers:
Example: values()
values()
{
"product_id": "123",
"name": "iPhone 12",
"category_id": "123",
"brand_id": "apple",
"brand": "Apple",
"sku_ids": [
"iphone_12_red",
"iphone_12_blue",
"iphone_12_black"
]
}
Example: pick()
pick(['name', 'brand'])
{
"name": "iPhone 12",
"brand": "Apple"
}
Example: get()
get('name')
"iPhone 12"
Example: relatedRecords().values()
relatedRecords('skus').values()
[
{
"sku_id": "iphone_12_red",
"name": "iPhone 12 Red",
"color": "red",
"price": 899.99
},
{
"sku_id": "iphone_12_blue",
"name": "iPhone 12 Blue",
"color": "blue",
"price": 799.99
},
{
"sku_id": "iphone_12_black",
"name": "iPhone 12 Black",
"color": "black",
"price": 799.99
}
]
Example: relatedRecords().pick()
relatedRecords('skus').pick(['name', 'price'])
[
{
"name": "iPhone 12 Red",
"price": 899.99
},
{
"name": "iPhone 12 Blue",
"price": 799.99
},
{
"name": "iPhone 12 Black",
"price": 799.99
}
]
Example: relatedRecords().get()
relatedRecords('skus').get('price')
[ 899.99, 799.99, 799.99 ]
Example: relatedRecords().relatedRecords().values()
relatedRecords('skus').relatedRecords('countriesSoldIn').values({ unique: true })
[
{
"country_id": "us",
"name": "United States"
},
{
"country_id": "ca",
"name": "Canada"
},
{
"country_id": "uk",
"name": "United Kingdom"
}
]
Example: json()
json()
This will return the entire example JSON structure above.
Example: relatedRecords.()relatedRecords().json()
relatedRecords('skus').relatedRecords('countriesSoldIn').json()
[
{
"values": {
"country_id": "us",
"name": "United States"
},
"relationships": {}
},
{
"values": {
"country_id": "ca",
"name": "Canada"
},
"relationships": {}
},
{
"values": {
"country_id": "us",
"name": "United States"
},
"relationships": {}
},
{
"values": {
"country_id": "ca",
"name": "Canada"
},
"relationships": {}
},
{
"values": {
"country_id": "uk",
"name": "United Kingdom"
},
"relationships": {}
},
{
"values": {
"country_id": "us",
"name": "United States"
},
"relationships": {}
},
{
"values": {
"country_id": "ca",
"name": "Canada"
},
"relationships": {}
},
{
"values": {
"country_id": "uk",
"name": "United Kingdom"
},
"relationships": {}
}
]
Record Layout Configuration
The Record Layout Configuration defines what fields and relationships to return. It can be compared to GraphQL but without the need to implement any resolver functions. It is as a JSON object and can be specified when fetching data from the DX Graph.
Sample Record Layout Configuration
{
"fieldsToReturn": ["name", "brand"],
"relationships": {
"skus": {
"fieldsToReturn": ["name", "price"],
"relationships": {
"countriesSoldIn": {}
},
"category": {
"fieldsToExclude": ["category_id"]
}
}
}
}
| Property | Description |
|---|---|
| fieldsToReturn | An array of fields to return. If not specified (and fieldsToExclude is not specified), all fields will be returned. |
| fieldsToExclude | An array of fields to exclude. If not specified (and fieldsToReturn is not specified), all fields will be returned. |
| relationships | An object that defines the relationships to return. Each key in this object is the Relationship Code for the Collection you are querying. Within each Relationship Code object, you can specify fieldsToReturn and fieldsToExclude. |
info
The Record Layout Config is recursive. This means that you can specify a Record Layout Config for a relationship and that relationship can have its own Record Layout Config. In the above, you can see that the skus relationship has its own Record Layout Config. This means that the skus relationship will return the name and price fields and the countriesSoldIn relationship. The category relationship will return all fields except for category_id.
Based on the above Record Layout Configuration and the sample JSON, the result would be:
{
"values": {
"name": "iPhone 12",
"brand": "Apple",
},
"relationships": {
"skus": {
"entities": [
{
"values": { "name": "iPhone 12 Red","price": 799.99 },
"relationships": {
"countriesSoldIn": {
"entities": [
{
"values": { "country_id": "us", "name": "United States" },
"relationships": {}
},
{
"values": { "country_id": "ca", "name": "Canada" },
"relationships": {}
}
]
}
}
},
{
"values": {"name": "iPhone 12 Blue", "price": 799.99 },
"relationships": {
"countriesSoldIn": {
"entities": [
{
"values": { "country_id": "us", "name": "United States" },
"relationships": {}
},
{
"values": { "country_id": "ca", "name": "Canada" },
"relationships": {}
},
{
"values": { "country_id": "uk", "name": "United Kingdom" },
"relationships": {}
}
]
}
}
},
{
"values": {"name": "iPhone 12 Black", "price": 799.99
},
"relationships": {
"countriesSoldIn": {
"entities": [
{
"values": { "country_id": "us", "name": "United States" },
"relationships": {}
},
{
"values": { "country_id": "ca", "name": "Canada" },
"relationships": {}
},
{
"values": { "country_id": "uk", "name": "United Kingdom" },
"relationships": {}
}
]
}
}
}
]
},
"category": {
"entities": [
{
"values": { "name": "Electronics"
},
"relationships": {}
}
]
}
}
}