fix: remap parent id after hashing (#4245)

badGarnet · web-flow · commit e2d8b7ae0d41 · 2026-02-19T15:24:31.000Z
This PR addresses an issue where hashing element id loses the reference
for parent id.
This happens when calling `partition_html` where the partition process
already assigned parent ids for elements based on html structure before
`apply_metadata` is called, i.e., before element id hashing happens.
This fix ensures that the parent references stay unchanged after
hashing.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## 0.20.6
+
+- fix: remap parent id after hashing to preserve right reference
+
 ## 0.20.5
 
 ### Fixes
diff --git a/test_unstructured/partition/common/test_metadata.py b/test_unstructured/partition/common/test_metadata.py
@@ -482,3 +482,59 @@ def test_assign_hash_ids_produces_unique_and_deterministic_SHA1_ids_even_for_dup
     assert len(ids) == len(set(ids))
     # -- ids are deterministic, same value is computed each time --
     assert all(e.id == e2.id for e, e2 in zip(elements, elements_2))
+
+
+def test_assign_hash_ids_remaps_parent_id_to_new_hash_id():
+    """parent_id values (originally UUIDs) are updated to the corresponding hash IDs."""
+    title = Title(text="Title", metadata=ElementMetadata(filename="foo.bar", page_number=1))
+    child = Text(
+        text="Child",
+        metadata=ElementMetadata(filename="foo.bar", page_number=1, parent_id=title.id),
+    )
+    # -- sanity-check: ids are UUIDs before hashing --
+    assert len(title.id) == 36
+    assert child.metadata.parent_id == title.id
+
+    _assign_hash_ids([title, child])
+
+    # -- ids are now SHA1 hashes --
+    assert len(title.id) == 32
+    # -- parent_id has been updated to the new hash id, not the old UUID --
+    assert child.metadata.parent_id == title.id
+
+
+def test_assign_hash_ids_leaves_unknown_parent_id_unchanged():
+    """A parent_id that has no matching element (e.g. filtered out) is left as-is, not KeyError."""
+    external_parent_id = "some-external-or-filtered-id"
+    orphan = Text(
+        text="Orphan",
+        metadata=ElementMetadata(filename="foo.bar", page_number=1, parent_id=external_parent_id),
+    )
+
+    # -- should not raise KeyError even though external_parent_id is not in id_mapping --
+    _assign_hash_ids([orphan])
+
+    # -- parent_id is left unchanged because it wasn't in the mapping --
+    assert orphan.metadata.parent_id == external_parent_id
+
+
+def test_partition_html_parent_child_relationships_preserved_with_hash_ids():
+    """Integration: partition_html with unique_element_ids=False preserves parent-child links."""
+    from unstructured.partition.html import partition_html
+
+    html = "<html><body><h1>My Title</h1><p>My paragraph</p></body></html>"
+    elements = partition_html(text=html, unique_element_ids=False)
+
+    # -- all element ids should be SHA1 hashes (32 hex chars), not UUIDs (36 chars) --
+    assert all(len(e.id) == 32 for e in elements), "Expected SHA1 hash IDs"
+
+    # -- find the title and its child paragraph --
+    title = next((e for e in elements if isinstance(e, Title)), None)
+    child = next(
+        (e for e in elements if e.metadata.parent_id is not None),
+        None,
+    )
+    assert title is not None, "Expected a Title element"
+    assert child is not None, "Expected at least one element with a parent_id"
+    # -- parent_id must point to the hashed title id, not an old UUID --
+    assert child.metadata.parent_id == title.id
diff --git a/unstructured/__version__.py b/unstructured/__version__.py
@@ -1 +1 @@
-__version__ = "0.20.5"  # pragma: no cover
+__version__ = "0.20.6"  # pragma: no cover
diff --git a/unstructured/partition/common/metadata.py b/unstructured/partition/common/metadata.py
@@ -244,20 +244,32 @@ def wrapper(*args: _P.args, **kwargs: _P.kwargs) -> list[Element]:
 
 
 def _assign_hash_ids(elements: list[Element]) -> list[Element]:
-    """Converts `.id` of each element from UUID to hash.
+    """Converts `.id` of each element from UUID to hash and remaps `parent_id` accordingly.
 
     The hash is based on the `.text` of the element, but also on its page-number and sequence number
     on that page. This provides for deterministic results even when the document is split into one
     or more fragments for parallel processing.
+
+    After hashing, any `element.metadata.parent_id` that references a known original UUID is
+    updated to the corresponding new hash ID. Parent IDs that do not appear in the mapping (e.g.
+    because the parent element was filtered out before hashing, or the ID was set manually to an
+    external value) are left unchanged.
     """
     # -- generate sequence number for each element on a page --
     page_seq_counts = {}
+    id_mapping = {}
     for element in elements:
         page_number = element.metadata.page_number
         seq_on_page_counter = page_seq_counts.get(page_number, 0)
+        original_id = element.id
         element.id_to_hash(seq_on_page_counter)
+        id_mapping[original_id] = element.id
         page_seq_counts[page_number] = seq_on_page_counter + 1
 
+    for element in elements:
+        if element.metadata.parent_id is not None and element.metadata.parent_id in id_mapping:
+            element.metadata.parent_id = id_mapping[element.metadata.parent_id]
+
     return elements
 
 

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-__version__ = "0.20.5" # pragma: no cover`
	`1`	`+__version__ = "0.20.6" # pragma: no cover`