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

• Create and manage folders .
• Rename a folder .
• Optimize folder management .

Try it for yourself

If you're new to Google Cloud, create an account to evaluate how Cloud Storage performs in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Try Cloud Storage free