Hammerscript Fundamentals

Hammerscript is the query language used throughout Hammerspace to select a set of files and take a specified action on them. Some of the capabilities it enables includes:

Determining which files to place on which storage volume(s), via one or more objectives
Determining which data protection features to apply (WORM, write or read deny or block, versioning, undelete, antivirus)
Determining which files to include in a collection (in the .collection directories)
Running queries or setting metadata on a file or set of files, typically using HSTK

Hammerscript syntax is based on and meant to resemble Microsoft Excel formulas and Visual Basic. You can use simple expressions, or use an if-then-else structure. The structure also has shortcuts. For example:

If <condition> then <action1> else <action2>

Can be represented as:

<condition>?<action1>:<action2>

You can run queries using HSTK to find sets of files and other information using Hammerspace metadata. For example, this command finds files over 1 megabyte in size (SIZE>1MBYTE) and returns their paths relative to the share (PATH):

$ hs eval -r -e 'SIZE>1MBYTE?PATH' .

The previous command is equivalent to the Linux command find . -size +1M except for two differences:

The output from the hs command is the path to the file relative to the share, not the pwd where the command was run.
The command avoids making many calls to the physical file instance, but rather queries the Anvil metadata database directly. By separating the metadata from the files, you avoid the need to consume file storage system resources for metadata operations.
- This is particularly important when a file has been tiered off to a remote object storage volume where, with other storage architectures, the metadata is not readily available to read.

The Using the Hammerspace Toolkit and Advanced Filesystem Reporting section of this document provide examples for every HS command.

Refer to the Appendix section Common Operators Used With Hammerscript for a list of operators used when creating Hammerscript queries.

Combining or Modifying Conditions

In this section, we will explore how we combine multiple conditions into longer statements, and how we apply a negative match to conditions. With just a basic understanding of how conditions can be combined or modified, you will quickly learn how to craft complex ones that target exactly the data you need.

Marking a Condition as a Negative

By using a !, you can apply a negative to many conditions. This is useful when you want to use a condition to exclude files, rather than target them.

Here are some examples of negative matches that will exclude files.

Match files that do not have the Space Launch tag:

# Match files that do NOT have the tag "Space Launch" (case sensitive)
!HAS_TAG("Space Launch")

Match files that do not start with mars (lowercase):

# Match files that do NOT have the name "mars*.*" (case sensitive)
!FNMATCH("mars*.*",NAME)

Match files that do not have the Project Apollo label:

# Match files that do NOT have the label "Project Apollo"
!HAS_LABEL(LABEL('Project Apollo'))

Build a Hammerscript Conditional Statement

Conditions do not need to be singular. You can combine them with and or or statements and even ( ). In this section, we will review three different conditions that also leverage conditional statements.

It is important to note that plain language operators are also supported. For example, despite using different operator formats the following expressions will produce the same result:

# Hammerscript expression that uses symbols for all operators
IS_LIVE&&((HAS_LABEL("launch_report"))||LAST_USE_AGE<=1*DAYS)

# Hammerscript expression that uses plain language for some operators
IS_LIVE AND ((HAS_LABEL("launch_report")) OR LAST_USE_AGE<=1*DAYS)

Each of the examples provided uses ⇐ or >= operators for date statements, meaning that the times referenced will also match the condition. Remove the = if you do not want to match the time referenced, and only the value that precedes or follows it.

Conditional Statement Example 1

Desired match: Live files only (no snapshot data) AND EITHER used within the last 6 months and also has the "Space Launch" tag OR contained within any directory named jupiter and used within the last 30 days.

Equivalent condition written in Hammerscript:

# Match live files that were (used is last 6 months AND have the tag Space Launch) OR (are within a directory named jupiter AND were used in the last 30 days)
IS_LIVE AND ((LAST_USE_AGE<6*MONTHS AND HAS_TAG("Space Launch")) OR (FNMATCH("*/jupiter/*",PATH) AND LAST_USE_AGE<30*DAYS))

Conditional Statement Example 2

Desired match: All files that start with mars (all lowercase) OR files with the orbit extension (all lowercase) that were created less than 60 days ago.

Equivalent condition written in Hammerscript:

# Match all files whose name starts with mars OR (were created within the last 60 days AND match the file name *.orbit)
FNMATCH("mars*.*",NAME) OR (CREATE_AGE < 60*DAYS AND FNMATCH("*.orbit",NAME))

Conditional Statement Example 3

Desired match: Live files last used between 6 months and 1 year ago, including the 6 month and 1 year mark.

Equivalent condition written in Hammerscript:

# Match live files that were last used between 6 months and 1 year ago (inclusive of the start and end dates)
IS_LIVE AND (LAST_USE_AGE>=6*MONTHS AND LAST_USE_AGE<=1*YEARS)