[core][rest] Add branch merge support for append-only tables

docs/layouts/shortcodes/generated/core_configuration.html

@@ -104,6 +104,12 @@
             <td>MemorySize</td>
             <td>Target size of a blob file. Default is value of TARGET_FILE_SIZE.</td>
         </tr>
+        <tr>
+            <td><h5>branch-merge.enabled</h5></td>
+            <td style="word-wrap: break-word;">false</td>
+            <td>Boolean</td>
+            <td>Whether to enable branch merge for this table. When enabled, the table must keep a pure-append history: compaction and INSERT OVERWRITE are rejected, and deletion vectors are not supported. This provides the invariant required by branch merge.</td>
+        </tr>
         <tr>
             <td><h5>bucket</h5></td>
             <td style="word-wrap: break-word;">-1</td>

docs/static/rest-catalog-open-api.yaml

@@ -1267,6 +1267,48 @@ paths:
           $ref: '#/components/responses/BranchNotExistErrorResponse'
         "500":
           $ref: '#/components/responses/ServerErrorResponse'
+  /v1/{prefix}/databases/{database}/tables/{table}/branches/merge:
+    post:
+      tags:
+        - branch
+      summary: Merge branch
+      description: >-
+        Merge data files from source branch into target branch.
+        The table must be created with 'branch-merge.enabled' = 'true'. This option
+        enforces a pure-append table history by rejecting compaction and INSERT OVERWRITE,
+        and it is incompatible with deletion vectors. Requires an append-only table with
+        consistent row-tracking settings and compatible schema history.
+      operationId: mergeBranch
+      parameters:
+        - name: prefix
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: database
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: table
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MergeBranchRequest'
+      responses:
+        "200":
+          description: Success, no content
+        "401":
+          $ref: '#/components/responses/UnauthorizedErrorResponse'
+        "404":
+          $ref: '#/components/responses/BranchNotExistErrorResponse'
+        "500":
+          $ref: '#/components/responses/ServerErrorResponse'
   /v1/{prefix}/databases/{database}/tables/{table}/tags:
     get:
       tags:
@@ -3304,6 +3346,16 @@ components:
       properties:
         branch:
           type: string
+    MergeBranchRequest:
+      type: object
+      required:
+        - sourceBranch
+        - targetBranch
+      properties:
+        sourceBranch:
+          type: string
+        targetBranch:
+          type: string
     ListBranchesResponse:
       type: object
       properties:
@@ -3615,4 +3667,4 @@ components:
   securitySchemes:
     BearerAuth:
       type: http
-      scheme: bearer
+      scheme: bearer

paimon-api/src/main/java/org/apache/paimon/CoreOptions.java

