[ntuple] Add VersionBehavior to merger options

Author: silverweed

tree/ntuple/inc/ROOT/RNTupleMerger.hxx

@@ -62,6 +62,16 @@ enum class ENTupleMergeErrBehavior {
    kSkip
 };
 
+enum class ENTupleMergeVersionBehavior {
+   /// The merger will emit a warning when merging RNTuples with higher version than the latest supported by this
+   /// ROOT version, but merging will work. Some optional features present in the source(s) may be missing from the
+   /// merged RNTuple.
+   kWarnOnHigherVersion,
+   /// The merger will refuse to merge RNTuples with higher versions than the latest supported by this ROOT version.
+   /// The merging process will abort as soon as one such source is encountered.
+   kAbortOnHigherVersion
+};
+
 struct RColumnMergeInfo;
 struct RNTupleMergeData;
 struct RSealedPageMergeData;
@@ -71,6 +81,7 @@ struct RSealedPageMergeData;
 /// Here is the mapping for the TFileMerger options:
 ///   - "rntuple.MergingMode=(Filter|Union|...)" -> sets fMergingMode
 ///   - "rntuple.ErrBehavior=(Abort|Skip|...)"   -> sets fErrBehavior
+///   - "rntuple.VersionBehavior=(WarnOnHigherVersion|AbortOnHigherVersion|...)" -> sets fVersionBehavior
 ///   - "rntuple.ExtraVerbose"                   -> sets fExtraVerbose to true
 /// Rules about the string-based options:
 ///   1. there must be no space between the separators (i.e. `.` and `=`)
@@ -84,6 +95,8 @@ struct RNTupleMergeOptions {
    ENTupleMergingMode fMergingMode = ENTupleMergingMode::kFilter;
    /// Determines how the Merge function behaves upon merging errors
    ENTupleMergeErrBehavior fErrBehavior = ENTupleMergeErrBehavior::kAbort;
+   /// Determines how the Merge function behaves depending on the RNTuple sources' version.
+   ENTupleMergeVersionBehavior fVersionBehavior = ENTupleMergeVersionBehavior::kWarnOnHigherVersion;
    /// If true, the merger will emit further diagnostics and information.
    bool fExtraVerbose = false;
 };

tree/ntuple/src/RNTupleMerger.cxx

@@ -106,6 +106,16 @@ static std::optional<ENTupleMergeErrBehavior> ParseOptionErrBehavior(const TStri
                                                         {"Skip", ENTupleMergeErrBehavior::kSkip},
                                                      });
 }
+
+static std::optional<ENTupleMergeVersionBehavior> ParseOptionVersionBehavior(const TString &opts)
+{
+   return ParseStringOption<ENTupleMergeVersionBehavior>(
+      opts, "rntuple.VersionBehavior=",
+      {
+         {"WarnOnHigherVersion", ENTupleMergeVersionBehavior::kWarnOnHigherVersion},
+         {"AbortOnHigherVersion", ENTupleMergeVersionBehavior::kAbortOnHigherVersion},
+      });
+}
 // -------------------------------------------------------------------------------------
 
 // Entry point for TFileMerger. Internally calls RNTupleMerger::Merge().
@@ -244,6 +254,9 @@ try {
    if (auto errBehavior = ParseOptionErrBehavior(mergeInfo->fOptions)) {
       mergerOpts.fErrBehavior = *errBehavior;
    }
+   if (auto versionBehavior = ParseOptionVersionBehavior(mergeInfo->fOptions)) {
+      mergerOpts.fVersionBehavior = *versionBehavior;
+   }
    merger.Merge(sourcePtrs, mergerOpts).ThrowOnError();
 
    // Provide the caller with a merged anchor object (even though we've already
@@ -1241,9 +1254,16 @@ ROOT::RResult<void> RNTupleMerger::Merge(std::span<RPageSource *> sources, const
       mergeData.fSrcDescriptor = &srcDescriptor.GetRef();
 
       if (mergeData.fSrcDescriptor->GetVersion() > ROOT::RNTuple::GetCurrentVersion()) {
-         R__LOG_WARNING(NTupleMergeLog()) << "RNTuple '" << mergeData.fSrcDescriptor->GetName()
-                                          << "' has a higher format version than the latest supported by this version "
-                                             "of ROOT. Merging will work but some features may be dropped.";
+         if (mergeOpts.fVersionBehavior == ENTupleMergeVersionBehavior::kWarnOnHigherVersion) {
+            R__LOG_WARNING(NTupleMergeLog())
+               << "RNTuple '" << mergeData.fSrcDescriptor->GetName()
+               << "' has a higher format version than the latest supported by this version "
+                  "of ROOT. Merging will work but some features may be dropped.";
+         } else {
+            return R__FAIL("RNTuple '" + mergeData.fSrcDescriptor->GetName() +
+                           "' has a higher format version than the latest supported by this version. Refusing to "
+                           "merge, since RNTupleMergeOptions::fVersionBehavior is set to AbortOnHigherVersion.");
+         }
       }
 
       // Create sink from the input model if not initialized

tree/ntuple/test/ntuple_merger.cxx

@@ -3892,5 +3892,14 @@ TEST(RNTupleMerger, MergeNewerVersion)
          auto res = merger.Merge(sourcePtrs, opts);
          EXPECT_TRUE(bool(res));
       }
+
+      // Now merge again but with VersionBehavior set to Abort.
+      {
+         RNTupleMergeOptions opts;
+         opts.fVersionBehavior = ROOT::Experimental::Internal::ENTupleMergeVersionBehavior::kAbortOnHigherVersion;
+         auto res = merger.Merge(sourcePtrs, opts);
+         EXPECT_FALSE(bool(res));
+         EXPECT_THAT(res.GetError()->GetReport(), testing::HasSubstr("has a higher format version"));
+      }
    }
 }