Import Fields

This document describes the fields used during data import into Makaira, including the request structure and document fields.

Target location: This content should be added to Getting Started > Persistence Layer or Development > Core concepts > Importer in the documentation.

Import Request Structure

Persistence Layer API

{
  "import_timestamp": "2024-01-15 10:30:00",
  "source_identifier": "my-shop-system",
  "rebuild": false,
  "items": [
    {
      "source_revision": 1,
      "delete": false,
      "language_id": "de",
      "data": {
        // Document fields here
      }
    }
  ]
}

Request Fields

Field	Type	Required	Description
`import_timestamp`	string	Yes	Timestamp of the import (`yyyy-MM-dd HH:mm:ss`)
`source_identifier`	string	Yes	Identifies the data source
`rebuild`	boolean	No	Set to `true` for full rebuild
`items`	array	Yes	Array of items to import

Item Fields

Field	Type	Required	Description
`source_revision`	integer	Yes	Version number from source system
`delete`	boolean	No	Set to `true` to delete the document
`language_id`	string	Yes	Language code (e.g., `"de"`, `"en"`)
`data`	object	Yes	The actual document data

Required Document Fields

Every document must include these fields:

Field	Type	Description
`id`	string	Unique identifier
`type`	string	`product`, `variant`, `category`, or `manufacturer`
`active`	boolean	Whether the document is active
`shop`	string	Shop identifier

Additional Required Fields by Type

Products and Variants:

Field	Type	Description
`title`	string	Product title
`onstock`	boolean	Stock availability

Variants only:

Field	Type	Description
`parent`	string	Parent product ID
`isVariant`	boolean	Must be `true`

Import Examples

Minimal Product

{
  "import_timestamp": "2024-01-15 10:30:00",
  "source_identifier": "my-shop",
  "items": [
    {
      "source_revision": 1,
      "language_id": "de",
      "data": {
        "id": "product-001",
        "type": "product",
        "active": true,
        "onstock": true,
        "shop": "shop1",
        "title": "Blue T-Shirt"
      }
    }
  ]
}

Complete Product with Variant

{
  "import_timestamp": "2024-01-15 10:30:00",
  "source_identifier": "my-shop",
  "items": [
    {
      "source_revision": 100,
      "language_id": "de",
      "data": {
        "id": "product-001",
        "type": "product",
        "active": true,
        "onstock": true,
        "hidden": false,
        "searchable": true,
        "shop": "shop1",
        "title": "Blue T-Shirt",
        "shortdesc": "Comfortable cotton t-shirt",
        "longdesc": "This premium t-shirt is made from 100% organic cotton...",
        "url": "/products/blue-t-shirt",
        "ean": "4012345678901",
        "price": 29.99,
        "stock": 100,
        "timestamp": "2024-01-15 10:30:00",
        "insert": "2024-01-01",
        "soldamount": 150,
        "rating": 4.5,
        "picture_url_main": "https://cdn.example.com/blue-t-shirt.jpg",
        "manufacturer_title": "PremiumWear",
        "category": [
          {"catid": "cat-clothing", "path": "Clothing > T-Shirts", "pos": 1}
        ],
        "attributeStr": [
          {"id": "color", "title": "Color", "value": "Blue"},
          {"id": "material", "title": "Material", "value": "Cotton"}
        ]
      }
    },
    {
      "source_revision": 101,
      "language_id": "de",
      "data": {
        "id": "variant-001-S",
        "type": "variant",
        "parent": "product-001",
        "isVariant": true,
        "active": true,
        "onstock": true,
        "shop": "shop1",
        "title": "Blue T-Shirt - Size S",
        "price": 29.99,
        "ean": "4012345678902",
        "attributeStr": [
          {"id": "size", "title": "Size", "value": "S"}
        ]
      }
    }
  ]
}

Manufacturer

{
  "source_revision": 1,
  "language_id": "de",
  "data": {
    "id": "manufacturer-premiumwear",
    "type": "manufacturer",
    "active": true,
    "shop": "shop1",
    "title": "PremiumWear",
    "manufacturer_title": "PremiumWear",
    "url": "/brands/premiumwear"
  }
}

Delete Document

{
  "source_revision": 102,
  "delete": true,
  "language_id": "de",
  "data": {
    "id": "product-to-delete",
    "type": "product"
  }
}

Generated Fields

The importer automatically generates these fields:

Field	Description
`es_id`	Elasticsearch document ID (`{id}_{datatype}`)
`datatype`	Normalized type (`makaira-productgroup`, `makaira-product`, etc.)
`join_field`	Parent-child relationship structure
`makairaImport`	Import timestamp (ISO 8601)
`sequence`	Internal revision number
`suggest`	Autocomplete suggestions (from `title`)

Rebuild vs. Delta Import

Delta Import (default)

Only changed documents are processed
Use source_revision to track changes
Faster for incremental updates

Full Rebuild

Set rebuild: true to:

Replace all documents of a type
Clean up orphaned data
Ensure index consistency

{
  "import_timestamp": "2024-01-15 10:30:00",
  "source_identifier": "my-shop",
  "rebuild": true,
  "items": [...]
}

Best Practices

Unique IDs - Ensure id is unique within each type.
Consistent source_revision - Increment for each change to enable delta imports.
Provide all required fields - Missing required fields cause import failures.
Use correct types - Match type to your document kind (product, variant, category, manufacturer).
Parent before variants - Import parent products before their variants.
Set timestamps - Include timestamp and insert for ranking features.