ENG-2292 - Add distance column to StagedResourceAncestor

[vcruces]

Ticket ENG-2292

Description Of Changes

This PR adds a distance column to the StagedResourceAncestor table to track the hierarchical distance between resources in their ancestor relationships. The distance is calculated based on URN segment depth (e.g., database → schema = 1, database → table = 2, database → field = 3).

The implementation includes a database migration, backfill script to populate existing records, and tests.

Code Changes

• Added distance column (nullable integer) to StagedResourceAncestor table
• Created migration with conditional index creation based on table size
• Implemented backfill script backfill_stagedresrouceancestor_distance.py that calculates distance from URN segment counts
• Integrated distance backfill into post-upgrade process and admin backfill status endpoint
• Updated StagedResourceAncestor.create_all_staged_resource_ancestor_links() to accept and store distance values
• Added ix_staged_resource_ancestor_desc_anc_dist index on [descendant_urn, ancestor_urn, distance]
• Updated all related tests to handle distance field in ancestor relationships

Steps to Confirm

1. Run the migration and verify distance column is added to stagedresourceancestor table
2. Verify backfill process correctly calculates distances based on URN segments
3. Check admin endpoint /api/v1/admin/backfills/status includes distance backfill status
4. Verify downgrade migration properly removes the column and clears backfill history

Pre-Merge Checklist

• Issue requirements met
• All CI pipelines succeeded
• CHANGELOG.md updated
  • Add a db-migration This indicates that a change includes a database migration label to the entry if your change includes a DB migration
  • Add a high-risk This issue suggests changes that have a high-probability of breaking existing code label to the entry if your change includes a high-risk change (i.e. potential for performance impact or unexpected regression) that should be flagged
  • Updates unreleased work already in Changelog, no new entry necessary
• UX feedback:
  • All UX related changes have been reviewed by a designer
  • No UX review needed
• Followup issues:
  • Followup issues created
  • No followup issues
• Database migrations:
  • Ensure that your downrev is up to date with the latest revision on main
  • Ensure that your downgrade() migration is correct and works
    • If a downgrade migration is not possible for this change, please call this out in the PR description!
  • No migrations
• Documentation:
  • Documentation complete, PR opened in fidesdocs
  • Documentation issue created in fidesdocs
  • If there are any new client scopes created as part of the pull request, remember to update public-facing documentation that references our scope registry
  • No documentation updates required

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
fides-plus-nightly	Ignored	Preview	Feb 9, 2026 2:19pm
fides-privacy-center	Ignored		Feb 9, 2026 2:19pm