This section explains how to create, retrieve, list, and delete user-defined metadata in Qumulo Core by using the qq CLI.

How User-Defined Metadata Works in Qumulo Core

Qumulo Core lets you add user-defined metadata to any file type stored in its file system. User-defined metadata comprises user-specified key-value pairs that have the following requirements:

  • The key must be a Unicode string.
  • The value must be a sequence of bytes.
  • The total size of each key-value pair must be under 400 KB.

Keyspace Types and Functions

User-defined metadata in Qumulo Core is divided into GENERIC and S3 keyspaces. Keyspaces work like containers for key-value pairs. The S3 keyspace primarily supports the S3 API, which requires all files to have two sets of metadata in separate keyspaces.

Keyspaces can hold approximately 17 trillion key-value pairs and have the following requirements:

  • All keys within a keyspace must be unique.
  • The keyspace and key are required to create or access a user-defined metadata entry.

Managing User-Defined Metadata by Using the qq CLI

This section explains how to create, retrieve, list, and delete user-defined metadata by using the qq CLI.

Prerequisites

Managing user-defined metadata requires the following privileges:

  • READ_EA: Read the user-defined metadata from a file
  • WRITE_EA: Write to, or delete, the user-defined metadata of a file

To Create a Generic User-Defined Metadata Entry for a File by Using the qq CLI

Run the fs_set_user_metadata command and specify the path to the file, the key, and the value. For example:

qq fs_set_user_metadata \
  --path my-file \
  --key my-key \
  --value my-value

To specify a non-text value for the user-defined metadata, use the --base64-value or --hex-value flag.

For more information, see qq fs_set_user_metadata in the Qumulo qq CLI Command Guide.

To Retrieve a Generic User-Defined Metadata Entry for a File by Using the qq CLI

Use fs_get_user_metadata command and specify the path to the file and the key. For example:

qq fs_get_user_metadata \
  --path my-file \
  --key my-key
  • To specify a non-text value for the user-defined metadata, use the --base64-value or --hex-value flag.
  • To access the user-defined metadata within a file snapshot, use the --snapshot flag and specify the shapshot ID.

For more information, see qq fs_get_user_metadata in the Qumulo qq CLI Command Guide.

To List All Generic User-Defined Metadata Entries for a File by Using the qq CLI

Run the fs_list_user_metadata command and specify the path to the file. For example:

qq fs_list_user_metadata \
  --path my-file
  • To specify a non-text value for the user-defined metadata, use the --base64-value or --hex-value flag.
  • To access the user-defined metadata within a file snapshot, use the --snapshot flag and specify the shapshot ID.

For more information, see qq fs_list_user_metadata in the Qumulo qq CLI Command Guide.

To Delete a Generic User-Defined Metadata Entry for a File by Using the qq CLI

Run the fs_delete_user_metadata command and specify the path to the file and the key. For example:

  qq fs_delete_user_metadata \
    --path my-file \
    --key my-key

For more information, see qq fs_delete_user_metadata in the Qumulo qq CLI Command Guide.

Managing User-Defined Metadata by Using the S3 API

S3 categorizes metadata as:

  • Metadata

    • Immutable metadata that remains for the life of the object.

    • Qumulo Core maps metadata to the S3 keyspace.

  • Tags

    • Mutable metadata that doesn’t impact the object’s entity tag.

    • Qumulo Core maps tags to the GENERIC keyspace.

In Qumulo Core 6.3.2 (and higher) the Qumulo S3 API supports user-defined metadata fully. For more information about how to access metadata by using the S3 API, see the Amazon Simple Storage Service API Reference.