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

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