Dremio Cloud
Dremio Software
 
On this page

    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. Commit hashes must be enclosed in double quotes (for example, “ff2fe50fef5a030c4fc8e61b252bdc33c72e2b6f929d813833d998b8368302e2”).
    .

    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.

    Specifying a Branch to Use

    Each individual state in Nessie is defined by a Nessie commit. Each commit in Nessie has references to its predecessor (the previous versions of the data) except for the first (empty) commit. To learn more about how commits work in Nessie, see Working with data in Nessie.

    The USE SQL command enables you to change the commit reference for your current SQL session.

    Syntax
    USE ( REF[ERENCE] | BRANCH | TAG | COMMIT ) <refValue>
   [ IN <nessie_name> ]

    Parameters

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

    String

    Change the reference point for the current SQL session:

    • REF or REFERENCE: Identifies the branch, tag, or commit that you want to use as the new commit reference point.
    • BRANCH: Changes the commit reference point to the specified branch.
    • TAG: Changes the commit reference point to the specified tag.
    • COMMIT: Changes the commit reference point to the specified commit. Commit hashes must be enclosed in double quotes (for example, “ff2fe50fef5a030c4fc8e61b252bdc33c72e2b6f929d813833d998b8368302e2”).
    .

    IN <nessie_name>

    String

    Optional

    The name of the Nessie repository where you want to change the commit reference point. When this parameter is not used, the current Nessie repository is used.

    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. Commit hashes must be enclosed in double quotes (for example, “ff2fe50fef5a030c4fc8e61b252bdc33c72e2b6f929d813833d998b8368302e2”).
    .

    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_hash"> | 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_hash"> | 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. Commit hashes must be enclosed in double quotes (for example, “ff2fe50fef5a030c4fc8e61b252bdc33c72e2b6f929d813833d998b8368302e2”).
    • 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.