Some or all of the information on this page might not apply to Cloud de Confiance by S3NS. See Differences from Google Cloud for more details.

About folders in buckets with hierarchical namespace enabled

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

Overview

When you create a bucket with hierarchical namespace enabled, the bucket uses a true file system structure as opposed to a standard flat namespace. Folders exist as a resource in buckets with hierarchical namespace enabled. Using folders, you can organize your objects more effectively and gain access to true directory capabilities, such as atomic folder renames and efficient metadata operations.

You can manage folders by using the create, delete, rename, list, and get operations. To learn how to perform these operations, see Create and manage folders and Rename a folder.

Folders in buckets with hierarchical namespace enabled are different from simulated folders and managed folders. Simulated folders exist in flat namespace buckets and managed folders can be applied in both flat namespace buckets and buckets with hierarchical namespace enabled. Managed folders are primarily used to grant IAM permissions to groups of objects. For more information about these other folder types, see Folder types.

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.

Folder operations

This section describes the operations you can perform on folders.

Create a folder

You can explicitly create folders by using the folder creation operation. Additionally, when you create an object and specify a non-existent folder in its path, the missing parent folder is automatically created for you. For example, creating an object named dir1/foo.txt automatically creates the folder dir1/ if it doesn't already exist.

For information about folder naming, see Considerations.

List folders

You can retrieve a list of folders in your bucket by using the list folders operation. Because folders are distinct resources in buckets with hierarchical namespace enabled, this operation evaluates the true folder structure instead of simulating folders from object paths.

When listing folders, you can filter the results using parameters such as prefix, delimiter, lexicographicStart, and lexicographicEnd. For example, setting the delimiter parameter to / lets you list folders in a directory-like mode, returning only the folders that match the prefix or exist one level below it.

The list folders operation returns paginated results. A single response page can contain a maximum of 1000 folders.

Get the metadata of a folder

You can retrieve the properties of a folder by using the get folder metadata operation. This operation retrieves information about the folder resource itself, rather than the objects it contains.

This operation returns a folder's metadata, which provides structured information such as its creation timestamp, its unique identifier, and the bucket where it resides. For a detailed list of the properties returned by this operation, see Folder metadata.

Rename or move a folder

Renaming a folder and moving a folder use the same underlying operation. The operation is an atomic, metadata-only change that updates the folder's path without physically copying or deleting the underlying objects. Renaming a folder also updates the folder's path for resources within the folder, such as child folders, objects, and managed folders. This makes the operation fast and avoids object copy costs.

In the JSON API and Google Cloud CLI, renaming and moving use the same URL endpoint or command. In the Cloud de Confiance console, Rename folder and Move folder are presented as two distinct options, but options execute the same backend operation.

During a folder rename operation, you can read and list the folders being renamed, but you can't run write operations on them.

The folder rename operation initiates a long-running operation.

Delete a folder

You can permanently delete an empty folder by using the delete folder operation. While folders can be created automatically during object operations, they are not automatically removed when they become empty. You must delete them explicitly.

If you delete a folder that has a managed folder at the same path, the managed folder is also deleted.

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).
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.
Interaction with managed folders: In buckets with hierarchical namespace enabled, you can manage access control by using managed folders in conjunction with folders.