Managing Labels

The Product provides the Hammerspace toolkit, hstk, open-source utility to help manage data on shares. The utility is available on GitHub: https://github.com/hammer-space/hstk. This section explains how to set up labels for use with the hstk utility.

In addition to file-system metadata, the Product supports custom metadata, such as labels. Labels are schema-driven tags with an optional hierarchical layout. Labels can be used to easily tag data in a pre-configured, organized manner with constrained vocabularies, thereby avoiding scenarios in which words are entered with slight misspellings.

Labels can be set on a directory (including share-root) and files. When labels are applied to directories, they automatically inherit further down the directory tree.

Example of label hierarchy

Tree
Oak
Coast live oak
Black oak
Shrub oak
Fir
- …

Creating Labels

Labels are managed using the Admin CLI or with REST API calls.

To create a label, use the label-create CLI command.

Create a label.

label-create --name <label>

You can create a label hierarchy using the --implied-labels option.

Create a label hierarchy.

label-create --name <label> --implied-labels <parent label>

A label can be associated with multiple parent labels in the hierarchy.

Associate label with parent labels.

label-create --name <label> --implied-labels <parent1, parent2 ...>

To create the hierarchy from the example above, use the following command sequence:

Admin CLI Command	Output
label-create --name Tree	Tree
label-create --name Oak --implied-labels Tree	Tree Oak
label-create --name Oak --implied-labels "Coast live oak" label-create --name Oak --implied-labels "Black oak" label-create --name Oak --implied-labels "Shrub oak"	Tree Oak Coast live oak Black oak Shrub oak

Admin CLI Command

Output

label-create --name Tree

Tree

label-create --name Oak --implied-labels Tree

Tree

label-create --name Oak --implied-labels "Coast live oak"

label-create --name Oak --implied-labels "Black oak"

label-create --name Oak --implied-labels "Shrub oak"

Tree

Oak
- Coast live oak
- Black oak
- Shrub oak

Listing Labels

Configured labels in the system can be listed using label-list.

Admin CLI

Command:

label-list

Expected output:

total 5
Name:                    Black oak
Implied labels:          [Oak]
Internal ID:             4

Name:                    Coast live oak
Implied labels:          [Oak]
Internal ID:             3

Name:                    Oak
Implied labels:          [Tree]
Internal ID:             2

Name:                    Shrub Oak
Implied labels:          [Oak]
Internal ID:             5

Name:                    Tree
Internal ID:             1

Renaming Labels

Labels can be renamed using label-update.

Admin CLI

label-update --name <current name> --new-name <new name>

Note that renaming a label does not change the relationship with any other labels. Any other label with the update label in the implied-labels list will now reference the new name automatically.

Changing the Label Hierarchy

The implied labels can be updated.

Admin CLI

Command:

label-update --name <label> --implied-labels <list of comma separated labels>

The implied labels list replaces the existing list. To retain existing implied labels, ensure that they are included in the updated list.

Using the example above, insert a "Large Oaks" and "Small Oaks" label and move existing labels into one of the two choices.

Admin CLI: Inserting implied labels

Command:

label-create --name "Large Oaks" --implied-labels Oak

label-create --name "Small Oaks" --implied-labels Oak

Then verify the labels with label-list:

Command:

label-list

Expected output:

total 7
Name:                    Black oak
Implied labels:          [Oak]
Internal ID:             4

Name:                    Coast live oak
Implied labels:          [Oak]
Internal ID:             3

Name:                    Large Oaks
Implied labels:          [Oak]
Internal ID:             6

Name:                    Oak
Implied labels:          [Tree]
Internal ID:             2

Name:                    Shrub Oak
Implied labels:          [Oak]
Internal ID:             5

Name:                    Small Oaks
Implied labels:          [Oak]
Internal ID:             7

Name:                    Tree
Internal ID:             1

Move Coast Live Oak and Black Oak to Large Oaks

Command:

label-update --name "Coast live oak" --implied-labels "Large Oaks"

label-update --name "Black oak" --implied-labels "Large Oaks"

Move Shrub Oak to Small Oaks

Command:

label-update --name "Shrub Oak" --implied-labels "Small Oaks"

List the Labels After the Change

Command:

label-list

Expected output:

total 7
Name:                    Black oak
Implied labels:          [Large Oaks]
Internal ID:             4

Name:                    Coast live oak
Implied labels:          [Large Oaks]
Internal ID:             3

Name:                    Large Oaks
Implied labels:          [Oak]
Internal ID:             6

Name:                    Oak
Implied labels:          [Tree]
Internal ID:             2

Name:                    Shrub Oak
Implied labels:          [Small Oaks]
Internal ID:             5

Name:                    Small Oaks
Implied labels:          [Oak]
Internal ID:             7

Name:                    Tree
Internal ID:             1

Removing Labels

When a label is no longer needed, it can be removed using the label-delete command.

Admin CLI

label-delete --name <label>

If you delete a label, its reference will be removed from any other labels that includes it as an implied label. label-delete will not delete any other labels.

Deleting labels should be done with care as labels can also be used in objectives to determine file placement and behavior. Removing labels does not update or change any Objectives in the system.

Using the Hs Command with Labels

With labels created in the system, the Hammerspace toolkit (hstk) can be used to assign labels to files and directories as metadata. This type of metadata only lives within the file system itself and does not change the contents of the file. The metadata is also replicated when used together with the Global File System feature.

For a detailed understanding of all the capabilities of the hs command, please see the hs help pages. The hs command can be used from Linux or Windows, over both NFS and SMB protocols.

Adding a Label to a File Using the Hs Command

hstk on a client

hs label add <label name> <file and/or directory>

Listing All Files and Their Paths with a Particular Label

List all the files containing the "Black oak" label and print the PATH within the share.

hstk on a client

Command:

hs eval -e 'HAS_LABEL("Black oak")?PATH' . --recursive

Expected output:

"./Pictures/2020/Apr/DCS2522.jpg"
"./Pictures/2020/Dec/DCS3555.jpg"
"./Pictures/2021/May/DCS5524.jpg"

Listing All Files with a Particular Label

This label was not manually set on any files or directories but rather it is inherited through the hierarchy of the label definitions.

hstk on a client

Command:

hs eval -e 'HAS_LABEL("Oak")?PATH' . --recursive

Expected output:

"./Pictures/2020/Apr/DCS2521.jpg"
"./Pictures/2020/Apr/DCS2522.jpg"
"./Pictures/2020/Dec/DCS3555.jpg"
"./Pictures/2021/May/DCS5524.jpg"
"./Pictures/2021/May/DCS5534.jpg"