Partial Updates
Partial Update allows you to update, add, or remove targetted records in your collection without impacting the entire catalog. The engine accepts partial updates. This means you do not have to re-upload the entire catalog for the index to be updated.
If you choose to have partial updates, there are a number of things that should be considered.
For this guide there are sample files available within each section.
Limitations With Partial Updates
Partial updates are great for quick updates to your catalog, but here are some important caveats you should know about:
You cannot send a partial record
If you want to change the content of just one field, you still need to send all the data that should exist on the record. In other words: the stored record is replaced with the record that you send.
For example, let’s say we are starting with this record:
{
"id":"1001",
"title":"Ultra Comfort Flip flops",
"gender":"Women",
"categoryId":[
"230"
],
"brand":"Nike",
"variants":[
{
"sku":"1001G-7-B",
"shoeSize":"7",
"width":"B",
"color":"Green",
"image":"1001G",
"onSale":"true",
"originalPrice":"149.95",
"finalPrice":"99.95",
"stores":[
{
"storeID":"1",
"inventory":"15",
"price":"99.95"
}
]
}
]
}
If you were to update it with this:
{"id":"1001","title":"Ultra Comfort Flat Sandals","gender":"Women", "categoryId":["230"]}
Then the record will lose information, and look like this:
{
"gender":"Women",
"categories":[
{
"1":"Shoes",
"2":"Sandals",
"leaf":"Sandals"
}
],
"id":"1001",
"title":"Ultra Comfort Flat Sandals",
"categoryId":[
"230"
]
}
Note:
variantsandbrandis no longer attached.
You cannot change arrays to single values
If your field was defined as an array initially, you cannot change it to be a single value field.
For example, let’s say we are starting with this record:
{
"id":"1001",
"title":"Ultra Comfort Flip flops",
"gender":"Women",
"categoryId":[
"230"
],
"brand":"Nike",
"variants":[
{
"sku":"1001G-7-B",
"shoeSize":"7",
"width":"B",
"color":"Green",
"image":"1001G",
"onSale":"true",
"originalPrice":"149.95",
"finalPrice":"99.95",
"stores":[
{
"storeID":"1",
"inventory":"15",
"price":"99.95"
}
]
}
]
}
If you were to try to update it with this:
{ "id":"1001",
"title":"Ultra Comfort Flip flops",
"gender":"Women",
"categoryId":["230"],
"brand":"Nike",
"variants":"" }
You will get this error:
{ "status": {
"code": 420,
"internalCode": 0,
"message": "Data file failed to parse",
"additionalInfo": "Upload resulted in 0 updated records: id '1001' - MapperParsingException[object mapping for [variants] tried to parse field [variants] as object, but found a concrete value]",
"serverTimestamp": 1490663172354 }
}
The data model cannot change within a partial update.
Let’s say this is your record:
{
"id":"1001",
"title":"Ultra Comfort Flip flops",
"gender":"Women",
"categoryId":[
"230"
],
"brand":"Nike",
"variants":[
{
"sku":"1001G-7-B",
"shoeSize":"7",
"width":"B",
"color":"Green",
"image":"1001G",
"onSale":"true",
"originalPrice":"149.95",
"finalPrice":"99.95",
"stores":[
{
"storeID":"1",
"inventory":"15",
"price":"99.95"
}
]
}
]
}
We can make the stores an array, because it’s already an object:
{
"id":"1001",
"title":"Ultra Comfort Flip flops",
"gender":[
"Women",
"Men"
],
"categoryId":[
"230"
],
"brand":"Nike",
"variants":[
{
"sku":"1001P-7-B",
"shoeSize":"7",
"width":"B",
"color":"Pink",
"image":"1001P",
"onSale":"true",
"originalPrice":"149.95",
"finalPrice":"99.95",
"stores":"hello"
},
{
"sku":"1001G-7-B",
"shoeSize":"7",
"width":"B",
"color":"Green",
"image":"1001G",
"onSale":"true",
"originalPrice":"149.95",
"finalPrice":"99.95",
"stores":[
{
"storeID":"1",
"inventory":"15",
"price":"99.95"
}
]
}
]
}
Bad partial update (throws an exception back to the user) is trying to make color an array:
{
"id":"1001",
"title":"Ultra Comfort Flip flops",
"gender":"Women",
"categoryId":[
"230"
],
"brand":"Nike",
"variants":[
{
"sku":"1001P-7-B",
"shoeSize":"7",
"width":"B",
"color":[
{
"rgb":"#ff0000",
"label":"Pink"
}
],
"image":"1001P",
"onSale":"true",
"originalPrice":"149.95",
"finalPrice":"99.95",
"stores":[
{
"storeID":"1",
"inventory":"15",
"price":"99.95"
}
]
},
{
"sku":"1001G-7-B",
"shoeSize":"7",
"width":"B",
"color":"Green",
"image":"1001G",
"onSale":"true",
"originalPrice":"149.95",
"finalPrice":"99.95",
"stores":[
{
"storeID":"1",
"inventory":"15",
"price":"99.95"
}
]
}
]
}
Will return this error:
{
"status": {
"code": 420,
"internalCode": 0,
"message": "Data file failed to parse",
"additionalInfo": "Upload resulted in 0 updated records: id '1001' - MapperParsingException[failed to parse [variants.color]]; nested: IllegalArgumentException[unknown property [rgb]];",
"serverTimestamp": 1490663843436
}
}
The data configuration cannot change
You cannot add searchable fields, or change any other parts of your configuration with a partial update. This includes refinable and sortable fields, category hierarchy, field types, and language types.
If we try to add this line to my configuration:
fieldDefinition: {name: "id", search: true}
We will get this error:
{
"status": {
"code": 420,
"internalCode": 0,
"message": "Data file failed to parse",
"additionalInfo": "Change detected in upload config. Must set replaceCollection.",
"serverTimestamp": 1490664153313
}
}
Download the illegal partial configuration to see the full file.
Managing deletes
In order to do that you will need to manage deletes via an action flag at record level.
For example, to delete the record we used above, you would send this in:
{
"id":"1001",
"action":"delete"
}
And get this response:
{
"status": {
"code": 200,
"internalCode": 0,
"message": "OK",
"additionalInfo": {
"masterCount": 0,
"variantCount": 0,
"deleteCount": 1,
"uniqueCount": 0,
"invalidRecordCount": 0,
"invalidRecordDetails": []
},
"serverTimestamp": 1490665759463
},
"result": null
}
Best Practice
It is mandatory that you are able to generate baselines (full snapshots) of your catalogues.
While partial updates can be used in an ongoing production environment, a baseline is required when the upload configuration changes. This is a fairly regular occurrence due to shifting data models and shifting business rules. Therefore, any implementation that expects to generate partial updates should also prepare to generate baselines.