From 4488a4fb06ba925efc8a18d4593235ca3aab7198 Mon Sep 17 00:00:00 2001
From: Shreyas Ganesh <vansi.ganeshs@gmail.com>
Date: Fri, 14 Nov 2025 12:33:58 -0500
Subject: [PATCH] docs: document sstables quarantine subdirectory

Add documentation for the quarantine/ subdirectory that holds SSTables
isolated due to validation failures or corruption. Document the scrub
operation's quarantine_mode parameter options and the drop_quarantined_sstables
API operation.

Also update the directory hierarchy example to include the quarantine directory.

Fixes #10742

Signed-off-by: Shreyas Ganesh <vansi.ganeshs@gmail.com>

Closes scylladb/scylladb#27023
---
 docs/dev/sstables-directory-structure.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/docs/dev/sstables-directory-structure.md b/docs/dev/sstables-directory-structure.md
index 0b46d603bb..a7c25111b4 100644
--- a/docs/dev/sstables-directory-structure.md
+++ b/docs/dev/sstables-directory-structure.md
@@ -28,6 +28,7 @@ Scylla uses the following directory structure to store all its SSTables, for exa
     │   │   │       ├── ...
     │   │   │       └── mc-1-big-TOC.txt
     │   │   ├── staging
+    │   │   ├── quarantine
     │   │   └── upload
     │   └── cf-7ec943202fc611e9a130000000000000
     │       ├── snapshots
@@ -36,6 +37,7 @@ Scylla uses the following directory structure to store all its SSTables, for exa
     │       │       ├── ks-cf-ka-3-TOC.txt
     │       │       └── manifest.json
     │       ├── staging
+    │       ├── quarantine
     │       └── upload
     ├── system
     │   ├── schema_columnfamilies-45f5b36024bc3f83a3631034ea4fa697
@@ -167,6 +169,21 @@ The per-table directory may contain several sub-directories, as listed below:
   Used for ingesting external SSTables into Scylla on startup.
 
 
+* Quarantine directory (`quarantine`)
+  A sub-directory holding SSTables that have been quarantined, typically due to
+  validation failures or corruption detected during scrub operations.
+  
+  Quarantined SSTables are isolated to prevent them from being read or used by the
+  database. They can be inspected manually for debugging purposes or removed using
+  the `drop_quarantined_sstables` API operation.
+  
+  The scrub operation can be configured to handle quarantined SSTables using the
+  `quarantine_mode` parameter with the following options:
+  - `INCLUDE`: Process both regular and quarantined SSTables (default)
+  - `EXCLUDE`: Skip quarantined SSTables during scrub
+  - `ONLY`: Process only quarantined SSTables
+
+
 * Temporary SSTable directory (`<generation>.sstable`)  
   A directory created when writing new SSTables.