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.
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.
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.
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
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.
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.