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.
SyntaxCREATE 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 an Arctic catalog is not specified, the tag is created in the catalog specified in the query context.
AT { REF[ERENCE] | BRANCH | TAG | COMMIT } <refValue>
String
Optional
Specifies the reference where you want the new tag to be created from. When this parameter is omitted, the current reference is used.
REF
: Identifies a specific branch, tag, or commit.BRANCH
: Identifies a specific branch.TAG
: Identifies a specific tag.COMMIT
: Identifies a specific commit. Commit hashes must be enclosed in double quotes (for example,“ff2fe50fef5a030c4fc8e61b252bdc33c72e2b6f929d813833d998b8368302e2”
.
IN <catalog_name>
String
Optional
The name of the Arctic catalog that you want to create a tag in. If not specified, the current Arctic catalog in the query context is used.
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 to.
ASSIGN { REF[ERENCE] | BRANCH | TAG | COMMIT } <identifier>
String
Specifies a reference to assign a tag from.
REF
: Identifies a reference, which can be a branch, another tag, or a commit.BRANCH
: Identifies a branch reference where the specified tag is assigned to.TAG
: Identifies a tag reference where the specified tag is assigned to.COMMIT
: Identifies a commit reference where the specified tag is assigned to. Commit hashes must be enclosed in double quotes (for example,“ff2fe50fef5a030c4fc8e61b252bdc33c72e2b6f929d813833d998b8368302e2”
.)
IN <catalog_name>
String
Optional
The name of the Arctic catalog that you want to assign a tag. If not specified, the current Arctic catalog in the query context is used.
Showing Tags
SyntaxSHOW TAGS
[ IN <nessie_name> ]
Parameters
IN <catalog_name>
String
Optional
The name of the Arctic catalog where you want to view all tags. If a catalog is not specified, the one in the query context is used.
Dropping a Tag
SyntaxDROP TAG [IF EXISTS] <tag_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 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_hash> | FORCE
String
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. Commit hashes must be enclosed in double quotes (for example, “ff2fe50fef5a030c4fc8e61b252bdc33c72e2b6f929d813833d998b8368302e2”
).
Use the FORCE
parameter when you want to drop the tag even if it has been changed.
IN <catalog_name>
String
Optional
The name of the Arctic catalog containing the tag that you want to drop. If not specified, the current Arctic catalog in the query context is used.