The Item collection API uses a patch mechanism to modify record data in item collections.
This guide explains how the patch mechanism works, including path targeting, operation types, update modes, and advanced features like automatic downstream triggers.
Prerequisite knowledge
-
Understanding of item collection concepts.
-
Understanding of job types.
Record hierarchy
Before modifying records with the patch mechanism, understand how they’re structured. Records follow a hierarchical structure. A product item type's records can be standalone (with no variants) or contain variants. A custom item type's records are always standalone. Custom item types don't support variants.
Product Record (identified by a record identifier)
└── fields (object of product-level fields)
└── variants (object, optional)
├── variant record Id 1
│ └── fields (object of variant-level fields)
├── variant record Id 2
│ └── fields
└── ...A custom item type's records don't have variants. Each record is a single, standalone fields container:
Item Record (identified by a record identifier)
└── fields (object of the item's fields)Structure components
-
record ID: Unique identifier for the record (for example, "006").
-
fields: Key-value pairs of the record's fields. For product item types, these are product-level fields.
-
variants (optional, product item types only): Key-value pairs whose keys are the variant IDs, each mapping to a Variant record, which itself has a fields container.
When you add or replace a product record at the top level (for example, "/product-123"), you inherently add or replace all nested fields and variants as well.
What is the patch mechanism?
The patch mechanism provides a structured way to modify records in an item collection. The patch mechanism uses operations that describe specific changes to records.
How the patch mechanism works
When you submit a patch, you provide a list of operations and choose an update mode (full or delta). Bloomreach queues the patch as an asynchronous update job, not a streaming ingest, then processes the operations in sequence, applying each change to the targeted path in your record structure. To learn how patches are batched, see Patch processing and jobs.
Each operation specifies:
-
Path: Where to make the change.
-
Operation type: The type of change to make.
-
Value: What data to apply.
Combine multiple operations into a single patch to modify different parts of your data atomically. The Item collection API applies patches transactionally. Either all operations in a patch succeed, or none do. This ensures records never end up in a partially modified or indeterminate state.
Anatomy of a patch
Core components
- Path targeting: Specify where to make changes and explore examples.
- Patch operation types: Understanding add, upsert, and remove.
Application and modes
- Patch update modes: Full vs. delta updates.
- Patch format and delivery: How to send patches.
Advanced features
Automatic success triggers: Triggering items and destination updates.