--- updatedAt: 2026-04-30T03:26:35.000Z agentTools: projectIndex: https://docs.makaira.io/llms.txt --- # Field Reference # 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](https://docs.makaira.io/docs/visibility-fields). For ranking inputs (`soldamount`, `rating`, `insert`, `profit_margin`, `stock`) see [Ranking Fields](https://docs.makaira.io/docs/ranking-fields). For the `attributeStr` / `attributeInt` / `attributeFloat` / `attributes` structure see [Attribute Fields](https://docs.makaira.io/docs/attribute-fields). For custom suffixed fields like `*_int`, `*_bool`, `*_str_short` see [Dynamic Fields](https://docs.makaira.io/docs/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](https://docs.makaira.io/docs/dynamic-fields)). | | `groups` | object | Group-specific overrides for prices, stock, and visibility — e.g. discount tiers, B2B pricing. See [B2B / Customer Groups](https://docs.makaira.io/docs/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](https://docs.makaira.io/docs/other-systems#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` | ## Related Documentation * [Visibility Fields](https://docs.makaira.io/docs/visibility-fields) - Control what appears in search results * [Ranking Fields](https://docs.makaira.io/docs/ranking-fields) - Boost and ranking configuration * [Dynamic Fields](https://docs.makaira.io/docs/dynamic-fields) - Custom field naming conventions * [Attribute Fields](https://docs.makaira.io/docs/attribute-fields) - Product attributes structure