Dremio Cloud
Dremio Software
 
On this page

    Nessie Branches preview

    A branch is a named reference to a commit. A new commit to a branch updates the branch to the new commit. Nessie uses the concept of branches to always reference the latest version in a chain of commits. To learn about how branches work in Nessie, see Branches on the Project Nessie website.

    The SQL commands for branches enable you to perform the Git-like operation of forking (or creating a new branch based on) the the current commit. Nessie SQL commands are structured to be consistent with the SQL commands used for other catalog objects and consistent with database standards.

    note:

    If you are using these SQL commands in engines other than Dremio Sonar, the SQL syntax may differ:

    Creating a Branch

    When you create a branch, you are forking the branch you are currently in. To add a reference point to a new branch, create a tag.

    Syntax
    CREATE BRANCH [ IF NOT EXISTS ] <branch_name> 
   [ AT ( REF[ERENCE] | BRANCH | TAG | COMMIT ) <refValue> ] 
   [ IN <nessie_name> ]

    Parameters

    IF NOT EXISTS

    Optional

    If you include this optional clause, the command will run regardless of whether the branch exists and you will receive a summary indicating whether the branch could be created. If this clause is not specified, the command will fail if the branch to be created already exists.

    <branch_name>

    String

    The name of the branch that you are creating. If a Nessie repository is not specified, the branch is created in the current Nessie repository.

    AT ( REF[ERENCE] | BRANCH | TAG | COMMIT ) <refValue>

    String

    Optional

    You can use this parameter to specify a reference point where you want the new branch to be created from. You can use one of the following as a reference point:

    • REF[ERENCE]: Identifies the branch, tag, or commit that you want to create a new branch from.
    • BRANCH: Creates a new branch based on another existing branch.
    • TAG: Creates a new branch based from an existing tag.
    • COMMIT: Creates a new branch based on an existing commit.
    .

    IN <nessie_name>

    String

    Optional

    The name of the Nessie repository where you want to create a branch. If not specified, we default to the current Nessie repository.

    Merging a Branch

    The MERGE command enables you to merge a (source) branch into the current branch that you are in by default, or into a target branch that you specify.

    Syntax
    MERGE BRANCH <source_branch_name> 
  [ INTO <target_branch_name> ] 
  [ IN <nessie_name> ]

    Parameters

    <source_branch_name>

    String

    The name of the branch that you want to merge into your target branch. If a target branch is not specified, the source branch is merged into the current branch you are in.

    INTO <target_branch_name>

    String

    Optional

    The name of the branch that is the target for the merge. If you do not use this optional clause and the reference point is a branch, the query will still run successfully. However, if the reference point is not a branch, the query will fail because you can only merge branches.

    IN <nessie_name>

    String

    Optional

    The name of the Nessie repository. If not specified, we default to the current Nessie repository.

    Assigning a Branch

    The ASSIGN command enables you to change the reference point that the branch head points to.

    Syntax
    ALTER BRANCH <branch_name> 
  ASSIGN ( REF[ERENCE] | BRANCH | TAG | COMMIT ) <identifier>
  [ IN <nessie_name> ]

    Parameters

    <branch_name>

    String

    The name of the branch that you are assigning a new reference point to.

    ASSIGN ( REF[ERENCE] | BRANCH | TAG | COMMIT ) <identifier>

    String

    You can use this parameter to specify a reference point to assign a branch from. You can use one of the following as a reference point:

    • REF[ERENCE]: Identifies a branch, tag, or commit that you want to change the reference point for the specified branch.
    • BRANCH: Identifies a branch reference point where the specified branch is assigned to.
    • TAG: Identifies a tag reference point where the specified branch is assigned to.
    • COMMIT: Identifies a commit reference point where the specified branch is assigned to.
    .

    IN <nessie_name>

    String

    Optional

    The name of the Nessie repository that you want to assign a new reference point to. If not specified, we default to the current Nessie repository.

    Showing Branches

    Syntax
    SHOW BRANCHES 
  [ IN <nessie_name> ]

    Parameters

    IN <nessie_name>

    String

    Optional

    The name of the Nessie repository that you want to view all branches for. If not specified, we default to the current Nessie repository.

    Dropping a Branch

    Branches in Nessie point to existing commits, meaning that these commits are considered referenced. When you drop a branch, you are removing the branch’s head reference. After a branch is dropped, the underlying commits remain as unreferenced commits.

    Syntax
    DROP BRANCH [IF EXISTS] <branch_name> 
  ( AT COMMIT <commit> | FORCE )
  [ IN <nessie_name> ]

    Parameters

    IF EXISTS

    Optional

    If you include this optional clause, the command will succeed regardless of whether the branch existed. If this clause is not specified, the command will fail if the branch to be dropped does not exist.

    <branch_name>

    String

    The name of the branch that you are dropping.

    AT COMMIT <commit> | FORCE

    String

    When dropping a branch, you must choose either the AT COMMIT 〈commit〉 parameter or the FORCE parameter.

    • Use the AT COMMIT parameter when you want to specify the exact commit hash that the branch is expected to be at. This is helpful to prevent the branch from being dropped if it was modified unexpectedly.
    • Use the FORCE parameter when you want to drop the branch even if it has been changed.

    IN <nessie_name>

    String

    Optional

    The name of the Nessie repository containing the branch that you want to drop. If not specified, we default to the current Nessie repository.