Pimcore Field Collections, Object Bricks, and Classification Store at a glance<\/h2>\n
Think of them as three different relationships to your object.<\/p>\n
- \n
- Field Collections<\/strong> \u2014 a repeatable, ordered list of field rows on one field. One-to-many.<\/li>\n
- Object Bricks<\/strong> \u2014 an optional field group that attaches to specific classes. A conditional mixin.<\/li>\n
- Classification Store<\/strong> \u2014 a runtime key\/value attribute matrix, extensible without a rebuild.<\/li>\n<\/ul>\n
You configure all three in Studio under Data Management > Data Model Definitions. Each tool has its own definition editor there.<\/p>\n
Pimcore Field Collections: repeatable ordered rows<\/h2>\n
A Field Collection is a reusable, repeatable, ordered list of fields. You add the same structured row many times to a single field.<\/p>\n
That makes it a one-to-many relationship. Think specs, phone numbers, price tiers, downloads, or channel-specific rows.<\/p>\n
![\"pimcore-field-collections-editor\"](\"https:\/\/cdnblog.webkul.com\/blog\/wp-content\/uploads\/2026\/07\/pimcore-field-collections-editor.webp\")
<\/figure>\nField Collection storage<\/h3>\n
Pimcore stores each Field Collection in its own dedicated table. The pattern is
object_collection_<FcKey>_<classId><\/code>, with a localized variantobject_collection_<FcKey>_localized_<classId><\/code>.<\/p>\nAll objects of the same class share this table. Because rows are identified by object id plus index, data stays separate from the base object and keeps it lean.<\/p>\n
Field Collection API access<\/h3>\n
Call
$object->getMyFcField()<\/code>. It returns aFieldcollection<\/code> object that implementsIterator<\/code>.<\/p>\nYou access items by index, fieldname, or type. Also, each item exposes
getFieldname()<\/code>,getIndex()<\/code>, andgetType()<\/code>.<\/p>\nQuerying Pimcore Field Collections items across many objects means reading objects first, then filtering their rows. So the base object query table holds no Field Collection values.<\/p>\n
Field Collection localization and relations<\/h3>\n
A Field Collection item can carry its own Localizedfields container. As a result, you get a clean two-axis model: the item axis crossed with the locale axis.<\/p>\n
For example, this pairs well with translation workflows like the Pimcore DeepL Bundle<\/a>. Items can also hold relations.<\/p>\n
Querying Pimcore Field Collections by a localized field value is even harder than querying by a non-localized field. Therefore you must join both the FC table and the localization table.<\/p>\n
For most queryable attributes, store them as denormalized top-level fields instead. Meanwhile, keep the item structure for data you only read after loading the object.<\/p>\n
Field Collection controls<\/h3>\n
The definition supports
allowedTypes<\/code>,minItems<\/code>\/maxItems<\/code>,disallowReorder<\/code>, and collapsible UI. You also getlazyLoading<\/code> to load individual fields on demand.<\/p>\nQuerying Field Collections<\/h3>\n
Querying across objects by a Field Collection item value is hard. That is because the data lives in separate tables, not denormalized into the object query table.<\/p>\n
The built-in Listing API does not filter by Field Collection values. Instead, the workarounds are custom SQL, denormalizing key fields to the base object, or loading objects and filtering in memory.<\/p>\n
Pimcore Object Bricks: optional field groups per class<\/h2>\n
An Object Brick is a reusable, developer-defined field group. It attaches conditionally to specific classes through an Objectbricks container field.<\/p>\n
Treat it as a mixin or an optional attribute set. Typically you get one brick per type per object, not an ordered repeating list.<\/p>\n
![\"pimcore-object-bricks-editor\"](\"https:\/\/cdnblog.webkul.com\/blog\/wp-content\/uploads\/2026\/07\/pimcore-object-bricks-editor.webp\")
<\/figure>\nWhen to use it<\/h3>\n
Reach for a brick when only some objects need a set of fields. For instance, a
Car<\/code> class where only some cars carry anEngine<\/code> brick is the classic case.<\/p>\nBricks let you avoid null, unused columns in the common case. So the fields appear only where they apply.<\/p>\n
Binding<\/h3>\n
A brick declares which classes and fields it attaches to via
classDefinitions<\/code>. Then, at save time,createContainerClasses()<\/code> adds the brick key to each target field’sallowedTypes<\/code>.<\/p>\nThat binding is bidirectional. Therefore the brick knows its classes, and each class field knows its allowed bricks.<\/p>\n
Storage<\/h3>\n
Pimcore creates per-bound-class tables. It names them
object_brick_store_<brickKey>_<classId><\/code> andobject_brick_query_<brickKey>_<classId><\/code>, plus localized variants when needed.<\/p>\nEach store table uses an
(id, fieldname)<\/code> composite primary key. As a result, multiple brick types coexist in a single Objectbricks field.<\/p>\nPimcore stores each type separately under its own fieldname. So one container field can hold several distinct bricks.<\/p>\n
The query table gives bricks indexed lookups. Also, Pimcore validates table names to stay within 64 characters.<\/p>\n
API access<\/h3>\n
Reach a field via
$object->getBricks()->getEngine()->getCylinders()<\/code>. Here thegetBricks()<\/code> call returns the container, and each brick type has its own typed getter.<\/p>\nPimcore generates a container class per class-field binding. It lives at
PIMCORE_CLASS_DIRECTORY\/DataObject\/<ClassName>\/<FieldName>.php<\/code>.<\/p>\nInheritance<\/h3>\n
With class inheritance on, a child auto-creates an empty parent brick via
createParentBrick()<\/code> insave()<\/code>. That empty brick lets values inherit down the chain.<\/p>\nIf class inheritance is off, no brick scaffolding is created, so the child will not inherit parent values. For how inheritance and variants behave at the class level, see class settings in Pimcore<\/a>.<\/p>\n
The limit<\/h3>\n
An Object Brick is not a repeatable list. Instead you get one brick per type per object, and
maxItems<\/code> counts distinct types, not rows.<\/p>\nBricks must declare their class bindings. However, a free Field Collection has no such requirement.<\/p>\n
Pimcore Classification Store: runtime attribute matrix<\/h2>\n
Classification Store is a single object field holding a dynamic key\/value attribute store. It organizes attributes in three tiers: Keys, Groups, and Group Collections, all tied to a Store.<\/p>\n
The store is unbounded and sparse. Values exist only for the groups you activate on an object.<\/p>\n
![\"pimcore-classification-store-editor\"](\"https:\/\/cdnblog.webkul.com\/blog\/wp-content\/uploads\/2026\/07\/pimcore-classification-store-editor.webp\")
<\/figure>\nRuntime configuration<\/h3>\n
Admins create and toggle Keys, Groups, and Collections at runtime. Studio drives this through 29-plus CRUD controllers, not hardcoded class definitions.<\/p>\n
All this configuration is admin-facing through the Studio UI. So adding an attribute needs no class rebuild, which is the headline advantage.<\/p>\n
When to use it<\/h3>\n
Use it for catalogs where categories need radically different attribute sets. For example, shoes need size and color, electronics need wattage, furniture needs material.<\/p>\n
Without it, you would create a class per category. Classification Store avoids that attribute explosion. That is why marketplace and PIM connectors like the Pimcore Magento 2 Connector<\/a> lean on it.<\/p>\n
Storage<\/h3>\n
Classification Store uses two layers. This split is exactly why it stays extensible at runtime without a rebuild.<\/p>\n
First, the global configuration layer. Tables like
classificationstore_keys<\/code>,classificationstore_groups<\/code>, andclassificationstore_collections<\/code> define what attributes exist, and admins manage them.<\/p>\nNext, the per-object data layer. Pimcore uses
object_classificationstore_data_<classId><\/code> for values andobject_classificationstore_groups_<classId><\/code> for active groups, one pair of tables per class.<\/p>\nBecause the config layer sits apart from the data layer, you add or retire attributes without touching class definitions. Each key carries a type, a JSON definition, and an enabled flag.<\/p>\n
Localization<\/h3>\n
Localization is a per-key setting, since each key definition carries a localized flag.<\/p>\n
When the flag is true, Pimcore stores values with a language column. If it is false, the values stay language-agnostic.<\/p>\n
Programmatic access<\/h3>\n
The
ClassificationStoreFieldDataMarshaller<\/code> handles read and write. Connectors set values via$object->setClassificationStoreData()<\/code> without triggering a rebuild.<\/p>\nInheritance<\/h3>\n
A child inherits values from all of the parent’s active groups, unless you explicitly deactivate a group. Also, metadata tracks each inherited value and its source object id.<\/p>\n
The limit<\/h3>\n
Values are key\/value, not first-class columns. Because of that, filtering by a specific key needs table joins and is harder than querying a normal field.<\/p>\n
The
MarshallerService<\/code> persists values through normalization, not raw SQL types. Also, Pimcore does not support Grid and CSV export of these values.<\/p>\nDo not use it for small, fixed attribute sets. Instead, plain fields or a Field Collection fit those better.<\/p>\n
Pimcore Field Collections vs Object Bricks vs Classification Store, compared<\/h2>\n
Here is the same set of dimensions across all three.<\/p>\n
\n\n
\n \nDimension<\/th>\n Field Collections<\/th>\n Object Bricks<\/th>\n Classification Store<\/th>\n<\/tr>\n<\/thead>\n \n Shape<\/td>\n Repeatable ordered rows (1-to-many)<\/td>\n Optional single group per type<\/td>\n Sparse key\/value matrix (group \u00d7 key)<\/td>\n<\/tr>\n \n Bound to a class?<\/td>\n No, free and reusable<\/td>\n Yes, via classDefinitions<\/code><\/td>\nNo, tied to a Store<\/td>\n<\/tr>\n \n Who configures it<\/td>\n Developer, at class level<\/td>\n Developer, at class level<\/td>\n Admin, at runtime (no rebuild)<\/td>\n<\/tr>\n \n Storage table<\/td>\n Dedicated per-class FC tables<\/td>\n Per-class brick store + query tables<\/td>\n Global config tables + per-object data tables<\/td>\n<\/tr>\n \n Query support<\/td>\n Weak (separate tables, no Listing API)<\/td>\n Indexed query table per class<\/td>\n Weak (marshalled key\/value)<\/td>\n<\/tr>\n \n Localization<\/td>\n Nested Localizedfields (2-axis)<\/td>\n Inherits parent localized values<\/td>\n Per-key language column when localized<\/td>\n<\/tr>\n \n Inheritance<\/td>\n Wholesale replace on variant<\/td>\n Empty-parent-brick, per-field override<\/td>\n Per-key, activeGroups propagate<\/td>\n<\/tr>\n \n Best for<\/td>\n Repeating rows: specs, tiers, channels<\/td>\n Optional fields some objects need<\/td>\n Many attributes across varied categories<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n For queryable Field Collection fields, remember the workarounds. So run custom SQL, denormalize key fields to the base object, or load all objects and filter in memory.<\/p>\n
The built-in Listing API does not support Field Collection filtering. So plan for that before you model reporting on FC data.<\/p>\n
Which one should you use?<\/h2>\n
Match the tool to the shape of your data. These rules cover most cases.<\/p>\n
- \n
- Choose Field Collections<\/strong> when you need multiple ordered rows of the same structure. Price tiers, phone numbers, and per-channel grids fit here.<\/li>\n
- Choose Object Bricks<\/strong> when only some objects need an extra field group. An optional
Engine<\/code> orTechnicalSpecs<\/code> set is the textbook case.<\/li>\n- Choose Classification Store<\/strong> when many categories need different attribute sets. Add attributes at runtime without touching class definitions.<\/li>\n<\/ul>\n
Now the anti-patterns. These are the wrong-tool mistakes teams make most.<\/p>\n
- \n
- Avoid Classification Store for small, fixed attribute sets.<\/strong> It renders awkwardly and conflates axes; use plain fields or a Field Collection.<\/li>\n
- Skip an Object Brick when you need a repeatable list.<\/strong> One brick per type is a hard ceiling, so switch to a Field Collection.<\/li>\n
- Reconsider Field Collections when you need queryable, first-class columns.<\/strong> Filtering and reporting want denormalized fields, not separate tables.<\/li>\n<\/ul>\n
One more axis matters: who owns change. Developers own Field Collections and Bricks, which need a rebuild. Admins own Classification Store, which does not.<\/p>\n
When to reach for Pimcore Field Collections again, in one line: any time the data is a repeating, ordered set of rows you read after loading the object.<\/p>\n
Real gotchas to plan for<\/h2>\n
These traps bite teams in production. Design around them early.<\/p>\n
The variant wholesale-replace trap.<\/strong> A variant’s Field Collection replaces the parent’s entirely. There is no per-field inheritance.<\/p>\n
Set one field on a variant’s FC item, and every other field the parent carried goes blank. Only wholesale-replace when the variant truly owns the full tuple.<\/p>\n
Otherwise, implement a merge. Copy the parent’s FC item, set the one field, then append the missing rows.<\/p>\n
The variant Listing regression.<\/strong> A class Listing defaults its object types to object, variant, and folder.<\/p>\n
The moment a connector creates variant children, every existing Listing over that class starts returning variants too. Audit each Listing after you enable variants.<\/p>\n
Add
->setObjectTypes([OBJECT_TYPE_OBJECT])<\/code> wherever only top-level objects are meant.<\/p>\nClassification Store queryability.<\/strong> Its values are marshalled key\/value pairs, not columns. Cross-object filtering and reporting on specific keys stay weak.<\/p>\n
If you need heavy querying on an attribute, promote it to a real field. Reserve the store for the long tail of varied attributes.<\/p>\n
The empty-parent-brick behavior.<\/strong> Bricks inherit only because Pimcore auto-creates an empty child brick when the parent has one.<\/p>\n
An Object Brick with inheritance off gets no scaffolding. So parent values never flow down to the child.<\/p>\n
Conclusion<\/h2>\n
Pimcore Field Collections, Object Bricks, and Classification Store are not interchangeable. Each maps to a different data shape.<\/p>\n
Reach for Pimcore Field Collections when the data is repeatable ordered rows. Object Bricks fit optional field groups that only some classes need.<\/p>\n
Classification Store wins when many categories need different attributes, all configured at runtime.<\/p>\n
When you match the tool to the shape, your model stays clean and fast. Pick wrong, and you inherit awkward queries, blank variants, and needless rebuilds.<\/p>\n
Need help modeling a complex Pimcore catalog or building a connector around it? The Webkul Pimcore team<\/a> can architect the data model and the integrations for you.<\/p>\n","protected":false},"excerpt":{"rendered":"
- Skip an Object Brick when you need a repeatable list.<\/strong> One brick per type is a hard ceiling, so switch to a Field Collection.<\/li>\n
- Choose Object Bricks<\/strong> when only some objects need an extra field group. An optional
- Object Bricks<\/strong> \u2014 an optional field group that attaches to specific classes. A conditional mixin.<\/li>\n