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. |
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": {}
}
]
}
}
}