Skip to content

Clarify the order of changes in CDC #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nvitucci merged 5 commits into from
Jan 20, 2025
Merged

Clarify the order of changes in CDC #73

Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
088a080
Clarify the order of changes
nvitucci Jan 17, 2025
dd4c04c
Add ref to new section
nvitucci Jan 17, 2025
438de19
Change wording
nvitucci Jan 17, 2025
0ddf422
Updates following review
nvitucci Jan 20, 2025
f68f3c1
More review
nvitucci Jan 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion modules/ROOT/pages/procedures/output-schema.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ It can be used to query changes from this change onward.
<2> A number identifying which transaction the change happened in, unique in combination with `seq`.
Transaction identifiers are not continuous (some transactions, such as system and schema commands, are not recorded in change data capture and cause gaps in the transaction identifiers).
<3> A number used for ordering changes that happened in the same transaction.
The order of changes observed in the output does not necessarily correspond to the order in which changes were applied during the transaction.
The order of changes observed in the output does not necessarily correspond to the order in which changes were applied during the transaction (see <<order>>).
<4> The user that performed this change.
May be different from `authenticatedUser` when using link:https://neo4j.com/docs/operations-manual/current/authentication-authorization/dbms-administration/#access-control-dbms-administration-impersonation[impersonation].
<5> The authenticated user when this change was performed.
Expand Down Expand Up @@ -171,3 +171,19 @@ Only the differences are annotated below.
<7> Relationship type.
<8> The keys identifying the changed entity.
This requires key constraints defined on the changed entities, see xref:procedures/elementids-key-properties.adoc[] for details.

[#order]
== Order of changes

The changes from a transaction are tracked as change events in the following order:

* Node creation
* Relationship creation
* Node labels/properties updates
* Relationship properties updates
* Node deletions
* Relationship deletions

Note that the order of changes in the output is **not guaranteed** to match exactly the order of changes occurring in the transaction.
Copy link
Contributor

@stefano-ottolenghi stefano-ottolenghi Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd put this as leading sentence for the section (without Note that), as the listed ordering is a further explanation.

Copy link
Contributor Author

@nvitucci nvitucci Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think of this as a clarification instead, since the section is about the order within the output rather than in the transaction, but I'm fine either way. I'm including the change.


CDC tracks logical changes only; therefore, if two or more changes cancel each other (for example, a `DELETE` following a `CREATE` on the same node), none is included in the change stream.
Copy link
Contributor

@stefano-ottolenghi stefano-ottolenghi Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
CDC tracks logical changes only; therefore, if two or more changes cancel each other (for example, a `DELETE` following a `CREATE` on the same node), none is included in the change stream.
CDC tracks logical changes only: if two or more changes cancel each other out (for example, a `DELETE` following a `CREATE` on the same node), none is included in the change stream.

Also, is logical the right term here? It may be and I just don't know it; otherwise, something like effective could be more descriptive.

Copy link
Contributor Author

@nvitucci nvitucci Jan 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch for the missing out.

I think logical is the right term here, as opposed to physical (see also the question on the forum that sparked this update), both commonly used in database-related topics. If we want to make it less technical (if slightly more ambiguous), we could use actual.

Copy link
Contributor Author

@nvitucci nvitucci Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(Or remove it altogether.)

Copy link
Contributor

@stefano-ottolenghi stefano-ottolenghi Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think actual makes it more ambiguous; if anything, I think logical vs physical is ambiguous. What's the physical change? Is it the bits being altered in the file containing the changed entity? Is it a struct field being rewritten? Or is, as Rory says in that topic, the creation of a whole graph entity? That's much more ambiguous to me, and so is logical.

Copy link
Contributor Author

@nvitucci nvitucci Jan 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's go with actual then.

Loading