Nessie Tags preview
A tag is another type of named references (like branches). Nessie tags are named references to specific commits. Tags always point to the same commit and does not change automatically. As a result, tags are useful to reference specific commits. For example, a tag named web-transactions-in-FY2021
could reference all web transactions completed in the specified year. To learn about how tags work in Nessie, see Tags on the Project Nessie website.
The SQL commands for tags enable you to create reference points for branches and commits. 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 Tag
When you create a tag, you are providing a tag reference for the current commit.
CREATE TAG [ IF NOT EXISTS ] <tag_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 tag exists and you will receive a summary indicating whether the tag could be created. If this clause is not specified, the command will fail if the tag to be created already exists.
<tag_name>
String
The name of the tag that you are creating. If a Nessie repository is not specified, the tag 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 tag 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 tag from.BRANCH
: Creates a new tag based on the specified branch.TAG
: Creates a new tag based on another tag.COMMIT
: Creates a new tag based on the specified commit.
IN <nessie_name>
String
Optional
The name of the Nessie repository that you want to create a tag in. If not specified, we default to the current Nessie repository.
Assigning a Tag
The ASSIGN
command enables you to change the reference point that the tag points to.
ALTER TAG <tag_name>
ASSIGN ( REF[ERENCE] | BRANCH | TAG | COMMIT ) <identifier>
[ IN <nessie_name> ]
Parameters
<tag_name>
String
The name of the tag 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 tag 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 tag.BRANCH
: Identifies a branch reference point where the specified tag is assigned to.TAG
: Identifies a tag reference point where the specified tag is assigned to.COMMIT
: Identifies a commit reference point where the specified tag is assigned to.
IN <nessie_name>
String
Optional
The name of the Nessie repository that you want to assign a tag. If not specified, we default to the current Nessie repository.
Showing Tags
SHOW TAGS
[ IN <nessie_name> ]
Parameters
IN <nessie_name>
String
Optional
The name of the Nessie repository where you want to view all tags. If not specified, we default to the current Nessie repository.
Dropping a Tag
DROP TAG [IF EXISTS] <tag_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 tag existed. If this clause is not specified, the command will fail if the tag to be dropped does not exist.
<tag_name>
String
The name of the tag that you are dropping.
AT COMMIT <commit> | FORCE
String
When dropping a tag, 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 tag is expected to be at. This is helpful to prevent the tag from being dropped if it was modified unexpectedly. - Use the
FORCE
parameter when you want to drop the tag even if it has been changed.
IN <nessie_name>
String
Optional
The name of the Nessie repository containing the tag that you want to drop. If not specified, we default to the current Nessie repository.