DROP FOLDER

Removes an empty directory inside a zone's storage root (local or cloud). Refuses if the folder still has any contents.

Category: catalogDeltaForge extension

Syntax

DROP FOLDER '<rel/path>' [IF EXISTS] IN ZONE <zone>

Description

## Overview DROP FOLDER removes an empty directory inside a zone's storage root. It is a cleanup affordance for demos, batch jobs, and orchestration scripts that need to tidy parent wrapper directories the engine cannot reach through table-level DROPs. DROP DELTA TABLE ... WITH FILES and DROP EXTERNAL TABLE ... WITH FILES delete exactly the table's own hosting folder and everything inside it. They never touch any directory outside the table's LOCATION, which is the right rule for safety (a table cannot ever destroy data outside its own folder), but it means that any per-demo or per-project wrapper directory the LOCATION sat under ends up empty on disk after the last table is dropped. DROP FOLDER is the explicit, user-controlled command that removes those wrappers. ## Behavior - The path is treated as zone-relative. Absolute paths, drive letters, `file://` schemes, and `..` segments are stripped and joined under the zone's storage_root. The command can never escape the zone. - Absolute cloud URLs (`s3://`, `abfss://`, `gs://`) are rejected. Use a zone-relative path and let the zone's storage backend determine the actual scheme. - An empty / `.`-only path targeting the zone root itself is rejected. Use DROP ZONE to remove a zone. - If the resolved folder is non-empty (contains any file or subdirectory), the command fails with an error and nothing is deleted. - If the folder does not exist: - With IF EXISTS: the statement completes successfully and reports the skip. - Without IF EXISTS: the command fails with a `DROP FOLDER: '<path>' does not exist` error. - The operation is non-recursive: even when the folder is empty, only that one directory is removed (sibling directories and the parent are never touched). ## Storage backends - **Local filesystem.** Uses `std::fs::remove_dir` (non-recursive). The empty-check reads at most one entry via `read_dir`. - **Cloud (S3, ABFSS, ADLS Gen2, GCS).** Lists objects under the prefix with `list(prefix).next()`; the listing is short-circuited as soon as any object is observed. When the listing is empty the directory marker is removed via `delete(prefix)`. For ADLS Gen2 HNS, the DFS-endpoint store is used when available because the Blob API rejects directory deletes with `OperationNotSupportedOnDirectory`. ## Authorization The command requires READ on the zone (the zone metadata is fetched through the control plane to resolve `storage_root`). Folder-level WRITE elevation is not yet enforced separately; the zone-boundary resolver ensures the command can only touch directories under the zone, so a user without READ on the zone cannot target a folder there. ## Compatibility DROP FOLDER is a DeltaForge extension. There is no equivalent in standard SQL, Spark SQL, Delta Lake, or Apache Iceberg. The closest analog is a manual `aws s3 rm --recursive` / `rmdir` invoked outside the engine, but DROP FOLDER ties the operation to the zone's RBAC boundary and refuses to destroy non-empty data.

Parameters

Name	Type	Description
`<rel/path>`		Zone-relative folder path. Absolute paths and `..` segments are stripped and the path is re-rooted under the named zone's storage_root. The path must point at a directory that is strictly inside the zone; targeting the zone root itself is an error (use DROP ZONE for that).
`IF EXISTS`		Suppresses the not-found error when the resolved folder does not exist. The statement completes successfully and reports the skip.
`<zone>`		Name of an existing zone. The folder is resolved under this zone's storage_root, so a zone is required: there is no zone-less variant.

Examples

-- Tidy the per-demo wrapper after DROP DELTA TABLE ... WITH FILES.
DROP DELTA TABLE demo_zone.iceberg_demos.financial_transactions WITH FILES;
DROP FOLDER 'iceberg-uniform-schema-rename' IF EXISTS IN ZONE demo_zone;

-- Remove an empty staging directory in a bronze zone.
DROP FOLDER 'staging/raw' IN ZONE bronze;

-- IF EXISTS lets cleanup scripts run idempotently.
DROP FOLDER 'tmp/job-2024-Q4' IF EXISTS IN ZONE landing;

Pitfalls

The folder must be empty. DROP FOLDER does not recurse and does not silently delete contents. If the folder still contains files or subdirectories, the command fails and reports one of the offending entries.
The path is always re-rooted under the zone. An absolute path such as 'C:/temp/foo' or '/var/data/bar' is reduced to its trailing fragment and joined under the zone storage_root; the command does not escape the zone even when the literal looks absolute.
Targeting the zone root itself (path '' or '.') is rejected. Use DROP ZONE to remove an entire zone.
Cloud directory markers (ADLS Gen2 HNS) are removed via the DFS endpoint when configured. On Azure accounts without HNS the deletion of a flat-prefix marker is effectively a no-op once the prefix is empty.
DROP FOLDER does not invalidate any catalog state. If a catalog table still references a path inside the folder, the table will continue to appear in SHOW TABLES, and the next SELECT will fail with a file-not-found error. Drop the table first.