Branch history provides a detailed account of all changes added to the business table to store and manage edits for the default version since the dataset was registered as branch versioned.
For branch versioning, the administration workflow is streamlined due to a simplified data model. Branch versioning operates on a temporal (time-related) insert-only model, where all edits are recorded in a single table. The insert-only model means that each edit operation results in an insert with a corresponding timestamp, allowing for a complete historical record of all modifications, including deletions. This method allows for the visualization and analysis of data to evolve over time.
Unlike traditional versioning, which relies on delta tables and joins them with other system tables to represent data for a particular version, branch-versioned feature classes are designed to support archiving natively using a single-table model. Once a dataset is registered as branch-versioned, archiving is automatically enabled, and additional fields are added to the business table to store and manage edits between versions.
To manage all edits (inserts, updates, and deletes), six specific system fields are added to the business table of the branch-versioned feature class or table.
- GDB_BRANCH_ID—Identifies the version where the edit was made.
- GDB_FROM_DATE—Records the exact date and time when an edit is made.
- GDB_IS_DELETE—Indicates whether a feature has been deleted, using a binary value (0 for not deleted / 1 or 2 for deleted).
- GDB_DELETED_AT—Records the date and time when a feature is deleted.
- GDB_DELETED_BY—Records the user who deleted the feature.
- GDB_ARCHIVE_OID—Uniquely identifies each row in the table, tracking every edit with a distinct ID.
Note:
The GDB_DELETED_AT and GDB_DELETED_BY fields are added to the feature class or table and allow tracking of deletions; these work in conjunction with the standard editor tracking fields.
Learn more about the requirements and process to register a dataset as branch versioned
There are various uses for archived data, including the following:
- Conducting historical analysis and reporting
- Ensuring compliance through auditing
- Exporting the dataset as it existed at a specific point in time
Prune branch history
Over time, data in the business table grows due to the branch versioning model, which tracks all changes by inserting new records for each edit possibly leading to significant data accumulation. Pruning the history of a branch versioned dataset involves removing historical records that are no longer needed, optimizing storage, and improving performance.
Pruning is necessary for managing the growth of historical data, which can consume considerable storage over time. It is recommended to prune archived records from a dataset under certain circumstances, such as the following:
- When historical data is no longer needed for operational purposes
- To free up storage space by eliminating unnecessary historical records
- To lower storage costs
Beginning with ArcGIS Pro 3.5, you can manage and optimize the storage of branch-versioned datasets using the Prune Branch History geoprocessing tool. The Prune Branch History tool offers more granular control, allowing you to determine which specific records to keep based on established criteria—such as setting the Prune Before Date.
How the Prune Branch History tool works
The Prune Branch History tool is designed to manage historical data effectively. The following are its main functionalities:
- Historical data deletion—This tool allows users to delete historical data from classes based on a specified date. Any retired data older than this date will be removed from the history. A retired row is defined as a row in the archive for which a newer representation exists, or the last representation is of the feature being deleted. This means that the row is no longer the most current version of the data and has been superseded by a more recent update or marked for deletion. This is particularly useful for managing the size of the database by eliminating outdated and unnecessary information.
- Retention of current active rows—One of the key features of the Prune Branch History tool is that it ensures no active rows are deleted. An active row is defined as the latest representation of a feature that has not been deleted. This row represents the current state of the data and is not marked as deleted. If a feature was present before the specified date and is still active, it will be preserved. The tool focuses on removing only the historical data that is no longer relevant.
- Referenced data protection—The tool avoids pruning any data that is still being referenced by active versions. If a version points to a moment that includes older data, that data will not be pruned until it is no longer referenced.
- Reconcile—For versions that have been around for a long time, it may be necessary to reconcile to ensure the data can be pruned. This is especially relevant when the tool is used to manage data that has been in the system for an extended period. If the common ancestor and previous ancestor are both before the prune moment, you must reconcile the version twice.
- Customizable history retention—Organizations can determine how much historical data to retain. For instance, they may choose to keep history for the past two or five years, pruning anything beyond that. This adaptability allows for a balance between retaining valuable historical data and managing the overall database size.
The Prune Branch History tool is similar to the Trim Archive History tool, which is supported on nonversioned archived datasets. However, the Prune Branch History tool is created explicitly for datasets registered as branch versioned. The Prune Branch History tool allows you to generate a report with the Report Only parameter, which provides the total count of eligible archive records without actually pruning any records. Additionally, you can choose Only Prune System Tables. When this option is checked, only the eligible internal system tables of the controller datasets will be pruned or logged.
Key concepts and considerations for pruning branch history
Understanding some concepts related to branch history and the Prune Branch History tool is important. These concepts are discussed further in the following sections and include the following:
Prune Before Date
Prune Before Date is a user-defined date/time parameter marking the cutoff for data consideration in pruning. When setting Prune Before Date, all records prior to this moment are candidates to be removed by the prune operation, provided it does not conflict with any referenced moments.
Before using the Prune Branch History tool, it's important to have a clear purpose in mind and to choose an appropriate prune before date reflecting your specific needs, such as a legal requirement.
For example, if Prune Before Date is set to January 1, 2022, all retired data older than this point would be subject to pruning.
Referenced moments
A referenced moment is a point in time that prevents certain records from being pruned. These moments are important for maintaining data integrity and ensuring that necessary historical records are not deleted.
The Prune Branch History tool examines historical records of features in the database. If the tool reports a referenced moment, it means a version or feature service replica uses a referenced moment before the requested prune date. This referenced moment can prevent records from being pruned on the dataset. The output log will report the earliest moment that can be used including the referenced moment, feature service replica, and version that blocked the tool.
To resolve this, you can adjust Prune Before Date to an older time, reconcile the versions, or synchronize the feature service replicas. This step ensures that all necessary records are retained and avoids referenced moments.
For example, a new parcel was added a year ago to a parcel dataset registered as branch versioned. Then, the parcel was updated six months ago and updated again today. If you set Prune Before Date to be three months ago, the tool will identify which rows are candidates for pruning based on their update times. Any representation of the parcel that is older than the Prune Before Date value and is not the current representation of the parcel dataset can be removed.
When a feature is updated, the tool ensures that the current representation of the feature is not returned in queries. If the current representation is a delete, the row should be pruned, as there is no returnable current representation as of the prune time.
For example, if a parcel was deleted six months ago, its current representation is marked as deleted. This row becomes a candidate for pruning because there is no returnable current representation.
Named versions and reconciling
When a named version is created, the date and time of this moment are recorded and serve as a common ancestor for reconciling. During a reconcile, the tool must go back to the initial time to determine if changes were made in default or the named version. This process involves recording the initial and new times and updating the common ancestor.
Note:
The Prune Branch History tool only prunes retired archived records from the default version.
For example, if you have a named version created six months ago. During a reconcile, the system compares the current state of the default branch and the named version to determine if changes have occurred in either. This helps ensure that all changes are accurately reflected and avoids referenced moments.
Feature service replicas
Feature service replicas also hold referenced moments and move forward in time as they are synchronized. The tool ensures that rows needed for synchronization are not pruned. This includes maintaining the historical records required for conflict detection.
For example, if a feature service replica was created a year ago and has been synchronized multiple times, the tool ensures that rows needed for these synchronizations are not pruned. This helps maintain the integrity of the data across different replicas.
Transaction model
The Prune Branch History tool requires an exclusive lock on the dataset and will remove all candidate rows that are dated prior to the specified Prune Before Date. If the tool encounters an error during the pruning operation, you will need to resolve the error before rerunning the tool. This workflow ensures that the database remains consistent and that there are no gaps in the historical records.
When pruning a feature dataset or system tables, each input class or table will be committed as the operation is performed on each individual object. For example, if the tool encounters a memory issue while pruning, the process will stop. You can then address and resolve the issue and then re-run the tool, which will resume pruning from where it left off.
Depending on the volume of candidate rows that are being pruned, it may be necessary to increase database resources, such as disk space, to effectively support the size of the transaction.
Common ancestor and previous ancestor moment
The common ancestor and previous ancestor version properties are important for managing branch versioned data, tracking the history of changes, avoiding referenced moments, and ensuring the correct version of a feature is retrieved during queries. These version properties can be viewed when you open the Versions view for a web feature layer in the active map from the Contents pane. The information presented in these columns can also help you resolve issues related to reference moments that prevent pruning when using the Prune Branch History tool.
- Common Ancestor—The common ancestor marks the last moment two branches share before they diverge, marking the date and time when the version referenced the same moment as default.
- Previous Ancestor—The previous ancestor shows the previous date and time moment before the last reconciliation when the version and the default version referenced the same moment. It becomes the previous common ancestor after a new reconciliation is completed.
During a reconcile, if conflicts are detected, the common ancestor and the previous ancestor moments help determine if changes were made to the same feature in both the version and the default version.
When using the Prune Branch History tool, the common ancestor and the previous ancestor moments can prevent certain records from being pruned if a version or a feature service replica references them. This ensures that important historical data is not inadvertently removed. If the Prune Branch History tool returns an error indicating that the Prune Before Date is invalid due to a referenced moment, check the common ancestor and previous common ancestor moments in the version manager. Identifying these moments in the version manager can help you understand why certain records can't be pruned, allowing you to take action like reconciling versions or synchronizing feature service replicas to update and move the referenced moment forward.
Learn more about creating, viewing, and managing feature service replicas.
History preservation
Use the following recommendations to preserve historical data or archived rows before running the Prune Branch History tool.
- Regularly back up your enterprise geodatabase.
Tip:
Regularly testing your database backup and recovery plan is also a good practice. Consult the documentation for your RDBMS for specific details and steps regarding database backup and recovery plan options.
- Use the Report Only option in the Prune Branch History tool to identify potential issues before pruning.
- Before pruning, store the exported historical records in an external database or file for future reference.
Exporting historical records
To maintain historical records before pruning, you can export the archived class rows using a prior moment. The workflow to export historical records involves the following:
- Add the archive class to a map.
- Use the GDB_FROM_DATE field to sort and identify records older than the prune moment.
- Select and export all the records older than the Prune Before Date.
See Prune Branch History to learn more about the prerequisites and workflow for using the Prune Branch History tool.