Dremio Cloud
Dremio Software
 
On this page

    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.

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

    Syntax
    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. 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 tag. If not specified, we default to the current Nessie repository.

    Showing Tags

    Syntax
    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

    Syntax
    DROP 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

    When dropping a tag, you must choose either the AT COMMIT 〈commit_hash〉 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. 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 <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.