Skip to content

Use uniqueness constraint for KG writer temp ids - #554

Open
dylothx wants to merge 2 commits into
neo4j:mainfrom
dylothx:feat/constraints-node-key
Open

Use uniqueness constraint for KG writer temp ids#554
dylothx wants to merge 2 commits into
neo4j:mainfrom
dylothx:feat/constraints-node-key

Conversation

@dylothx

@dylothx dylothx commented Jul 5, 2026

Copy link
Copy Markdown

Description

Fixes #159

Replaces the KG writer’s temporary __KGBuilder__.__tmp_internal_id range index with a uniqueness constraint.

Neo4jWriter uses __tmp_internal_id to match nodes when creating relationships during graph writes. A plain index improves lookup performance, but does not prevent duplicate temporary ids. The new uniqueness constraint preserves indexed lookup behavior while also enforcing that temporary ids are unique during the write process.

This uses a uniqueness constraint rather than a node key constraint because __tmp_internal_id is removed during writer cleanup.

Type of Change

  • New feature
  • Bug fix
  • Breaking change
  • Documentation update
  • Project configuration change

Complexity

Complexity: Low

How Has This Been Tested?

  • Unit tests
  • E2E tests
  • Manual tests

Checklist

The following requirements should have been met (depending on the changes in the branch):

  • Documentation has been updated
  • Unit tests have been updated
  • E2E tests have been updated
  • Examples have been updated
  • New files have copyright header
  • CLA (https://neo4j.com/developer/cla/) has been signed
  • CHANGELOG.md updated if appropriate

@dylothx
dylothx requested a review from a team as a code owner July 5, 2026 16:37

@AmirLayegh AmirLayegh left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thanks for the contribution! I left one comment that may be worth addressing before merging.

Also, would this fix be worth adding to CHANGELOG.md under Fixed? It changes the handling of duplicate temporary node IDs and fixes #159.

Could you also please sign the Contributor License Agreement as advised here?

""")
self.driver.execute_query(
"DROP INDEX __entity__tmp_internal_id IF EXISTS",
database_=self.neo4j_database,

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Should _db_cleaning() target self.neo4j_database as well? _db_setup(), _upsert_nodes() and _upsert_relationships() all explicitly use it, but _db_cleaning() opens self.driver.session() without specifying a database, which would use the user's home database.
If neo4j_database is different from the home database, the temporary IDs would be written to the target DB but cleaned from the home DB. With this uniqueness constraint, a subsequent write with the same temporary IDs will fail.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

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

Hey! Yes, you're right, I have pushed a fix to open the cleanup session with database=self.neo4j_database (Also rebased onto latest main to clear merge conflict). Thanks!

_db_cleaning opened a session without a database, so cleanup ran against
the user's home database while _db_setup and the upserts targeted
self.neo4j_database. When neo4j_database differed from the home database,
__tmp_internal_id values were never cleared from the target DB and the new
uniqueness constraint made subsequent writes fail. Pass
database=self.neo4j_database to session().

Also adds the missing CHANGELOG entries for the constraint change (neo4j#159)
and this fix.
@dylothx
dylothx force-pushed the feat/constraints-node-key branch from 31ad7c8 to 8592f38 Compare August 19, 2026 16:46
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Use Constraints Instead of Plain Range Index for Node keys/ids

2 participants