This is an automated email from the ASF dual-hosted git repository.
weichiu pushed a commit to branch HDDS-9225-website-v2
in repository https://gitbox.apache.org/repos/asf/ozone-site.git
The following commit(s) were added to refs/heads/HDDS-9225-website-v2 by this
push:
new 956e87147 HDDS-14464. [Docs] Core Concepts -> Namespace -> Bucket ->
Layouts -> File System Optimized Buckets (FSO) (#294)
956e87147 is described below
commit 956e87147858855fd839532293959e227a5d983a
Author: Gargi Jaiswal <[email protected]>
AuthorDate: Wed Jan 28 00:24:20 2026 +0530
HDDS-14464. [Docs] Core Concepts -> Namespace -> Bucket -> Layouts -> File
System Optimized Buckets (FSO) (#294)
---
.../04-layouts/02-file-system-optimized.md | 69 +++++++++++++++++++++-
1 file changed, 68 insertions(+), 1 deletion(-)
diff --git
a/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md
b/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md
index 5e6616fbe..b226fea71 100644
---
a/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md
+++
b/docs/03-core-concepts/03-namespace/02-buckets/04-layouts/02-file-system-optimized.md
@@ -4,4 +4,71 @@ sidebar_label: File System Optimized (FSO)
# File System Optimized Buckets (FSO)
-**TODO:** File a subtask under
[HDDS-9857](https://issues.apache.org/jira/browse/HDDS-9857) and complete this
page or section.
+## Overview
+
+**File System Optimized** (FSO) is a bucket layout optimized for Hadoop
Compatible File System (HCFS) operations. Unlike the Object Store (OBS) layout,
FSO maintains separate entries for intermediate directories, enabling efficient
file system operations like directory listing, renaming, and deletion.
+FSO buckets support **atomic rename** and **delete operations** on directories
at any level in constant time, regardless of directory depth or the number of
files contained within.
+
+For example, in an FSO bucket, keys are stored with their hierarchical
structure preserved:
+
+```text
+/mybucket/data/2025/nov/report
+/mybucket/data/2025/dec/summary
+/mybucket/archive/2024/logs/applog
+```
+
+Each intermediate directories (`data`, `2025`, `nov`, etc.) are stored as a
separate entry, allowing efficient directory-level operations.
+
+:::note
+FSO is the default bucket layout in Ozone. To explicitly specify FSO layout
when creating a bucket, use the `--layout` flag:
+
+```bash
+ozone sh bucket create /<volume-name>/<bucket-name> --layout
FILE_SYSTEM_OPTIMIZED
+```
+
+:::
+
+## Why FSO for Ozone?
+
+### 1. Atomic Operations (The O(1) Factor)
+
+In a standard Object Store, if you rename a directory containing **1 million
files**, the system has to:
+
+- Find all 1 million keys
+- Copy them to a new path string
+- Delete the 1 million old keys
+
+This is **O(n)** operation — the more files you have, the longer it takes.
+
+In FSO, a **rename** is just a metadata pointer update. To rename `/data` to
`/archive`, Ozone simply finds the entry for `data` in the `DirectoryTable` and
updates its name to `archive`. All the children (the millions of files) stay
exactly where they are because they point to the `unique ID` of that directory,
not its name.
+
+### 2. Delete operations
+
+Deleting a directory with millions of files is efficient because all child
entries share the same parent ID prefix, allowing Ozone to quickly locate and
remove them using prefix-based queries, rather than scanning the entire
namespace.
+
+## When to Use FSO vs Object Store (OBS)
+
+Choose **File System Optimized (FSO)** when:
+
+- Using Hadoop Compatible File System interfaces
+- Storing data for analytics workloads (Hive, Spark ...)
+- Working with hierarchical directory structures
+- Requiring atomic directory operations (rename, delete)
+- Needing trash/recycle bin functionality
+
+Choose **Object Store (OBS)** when:
+
+- Primarily using S3-compatible APIs
+- Working with flat object access patterns
+
+## Configuration
+
+To update the default layout when creating buckets, configure these properties
in `ozone-site.xml`:
+
+| Property | Default Value | Description |
+|----------|---------------|-------------|
+| `ozone.default.bucket.layout` | none | Sets the default layout for all
buckets if no layout is specified during creation by the client |
+| `ozone.client.fs.default.bucket.layout` | `FILE_SYSTEM_OPTIMIZED` | Sets the
default layout for buckets created using the OFS client |
+| `ozone.s3g.default.bucket.layout` | `OBJECT_STORE` | Defines the default
layout for buckets created through the S3 API |
+
+For detailed technical information about the internal metadata structure and
implementation, see the [File System Optimization System
Internals](../../../../07-system-internals/07-features/01-filesystem-optimization.md)
documentation.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
