DRAFT: Change Data Capture documentation#11464
Conversation
|
|
|
@stefanus-heath Just to confirm, can I take a look at this first draft or are you still adding content? |
|
|
||
| Expand an entity row to see each attribute and association with a checkbox. Uncheck an item to exclude it from the event payload. The **Exposed name** column lets you rename individual attributes in the payload independently of their domain model names. | ||
|
|
||
| Associations appear as nested data within the parent entity's event payload. They do not produce separate Kafka topics and show no **Revision** or **Topic** values of their own. |
There was a problem hiding this comment.
- Associations appear as list of identifiers actually, not as nested data.
- "They" here can be confusing, it might refer to only associations, since we just explained about Associations. Rephrase it so "they" applies to all entity properties (attributes and associations).
|
|
||
| ## Revisions {#revisions} | ||
|
|
||
| Each tracked entity has a **Revision** number that identifies the schema version of its event payload. Downstream consumers use the revision to detect and respond to schema changes. The revision is also embedded in the Kafka topic name, so each schema version has its own isolated topic. |
There was a problem hiding this comment.
so each schema version has its own isolated topic.
we only use the major version of the schema version in topic name. If the change is minor, then you don't get a new topic name.
There was a problem hiding this comment.
refrain from using the word version
There was a problem hiding this comment.
schema version vs revision in the doc ... I don't think we can fully avoid the word
| Studio Pro manages revisions automatically. When you modify the tracked configuration of an entity, Studio Pro marks it as **Changed** and calculates the new revision based on whether the change is breaking or non-breaking: | ||
|
|
||
| * **Minor revision** (for example, `1.0` → `1.1`) — a non-breaking change such as adding a new attribute. Existing consumers can continue reading the topic without modification. | ||
| * **Major revision** (for example, `1.0` → `2.0`) — a breaking change such as removing an attribute, renaming an entity's exposed name, or removing an entity from tracking. Consumers must be updated to use the new topic. |
There was a problem hiding this comment.
Here I assume we are talking about revision for entity. We do have revision for document but that is hidden.
The explanation here seems to be leading toward the revision for document, especially the following description "renaming an entity's exposed name, or removing an entity from tracking."
I am going to check in Studio Pro if this is true. It is possible that when you rename exposed name then you would get v1 again since the topic name is unique enough e.g. cdc.appname.newExposedName.1.{space} -> this would be a new topic in Kafka.
There was a problem hiding this comment.
I checked the Studio Pro and we do increase major version if the exposed name get renamed. I think we can leave this description as-is.
| Accepting changes confirms the new revision numbers and clears the modification states, leaving the document in a clean state ready for deployment. | ||
|
|
||
| {{% alert color="warning" %}} | ||
| A major revision creates a new Kafka topic. Consumers subscribed to the previous topic version will no longer receive events after deployment. Ensure downstream systems are updated before deploying a major revision change. |
There was a problem hiding this comment.
Ensure downstream systems are updated before deploying a major revision change.
How is this possible? I think the ordering is for provider side to deploy first, then the consumer side can get the updated topic name. The consumer are free to consume the old topic name but it won't be updated.
6 participants
No description provided.