Attribute Fields

Product attributes in Makaira are stored as nested arrays, organized by data type. This structure enables flexible filtering and faceted search across product variants.

💡

When not to use this structure

The attributeStr / attributeInt / attributeFloat arrays are designed to differentiate between variants of the same product (e.g. T-Shirt in different sizes and colors). If your catalog has no real variants — every product is a single SKU — this structure is overhead with no benefit. Use flat Dynamic Fields on the product instead (e.g. color_str_short, weight_float, is_new_bool). They are easier to produce, automatically get the correct Elasticsearch type, and are filterable and sortable out of the box.

Attribute Types

Attribute Structure

Each attribute entry contains:

Example

{
  "id": "product-123",
  "type": "product",
  "attributeStr": [
    {"id": "color", "title": "Color", "value": "Blue"},
    {"id": "material", "title": "Material", "value": "Cotton"},
    {"id": "brand", "title": "Brand", "value": "Nike"}
  ],
  "attributeInt": [
    {"id": "weight_g", "title": "Weight (g)", "value": 200},
    {"id": "pack_size", "title": "Pack Size", "value": 1}
  ],
  "attributeFloat": [
    {"id": "rating", "title": "Rating", "value": 4.5},
    {"id": "discount_percent", "title": "Discount %", "value": 15.0}
  ]
}

Multi-Value Attributes

For attributes with multiple values, use the # separator:

{
  "attributeStr": [
    {"id": "color", "title": "Color", "value": "Blue#Red#Green"},
    {"id": "size", "title": "Size", "value": "S#M#L#XL"}
  ]
}

During import, these are split into individual values for filtering.

Attribute Sub-Fields

Each attribute value has these sub-fields for different query types:

Variant Attribute Aggregation

When using the Persistence Layer, attributes from variants are automatically aggregated to the parent product.

How It Works

1. All variants with active: true AND onstock: true are included
2. Attributes are merged and deduplicated
3. Result is stored in the attributes field on the parent product

Example

Variant 1:

{"attributeStr": [{"id": "size", "value": "S"}, {"id": "color", "value": "Blue"}]}

Variant 2:

{"attributeStr": [{"id": "size", "value": "M"}, {"id": "color", "value": "Blue"}]}

Variant 3 (inactive):

{"attributeStr": [{"id": "size", "value": "L"}, {"id": "color", "value": "Red"}]}

Parent Product (aggregated):

{
  "attributes": [
    {"id": "size", "value": ["S", "M"]},
    {"id": "color", "value": ["Blue"]}
  ]
}

Note: Variant 3's attributes are excluded because it's inactive.

Without Persistence Layer: You must manually aggregate attributes in your import data.

Using Attributes in Product Streams

Attributes can be used in stream filters with this field format:

Example Stream Filter

{
  "field": "attributeStr::color",
  "type": "nested",
  "operator": "eq",
  "value": "Blue"
}

Best Practices

1. Use correct types - Put numeric values in attributeInt or attributeFloat, not attributeStr.

2. Consistent IDs - Use the same attribute id across all products for proper filtering.

3. Meaningful titles - The title field is used in filter displays.

4. Multi-values with # - Use the # separator for multi-value attributes.

5. Keep variants active - Only active and in-stock variants are aggregated to the parent.