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

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

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

    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

    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.