About folders in buckets with hierarchical namespace enabled

This page provides information about folders in buckets with hierarchical namespace enabled.

Overview

Folders exist as a resource in buckets with hierarchical namespace enabled. You can organize objects within folders in a file system-like structure. Cloud Storage provides folder management APIs that enable operations such as creating, deleting, renaming, and listing folders, as well as retrieving folder metadata.

Folder metadata

A folder's metadata contains structured information about the folder. For detailed information about folder metadata, see the Folder resource in the Cloud Storage JSON API reference documentation.

The key components of a folder metadata are as follows:

  • bucket: The name of the bucket where the folder resides. For example, my-bucket.
  • id: A unique identifier for the folder within the bucket. For example, hns-bucket/dir1/.
  • kind: The resource type. For a folder, this value is always storage#folder.
  • name: The name of the folder. For example, dir1/.
  • selfLink: A URL that references the folder in the Cloud Storage API.
  • timeCreated: The timestamp when the folder was created. For example, 2023-05-05T16:32:08.878000+00:00.
  • updated: The timestamp when the folder was last updated. For example, 2024-05-06T16:32:08.878000+00:00.

Considerations

When creating folders, consider the following:

  • Object and folder names: Buckets with hierarchical namespace enabled, support all valid object names, including those with leading, trailing slashes (/) or consecutive slashes. Each forward slash (/) in an object name represents a folder. The following table shows examples of the relationship between object names and their corresponding location in the folder hierarchy:

    Object name Location in the folder hierarchy
    foo.txt Every bucket includes a root folder. Object foo.txt resides under the root folder of the bucket.
    dir1/foo.txt Object foo.txt resides within a top-level folder named dir1/. The top-level folder is distinct from the root folder.
    dir1/ The trailing slash in object names like dir1/ indicates that the object resides within the folder. In this example, the object name dir1/ is the same as the parent folder name dir1/.
    dir1//foo.txt Object foo.txt resides in a second-level folder named dir1//, a child folder of dir1/.

  • Maximum folder depth: Buckets with hierarchical namespace enabled support a maximum folder depth of 50. As a result, object names cannot have more than 50 slashes (/).

  • Maximum folder name size: 512 bytes (UTF-8 encoded).

  • Automatic folder creation: Creating a new object automatically creates any non-existent folders specified in the object's path. For example, creating an object named dir1/foo.txt automatically creates the folder dir1/ if it doesn't already exist.

  • Sensitive or personally identifiable information (PII): Folder names are more broadly visible than folder metadata. For example, folder names appear in URLs and when listing folders or objects in a bucket. Don't include sensitive information or PII in folder names.

What's next