Change Data Capture (CDC)

Change Data Capture (CDC) обеспечивает захват изменений строк таблицы YDB, формирует из них поток изменений (changefeed), записывает в распределенное хранилище и предоставляет доступ к этим записям для дальнейшей обработки. В качестве распределенного хранилища используется топик, который позволяет эффективно хранить лог изменений таблицы.

Когда в таблице добавляется, обновляется или удаляется строка, CDC формирует запись о произошедшем изменении с указанием первичного ключа строки и пишет ее в соответствующую данному ключу партицию топика.

Гарантии

  • Записи об изменении шардированы между партициями топика по первичному ключу.
  • Каждое изменение доставляется ровно один раз (exactly-once семантика).
  • Изменения по одному и тому же первичному ключу доставляются в том же порядке, в котором они происходили в таблице в одну и ту же партицию топика.

Ограничения

  • Количество партиций топика фиксируется на момент создания потока изменений и остается неизменным (топики, в отличие от таблиц, не являются эластичными).

  • В потоке изменений поддерживаются записи о следующих видах операций:

    • обновление;
    • удаление.

    Таким образом, добавление строки является частным случаем обновления, и в потоке изменений запись о добавлении строки будет выглядеть аналогично записи об обновлении.

Структура записи

В зависимости от параметров потока структура записи может отличаться.

Запись в формате JSON имеет следующую структуру:

{
    "key": [<key components>],
    "update": {<columns>},
    "erase": {},
    "newImage": {<columns>},
    "oldImage": {<columns>}
}
  • key — массив значений компонент первичного ключа. Присутствует всегда.
  • update — признак обновления. Присутствует, если запись соответствует операции обновления. В режиме UPDATES так же содержит названия и значения изменившихся столбцов.
  • erase — признак удаления. Присутствует, если запись соответствует операции удаления.
  • newImage — снимок состояния строки, получившегося в результате изменения. Присутствует в режимах NEW_IMAGE и NEW_AND_OLD_IMAGES. Содержит названия и значения столбцов.
  • oldImage — снимок состояния строки, предшествовавшего изменению. Присутствует в режимах OLD_IMAGE и NEW_AND_OLD_IMAGES. Содержит названия и значения столбцов.

Например, запись об обновлении в режиме UPDATES:

{
   "key": [1, "one"],
   "update": {
       "payload": "lorem ipsum",
       "date": "2022-02-22"
   }
}

Запись об удалении:

{
   "key": [2, "two"],
   "erase": {}
}

Запись со снимками строки:

{
   "key": [1, 2, 3],
   "update": {},
   "newImage": {
       "textColumn": "value1",
       "intColumn": 101,
       "boolColumn": true
   },
   "oldImage": {
       "textColumn": null,
       "intColumn": 100,
       "boolColumn": false
   }
}

Примечание

  • Одна и та же запись не может содержать поля update и erase одновременно, так как эти поля являются признаками операции (невозможно одновременно обновить и удалить строку таблицы). Но каждая запись содержит одно из этих полей (любая операция является обновлением или удалением).
  • В режиме UPDATES для операций обновления поле update выполняет роль не только признака операции (обновление), но и содержит названия и значения изменившихся столбцов.
  • Поля JSON-объекта, содержащие названия и значения столбцов (newImage, oldImage и update в режиме UPDATES), не включают в себя столбцы, являющиеся компонентами первичного ключа.
  • Если в записи присутствует поле erase (то есть запись соответствует операции удаления), то это всегда пустой JSON-объект ({}).

Создание и удаление потока изменений

Поток изменений может быть добавлен к существующей таблице или удален директивами ADD CHANGEFEED и DROP CHANGEFEED операции YQL ALTER TABLE. При удалении таблицы добавленный к ней поток изменений также будет удален.

Назначение и применение CDC

Об использовании CDC при разработке приложений смотрите в рекомендациях.