@@ -2215,6 +2215,17 @@ public InlineElement getDescription() {
                     .defaultValue(false)
                     .withDescription("Whether enable data evolution for row tracking table.");
 
+    @Immutable
+    public static final ConfigOption<Boolean> BRANCH_MERGE_ENABLED =
+            key("branch-merge.enabled")
+                    .booleanType()
+                    .defaultValue(false)
+                    .withDescription(
+                            "Whether to enable branch merge for this table. "
+                                    + "When enabled, the table must keep a pure-append history: "
+                                    + "compaction and INSERT OVERWRITE are rejected, and deletion vectors "
+                                    + "are not supported. This provides the invariant required by branch merge.");
+
     public static final ConfigOption<Boolean> SNAPSHOT_IGNORE_EMPTY_COMMIT =
             key("snapshot.ignore-empty-commit")
                     .booleanType()
@@ -3667,6 +3678,10 @@ public boolean dataEvolutionEnabled() {
         return options.get(DATA_EVOLUTION_ENABLED);
     }
 
+    public boolean branchMergeEnabled() {
+        return options.get(BRANCH_MERGE_ENABLED);
+    }
+
     public boolean prepareCommitWaitCompaction() {
         if (!needLookup()) {
             return false;

paimon-api/src/main/java/org/apache/paimon/rest/RESTApi.java

@@ -48,6 +48,7 @@
 import org.apache.paimon.rest.requests.ForwardBranchRequest;
 import org.apache.paimon.rest.requests.ListPartitionsByNamesRequest;
 import org.apache.paimon.rest.requests.MarkDonePartitionsRequest;
+import org.apache.paimon.rest.requests.MergeBranchRequest;
 import org.apache.paimon.rest.requests.RegisterTableRequest;
 import org.apache.paimon.rest.requests.RenameBranchRequest;
 import org.apache.paimon.rest.requests.RenameTableRequest;
@@ -1006,6 +1007,25 @@ public void fastForward(Identifier identifier, String branch) {
                 restAuthFunction);
     }
 
+    /**
+     * Merge branch for table.
+     *
+     * @param identifier database name and table name.
+     * @param sourceBranch source branch name
+     * @param targetBranch target branch name
+     * @throws NoSuchResourceException Exception thrown on HTTP 404 means the branch or table not
+     *     exists
+     * @throws ForbiddenException Exception thrown on HTTP 403 means don't have the permission for
+     *     this table
+     */
+    public void mergeBranch(Identifier identifier, String sourceBranch, String targetBranch) {
+        MergeBranchRequest request = new MergeBranchRequest(sourceBranch, targetBranch);
+        client.post(
+                resourcePaths.mergeBranch(identifier.getDatabaseName(), identifier.getObjectName()),
+                request,
+                restAuthFunction);
+    }
+
     /**
      * List branches for table.
      *

paimon-api/src/main/java/org/apache/paimon/rest/ResourcePaths.java

@@ -275,6 +275,18 @@ public String renameBranch(String databaseName, String tableName, String branch)
                 "rename");
     }
 
+    public String mergeBranch(String databaseName, String tableName) {
+        return SLASH.join(
+                V1,
+                prefix,
+                DATABASES,
+                encodeString(databaseName),
+                TABLES,
+                encodeString(tableName),
+                BRANCHES,
+                "merge");
+    }
+
     public String tags(String databaseName, String objectName) {
         return SLASH.join(
                 V1,

paimon-api/src/main/java/org/apache/paimon/rest/requests/MergeBranchRequest.java

@@ -0,0 +1,58 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.apache.paimon.rest.requests;
+
+import org.apache.paimon.rest.RESTRequest;
+
+import org.apache.paimon.shade.jackson2.com.fasterxml.jackson.annotation.JsonCreator;
+import org.apache.paimon.shade.jackson2.com.fasterxml.jackson.annotation.JsonGetter;
+import org.apache.paimon.shade.jackson2.com.fasterxml.jackson.annotation.JsonIgnoreProperties;
+import org.apache.paimon.shade.jackson2.com.fasterxml.jackson.annotation.JsonProperty;
+
+/** Request for merging branch. */
+@JsonIgnoreProperties(ignoreUnknown = true)
+public class MergeBranchRequest implements RESTRequest {
+
+    private static final String FIELD_SOURCE_BRANCH = "sourceBranch";
+    private static final String FIELD_TARGET_BRANCH = "targetBranch";
+
+    @JsonProperty(FIELD_SOURCE_BRANCH)
+    private final String sourceBranch;
+
+    @JsonProperty(FIELD_TARGET_BRANCH)
+    private final String targetBranch;
+
+    @JsonCreator
+    public MergeBranchRequest(
+            @JsonProperty(FIELD_SOURCE_BRANCH) String sourceBranch,
+            @JsonProperty(FIELD_TARGET_BRANCH) String targetBranch) {
+        this.sourceBranch = sourceBranch;
+        this.targetBranch = targetBranch;
+    }
+
+    @JsonGetter(FIELD_SOURCE_BRANCH)
+    public String sourceBranch() {
+        return sourceBranch;
+    }
+
+    @JsonGetter(FIELD_TARGET_BRANCH)
+    public String targetBranch() {
+        return targetBranch;
+    }
+}

paimon-core/src/main/java/org/apache/paimon/catalog/AbstractCatalog.java

@@ -541,6 +541,12 @@ public void fastForward(Identifier identifier, String branch) throws BranchNotEx
         throw new UnsupportedOperationException();
     }
 
+    @Override
+    public void mergeBranch(Identifier identifier, String sourceBranch, String targetBranch)
+            throws BranchNotExistException {
+        throw new UnsupportedOperationException();
+    }
+
     @Override
     public List<String> listBranches(Identifier identifier) throws TableNotExistException {
         throw new UnsupportedOperationException();

paimon-core/src/main/java/org/apache/paimon/catalog/Catalog.java

@@ -901,6 +901,19 @@ void renameBranch(Identifier identifier, String fromBranch, String toBranch)
      */
     void fastForward(Identifier identifier, String branch) throws BranchNotExistException;
 
+    /**
+     * Merge source branch into target branch.
+     *
+     * @param identifier path of the table, cannot be system or branch name.
+     * @param sourceBranch the source branch name
+     * @param targetBranch the target branch name
+     * @throws BranchNotExistException if the source or target branch doesn't exist
+     * @throws UnsupportedOperationException if the catalog does not {@link
+     *     #supportsVersionManagement()}
+     */
+    void mergeBranch(Identifier identifier, String sourceBranch, String targetBranch)
+            throws BranchNotExistException;
+
     /**
      * List all branches of the table.
      *

paimon-core/src/main/java/org/apache/paimon/catalog/DelegateCatalog.java

@@ -257,6 +257,12 @@ public void fastForward(Identifier identifier, String branch) throws BranchNotEx
         wrapped.fastForward(identifier, branch);
     }
 
+    @Override
+    public void mergeBranch(Identifier identifier, String sourceBranch, String targetBranch)
+            throws BranchNotExistException {
+        wrapped.mergeBranch(identifier, sourceBranch, targetBranch);
+    }
+
     @Override
     public List<String> listBranches(Identifier identifier) throws TableNotExistException {
         return wrapped.listBranches(identifier);

paimon-core/src/main/java/org/apache/paimon/io/DataFileMeta.java

@@ -329,6 +329,8 @@ default Range nonNullRowIdRange() {
 
     DataFileMeta assignFirstRowId(long firstRowId);
 
+    DataFileMeta newFirstRowId(@Nullable Long newFirstRowId);
+
     default List<Path> collectFiles(DataFilePathFactory pathFactory) {
         List<Path> paths = new ArrayList<>();
         paths.add(pathFactory.toPath(this));

paimon-core/src/main/java/org/apache/paimon/io/PojoDataFileMeta.java

@@ -379,6 +379,31 @@ public PojoDataFileMeta assignFirstRowId(long firstRowId) {
                 writeCols);
     }
 
+    @Override
+    public PojoDataFileMeta newFirstRowId(@Nullable Long newFirstRowId) {
+        return new PojoDataFileMeta(
+                fileName,
+                fileSize,
+                rowCount,
+                minKey,
+                maxKey,
+                keyStats,
+                valueStats,
+                minSequenceNumber,
+                maxSequenceNumber,
+                schemaId,
+                level,
+                extraFiles,
+                creationTime,
+                deleteRowCount,
+                embeddedIndex,
+                fileSource,
+                valueStatsCols,
+                externalPath,
+                newFirstRowId,
+                writeCols);
+    }
+
     @Override
     public PojoDataFileMeta copy(List<String> newExtraFiles) {
         return new PojoDataFileMeta(

paimon-core/src/main/java/org/apache/paimon/operation/FileStoreCommitImpl.java

@@ -297,6 +297,9 @@ public int commit(ManifestCommittable committable, boolean checkAppendFiles) {
         int attempts = 0;
 
         ManifestEntryChanges changes = collectChanges(committable.fileCommittables());
+        if (options.branchMergeEnabled()) {
+            validatePureAppendCommit(changes);
+        }
         try {
             List<SimpleFileEntry> appendSimpleEntries =
                     SimpleFileEntry.from(changes.appendTableFiles);
@@ -427,6 +430,13 @@ public int overwritePartition(
                     properties);
         }
 
+        if (options.branchMergeEnabled()) {
+            throw new UnsupportedOperationException(
+                    String.format(
+                            "INSERT OVERWRITE is not allowed when %s is true.",
+                            CoreOptions.BRANCH_MERGE_ENABLED.key()));
+        }
+
         long started = System.nanoTime();
         int generatedSnapshot = 0;
         int attempts = 0;
@@ -685,6 +695,15 @@ private ManifestEntryChanges collectChanges(List<CommitMessage> commitMessages)
         return changes;
     }
 
+    private void validatePureAppendCommit(ManifestEntryChanges changes) {
+        checkArgument(
+                changes.compactTableFiles.isEmpty()
+                        && changes.compactChangelog.isEmpty()
+                        && changes.compactIndexFiles.isEmpty(),
+                "Compaction is not allowed when %s is true.",
+                CoreOptions.BRANCH_MERGE_ENABLED.key());
+    }
+
     private int tryCommit(
             CommitChangesProvider changesProvider,
             long identifier,

paimon-core/src/main/java/org/apache/paimon/privilege/PrivilegedFileStoreTable.java

@@ -204,6 +204,12 @@ public void fastForward(String branchName) {
         wrapped.fastForward(branchName);
     }
 
+    @Override
+    public void mergeBranch(String sourceBranch, String targetBranch) {
+        privilegeChecker.assertCanInsert(identifier);
+        wrapped.mergeBranch(sourceBranch, targetBranch);
+    }
+
     @Override
     public ExpireSnapshots newExpireSnapshots() {
         privilegeChecker.assertCanInsert(identifier);

paimon-core/src/main/java/org/apache/paimon/rest/RESTCatalog.java

@@ -761,6 +761,18 @@ public void fastForward(Identifier identifier, String branch) throws BranchNotEx
         }
     }
 
+    @Override
+    public void mergeBranch(Identifier identifier, String sourceBranch, String targetBranch)
+            throws BranchNotExistException {
+        try {
+            api.mergeBranch(identifier, sourceBranch, targetBranch);
+        } catch (NoSuchResourceException e) {
+            throw new BranchNotExistException(identifier, e.resourceName(), e);
+        } catch (ForbiddenException e) {
+            throw new TableNoPermissionException(identifier, e);
+        }
+    }
+
     @Override
     public List<String> listBranches(Identifier identifier) throws TableNotExistException {
         try {