Формат загрузки данных

Содержание раздела

1. Структура сообщений
2. Формат данных
3. Примеры
   1. Пример сообщения, загружаемого в логическую таблицу
      1. Пример схемы данных Avro
      2. Пример записей Avro
   2. Пример сообщения, загружаемого в standalone-таблицу
      1. Пример схемы данных Avro
      2. Пример записей Avro

Структура сообщений

Данные загружаются в систему в виде сообщений топиков Kafka. Каждое сообщение имеет структуру, показанную на рисунке ниже.

Структура загружаемых сообщений

Формат данных

Система не валидирует данные при их загрузке. Данные должны быть проверены на соответствие формату загрузки и, если нужно, скорректированы внешней системой перед их загрузкой в Prostore.

Для успешной загрузки данные должны соответствовать следующим условиям:

• Формат сообщений Kafka:
  • Данные загружаются как сообщения Kafka.
  • Сообщения состоят из ключа и тела.
  • Требования к ключу сообщения не предъявляются.
  • Тело сообщения представляет собой файл Avro (Object Container File), состоящий из заголовка со схемой данных и блоков с записями.
• Схема данных Avro:
  • В схеме определены тип record, имя и перечень полей.
  • Поля имеют имя и тип данных Avro из списка поддерживаемых для загрузки (альтернативно можно использовать unions).
  • Если данные предназначены для логической или снапшот-таблицы, последним задано поле sys_op типа avro.int.
  • Если данные предназначены для прокси- или standalone-таблица, поле sys_op отсутствует.
• Записи Avro:
  • Блоки записей представлены в бинарной кодировке.
  • Каждая запись соответствует схеме (порядок, имена, типы данных полей).
  • В записях, предназначенных для логической или снапшот-таблицы, последним задано поле sys_op со значением:
    • 0 — если запись добавляется или обновляется;
    • 1 — если запись удаляется.
  • В записях, предназначенных для прокси или standalone-таблицы, поле sys_op отсутствует.
• Структура данных (порядок, имена* и типы данных полей) согласована:
  • в схеме данных,
  • в наборе загружаемых записей,
  • во внешней таблице загрузки (кроме поля sys_op, которое должно отсутствовать),
  • в целевой таблице (кроме поля sys_op, которое должно отсутствовать).

* В схеме данных и записях Avro важны порядок и тип полей. Имена полей не сравниваются с именами полей внешней таблицы и целевой таблицы.

Подробнее о формате Avro см. в официальной документации на сайте https://avro.apache.org.

Примеры

Пример сообщения, загружаемого в логическую таблицу

Пример схемы данных Avro

Пример ниже содержит схему данных Avro, используемую для загрузки данных о продажах в логическую таблицу sales. Для поля transaction_date указан логический тип Avro, для поля description — элемент union.

Для наглядности примера бинарные данные представлены в JSON-формате.

{
  "name": "sales",
  "type": "record",
  "fields": [
    {
      "name": "id",
      "type": "long"
    },
    {
      "name": "transaction_date",
      "type": "long",
      "logicalType": "timestamp-micros"
    },
    {
      "name": "product_code",
      "type": "string"
    },
    {
      "name": "product_units",
      "type": "long"
    },
    {
      "name": "store_id",
      "type": "long"
    },
    {
      "name": "description",
      "type": [
        "null",
        "string"
      ]
    },
    {
      "name": "sys_op",
      "type": "int"
    }
  ]
}

Пример записей Avro

Пример ниже содержит набор записей о продажах, загружаемых в логическую таблицу sales. Для наглядности примера бинарные данные представлены в JSON-формате.

[
  {
    "id": 1000111,
    "transaction_date": 1614269474000000,
    "product_code": "ABC102101",
    "product_units": 2,
    "store_id": 1000012345,
    "description": "Покупка по акции 1+1",
    "sys_op": 0
  },
  {
    "id": 1000112,
    "transaction_date": 1614334214000000,
    "product_code": "ABC102001",
    "product_units": 1,
    "store_id": 1000000123,
    "description": "Покупка без акций",
    "sys_op": 0
  },
  {
    "id": 1000020,
    "transaction_date": 1614636614000000,
    "product_code": "ABC102010",
    "product_units": 4,
    "store_id": 1000000123,
    "description": "Покупка по акции 1+1",
    "sys_op": 1
  }
]

Пример сообщения, загружаемого в standalone-таблицу

Пример схемы данных Avro

Пример ниже содержит схему данных Avro, используемую для загрузки данных в standalone-таблицу, на которую указывает внешняя writable-таблица agreements_ext_write_adp. Для полей signature_date, effective_date и closing_date указан логический тип Avro, для поля description — элемент union.

Для наглядности примера бинарные данные представлены в JSON-формате.

{
  "name": "agreements",
  "type": "record",
  "fields": [
    {
      "name": "id",
      "type": "long"
    },
    {
      "name": "client_id",
      "type": "long"
    },
    {
      "name": "number",
      "type": "string"
    },
    {
      "name": "signature_date",
      "type": {
        "type": "int",
        "logicalType": "date"
      }
    },
    {
      "name": "effective_date",
      "type": {
        "type": "int",
        "logicalType": "date"
      }
    },
    {
      "name": "closing_date",
      "type": {
        "type": "int",
        "logicalType": "date"
      }
    },
    {
      "name": "description",
      "type":
      [
        "null",
        "string"
      ]
    }
  ]
}

Пример записей Avro

Пример ниже содержит набор записей, загружаемых в standalone-таблицу, на которую указывает внешняя writable-таблица agreements_ext_write_adp. Для наглядности примера бинарные данные представлены в JSON-формате.

[
  {
    "id": 1000111,
    "client_id": 1614200,
    "number": "ABC102101",
    "signature_date": 18594,
    "effective_date": 18594,
    "closing_date": 22974,
    "description": "Договор с ООО \"Треугольник\""
  },
  {
    "id": 1000112,
    "transaction_date": 1614201,
    "number": "ABC102101",
    "signature_date": 18704,
    "effective_date": 18704,
    "closing_date": 23084,
    "description": ""
  }
]