Field Reference

This section documents the fields used by Makaira, including both customer-provided fields and internally generated fields.

Data Sources

Makaira can receive product data from multiple sources:

Source	Description
Shop Connectors	Direct integration with OXID, Shopware, Plentymarkets, Shopify
NDJSON Import	Newline-delimited JSON file imports
Persistence Layer	Optional intermediate storage with boost calculations
API Push	Direct data push via REST API

Field Categories

Customer-Provided Fields

These are the standard fields recognized by Makaira on product, variant, category, and manufacturer documents. Fields that are strictly required are marked Required; everything else is optional but typically expected for a usable storefront.

For visibility flags (active, hidden, searchable, hideOnLists, onstock) see Visibility Fields. For ranking inputs (soldamount, rating, insert, profit_margin, stock) see Ranking Fields. For the attributeStr / attributeInt / attributeFloat / attributes structure see Attribute Fields. For custom suffixed fields like *_int, *_bool, *_str_short see Dynamic Fields.

Identification

Field	Type	Description
`id`	string	Required. Unique document identifier within the type.
`type`	string	Required. `product`, `variant`, `category`, `manufacturer`, or a custom string for own document types.
`parent`	string	Required for variants — ID of the parent product. Must be empty (`""`) on a product.
`shop`	string	Required. Shop identifier — used for multi-shop installations.
`timestamp`	string	Export timestamp in `YYYY-MM-DD HH:MM:SS` format.

Display

Field	Type	Description
`title`	string	Required. Document title. Indexed with full text processing (stemming, compound words, etc.).
`shortdesc`	string	Short description / teaser. Indexed for full-text search.
`longdesc`	string	Long product description. Indexed for full-text search.
`url`	string	Frontend URL of the document. Used for linking in storefront and admin UI.
`picture_url_main`	string	URL of the main product image. Used in admin previews and search results.
`meta_keywords`	string	SEO meta keywords. Indexed for search.
`meta_description`	string	SEO meta description.
`raw_title`	string	Alternative title without word processing — only exact matches will hit. Mostly used for custom document types.

Search

Field	Type	Description
`searchkeys`	string	Additional search terms (synonyms, alternate spellings, related keywords). Indexed alongside the title for full-text search.
`ean`	string	EAN / SKU / article number. Used by the internal article-number search (`ProductNumber` request type) for exact and alphanumeric matches — keep this filled if customers search by article numbers.

Commerce

Field	Type	Description
`price`	float	Standard product price. Any field name containing `price` is automatically mapped to `double` (see Dynamic Fields).
`groups`	object	Group-specific overrides for prices, stock, and visibility — e.g. discount tiers, B2B pricing. See B2B / Customer Groups.

Manufacturer / Brand

Field	Type	Description
`manufacturerid`	string	ID of the manufacturer document — links the product to its manufacturer.
`manufacturer_title`	string	Manufacturer / brand name (denormalized for filtering and display).

Category Assignment (on products and variants)

Field	Type	Description
`maincategory`	string	ID of the primary category. Used for category-bound personalization and "main category" logic.
`maincategoryurl`	string	URL of the primary category.
`category`	nested array	Per-shop list of category memberships: `catid`, `shopid[]`, `path`, `title`, optional `pos` (position of the product within that category).

For category documents themselves see the Type category section in the NDJSON guide.

Sorting

Field	Type	Description
`sort`	integer	Sort hint within a level (mainly for category ordering). Set to `1` for no sorting.

Makaira-Generated Fields

These fields are created automatically during import:

Field	Description
`es_id`	Elasticsearch document ID (`{id}_{datatype}`)
`datatype`	Normalized document type
`join_field`	Parent-child relationship structure
`makairaImport`	Import timestamp (ISO 8601)
`sequence`	Change tracking number
`suggest`	Autocomplete suggestions

Optional Processing (Persistence Layer)

When using the Persistence Layer, these additional fields are generated:

Field	Description
`mak_boost_norm_*`	Normalized boost scores (0-1)
`isPseudo`	Pseudo-variant marker
`isVariant`	Variant type indicator
`attributes`	Aggregated attributes from variants

Document Type Mapping

Each imported document is stored with a normalized datatype field. You will see this value in API responses and when filtering documents directly.

Your `type`	Internal `datatype`	Description
`product`	`makaira-productgroup`	Parent product (contains variants)
`variant`	`makaira-product`	Product variant (child of product)
`category`	`category`	Category document
`manufacturer`	`manufacturer`	Manufacturer/brand document

Note: The naming is historical: a product document gets datatype: makaira-productgroup because it groups its variants, and a variant document gets datatype: makaira-product because it represents the actual purchasable SKU.

Field Suffixes

When filtering or sorting, use these suffixes:

Suffix	Purpose	Example
`.unanalyzed`	Exact matching	`title.unanalyzed`
`.lowercase`	Case-insensitive matching	`manufacturer_title.lowercase`
`.sorting`	Alphabetical sorting	`title.sorting`