Prune like a pro: Introduction to the Prune Branch History tool

Many of Esri’s product enhancement ideas come from your suggestions on the Esri Community site. In the Data Management Ideas section, you’ll find numerous requests for the ability to trim the history of branch versioned datasets, including the following idea:

Trim Archive History Tool for Branch Versioned Data

With more than 60 kudos given to this idea on Esri Community and a similar enhancement logged through Esri Support Services, we are pleased to announce that the Prune Branch History geoprocessing tool is available with the ArcGIS Pro 3.5 release.

Function of the Prune Branch History tool

The Prune Branch History geoprocessing tool was designed to help you manage and clean up the historical records of branch versioned datasets. This means you can delete or prune retired archive records from branch-versioned datasets that are no longer needed. The tool identifies which records can be safely pruned based on specific criteria, ensuring that only appropriate entries are deleted while preserving the necessary historical data.

Branch versioned data uses a temporal-based archiving model—while editor tracking must be configured as a prerequisite step, archiving is enabled automatically during registering as versioned.

A complete historical record of all modifications for branch versioned data is kept. Each modification—whether it’s inserting, updating, or deleting—is logged as a new entry in the business table. Six system fields are added to the business table to store and manage all edits made to the branch versioned feature class or table.

This detailed recording allows you to access the history of a branch versioned dataset by viewing a historical moment or even work with the archive class in ArcGIS Pro. The tracking of changes for branch versioned data is referred to as the branch history for the dataset.

When to use the tool

When you no longer need the entire branch history for your data or want to do a scheduled cleanup, the Prune Branch History tool can be used to help manage the growth of historical data and reduce the overall storage size for branch versioned datasets.

Prune Branch History tool parameters

Let’s take a closer look at how to use the Prune Branch History tool with branch versioned data by reviewing the tool parameters.

Input Dataset (required)—The source for the Input Dataset parameter for the tool can be a feature class, feature dataset, or table. This must be branch versioned data from a branch database connection created as the owner of the input dataset. When your data resides in a feature dataset, you must input the feature dataset, as all classes in a feature dataset and related data will be processed together.

Output Log File (required)—Reports the feature classes and tables that were/will be pruned. Will also list the replicas and versions that prevented performing the prune with the requested date in the Prune Before Date parameter.

Optional parameters

The following optional parameters can give you more control over how and what gets pruned. 

• Report Only (check box)—When the Report Only check box is checked, the tool doesn’t delete any data and doesn’t require an exclusive lock. Instead, it scans your dataset and generates an output log file report showing how many records are eligible for pruning. This gives you a preview of the data that would be pruned if you reran the tool without this option being checked. Any versions or feature service replicas that would block the pruning operation will also be reported. The Report Only option is checked by default. Use this option to preview the output log file to see how much data will be affected, identify potential issues, and for planning ahead.

• • If the Report Only check box is checked, the records will not be pruned. Instead, only the total count of eligible records will be reported in the Output Log File.

• • The eligible archive records will be pruned if the Report Only check box is unchecked.

• • Only Prune System Tables (check box)—When you check this box, the tool narrows the scope of the pruning operation by focusing only on the internal system tables of the controller datasets. This specifically includes the tables that manage network topology in utility networks, such as connectivity and containment associations. This option is turned off by default, so the tool will prune all eligible tables, including both business and system tables.

• Prune Before Date—The Prune Before Date field allows you to define a specific cutoff point. Any retired records older than this date become candidates for pruning—unless a version or feature service replica is still referencing them.  When setting the date for the Prune Before Date parameter, ensure the date is in UTC (coordinated universal time) to maintain a consistent reference.

• • If the Prune Before Date field is left empty, the tool will prune as much of the eligible archive history as possible based on the oldest referenced moment.

• • If the Prune Before Date field contains a specified date, only archived data up to that moment will be removed. For example, if you want to remove data older than three years, you would calculate the date three years prior to the current date and use that as the date in the Prune Before Date field.

When you run the tool, it will check whether the selected date in the Prune Before Date field is valid. If there are reference moments (such as versions or feature service replicas) that prevent pruning, the tool will return an error indicating the earliest possible prune date.

Retention of current active rows

The tool only prunes retired archived records from the default version. Any records still active or referenced by a version or feature service replica are not eligible for pruning. Once records are pruned, they are permanently deleted. Historical queries at the specified moments can no longer be conducted since the data is no longer available.

Export historical records

If you decide to use the Prune Branch History tool to remove historical records from branch versioned datasets, you can preserve the existing archived rows by exporting them before the pruning process.

To export historical records, complete the following steps:

1. Add the archive class to a map.
2. In the Contents pane, right-click the archive class layer and click Attribute Table or click Open for a stand-alone table.
3. In the table view, find the GDB_FROM_DATE field to sort and select the records that meet the criteria for preservation and are older than the date in the Prune Before Date field.
4. Export these records into a format on an external database or file for future reference or to be queried later if necessary.

Best practices

Follow these best practices to help optimize and ensure a smooth experience using this tool so that you can maintain an efficient and well-organized geodatabase:

• Back up your data—Always complete a full database backup before running the tool.
• Run regular maintenance—Reconcile versions with default. Delete versions that have been posted and no longer needed after editing workflows to prevent having older referenced moments and increase the candidate rows that can be pruned.
• Identify data for pruning—Choose an appropriate date for the Prune Before Date parameter.
• Conduct a test run—Use the Report Only option first to preview what will be pruned and identify potential issues.
• Review log files—Monitor results and confirm successful pruning.
• Preserve historical data—Export historical records to an external storage location before pruning.

After running the tool, check the Archive History parameter under the Source tab of your dataset properties to see the most recent date the tool was used to prune retired rows from this dataset.

Conclusion

As your datasets grow, so does the need for smart data management. Whether you’re managing large datasets or doing routine maintenance, the Prune Branch History tool is a powerful addition to your data management toolkit. It gives you more control over your data so that you can stay ahead by removing what is no longer needed while preserving what matters.

The creation of this tool is a direct result of your feedback, and we’re excited to see how it helps you streamline your workflows. Try it in ArcGIS Pro 3.5, and don’t hesitate to explore the documentation or reach out to Esri Community if you have questions.

Start pruning like a pro today and keep your geodatabase ready for what’s next!

Resources

Review the following sections from the Branch history and Prune branch history topics:

• How the Prune Branch History tool works
• Prerequisites for using the Prune Branch History tool
• Use the Prune Branch History tool – workflow steps
• Error handling during pruning