Interface ChangeRecord


@EvolvingApi
public interface ChangeRecord
Information pertaining to a single data change event (insertion, delete or update), affecting a single database record.

Each event has a key, identifying the affected record, and a value, describing the change to that record.

Most events have an operation which specifies the type of change (insertion, delete or update). Events without an operation have specialized usage, for example heartbeats, and aren't supposed to affect the data model. You can observe and act upon them in a Jet CDC sink, but we discourage such usage.

All events have a timestamp specifying the moment when the change event occurred in the database. Normally this is the timestamp recorded in the database's change log, but since it has a finite size, the change stream begins with virtual events that reproduce the state of the table at the start of the change log. These events have an artificial timestamp. In principle, it should be easy to identify them because they have a separate SYNC operation instead of INSERT, however some databases emit INSERT events in both cases (a notable example is MySQL).

Since:
4.2
  • Method Summary

    Modifier and Type Method Description
    String database()
    Returns the name of the database containing the record's table.
    RecordPart key()
    Returns the key part of the CDC event.
    Operation operation()
    Returns the type of change this record describes (insert, delete or update).
    String schema()
    Returns the name of the schema containing the record's table.
    String table()
    Returns the name of the table this record is part of.
    long timestamp()
    Specifies the moment when the change event occurred in the database.
    String toJson()
    Returns the raw JSON string from the CDC event underlying this ChangeRecord.
    RecordPart value()
    Returns the value part of the CDC event.
  • Method Details

    • timestamp

      long timestamp() throws ParsingException
      Specifies the moment when the change event occurred in the database. Normally this is the timestamp recorded in the database's change log, but since it has a finite size, the change stream begins with virtual events that reproduce the state of the table at the start of the change log. These events have an artificial timestamp. In principle, it should be easy to identify them because they have a separate SYNC operation instead of INSERT, however some databases emit INSERT events in both cases (a notable example is MySQL).
      Throws:
      ParsingException - if the timestamp field isn't present or is unparsable
    • operation

      @Nonnull Operation operation() throws ParsingException
      Returns the type of change this record describes (insert, delete or update). Some special events, like heartbeats, don't have an operation value.
      Returns:
      Operation.UNSPECIFIED if this ChangeRecord doesn't have an operation field, otherwise the appropriate Operation that matches the CDC record's operation field
      Throws:
      ParsingException - if there is an operation field, but its value is not among the handled ones.
    • database

      @Nonnull String database() throws ParsingException
      Returns the name of the database containing the record's table.
      Returns:
      name of the source database for the current record
      Throws:
      ParsingException - if the database name field isn't present or is unparsable
    • schema

      Returns the name of the schema containing the record's table. Note: not all databases have the concept of a schema (for example MySQL).
      Returns:
      name of the source schema for the current record
      Throws:
      ParsingException - if the schema name field isn't present or is unparsable
      UnsupportedOperationException
    • table

      Returns the name of the table this record is part of.
      Returns:
      name of the source table for the current record
      Throws:
      ParsingException - if the table name field isn't present or is unparsable
    • key

      Returns the key part of the CDC event. It identifies the affected record.
    • value

      Returns the value part of the CDC event. It includes fields like the timestamp, operation, and database record data.
    • toJson

      @Nonnull String toJson()
      Returns the raw JSON string from the CDC event underlying this ChangeRecord. You can use it if higher-level parsing (see other methods) fails for some reason (for example on some untested combination of database connector and version).