DESCRIBE AUTO OPTIMIZE

Shows the current auto-optimization configuration and status for a Delta table.

Category: maintenanceDeltaForge extension

Syntax

DESCRIBE AUTO OPTIMIZE <table>

Description

## Overview DESCRIBE AUTO OPTIMIZE reads the Delta transaction log for the specified table and returns the current auto-optimization configuration as a property/value result set. This allows you to verify whether auto-compaction and optimized writes are active, and to inspect the associated thresholds. ## Behavior The command opens the table's latest snapshot and reads the following table properties from the Delta log metadata: | Property | Description | Default | |----------|-------------|---------| | `delta.autoOptimize.autoCompact` | Whether automatic post-write compaction is enabled. | `false` | | `delta.autoOptimize.optimizeWrite` | Whether write operations automatically coalesce small files. | `false` | | `delta.autoCompact.minNumFiles` | Minimum number of small files required before auto-compaction triggers. | `50` | | `delta.autoCompact.maxFileSize` | Target file size in bytes for auto-compaction. | `134217728` (128 MB) | The result set also includes the resolved `table_path` for reference. If a property has never been explicitly set via SET AUTO OPTIMIZE, the command returns the engine default value. ## Access Control | Privilege | Object | Notes | |-----------|--------|-------| | Read | Table | Only metadata is accessed; no data files are read. | ## Compatibility DESCRIBE AUTO OPTIMIZE is a DeltaForge extension. The underlying table properties (`delta.autoOptimize.*`) follow the Delta Lake convention for auto-optimization metadata, ensuring interoperability with other Delta readers that inspect these properties.

Parameters

Name	Type	Description
`table`		Specify the name or path of the Delta table to inspect. The table must be registered in the session (via CREATE DELTA TABLE or OPEN DELTA TABLE). Fully qualified names (zone.schema.table) are supported.

Examples

-- View auto-optimize settings for a single table
DESCRIBE AUTO OPTIMIZE orders;

-- Inspect auto-optimize on a fully qualified table
DESCRIBE AUTO OPTIMIZE warehouse.sales.transactions;

-- Check configuration after enabling auto-optimize
SET AUTO OPTIMIZE orders ON;
DESCRIBE AUTO OPTIMIZE orders;

-- Verify that a custom target file size was applied
SET AUTO OPTIMIZE events ON TARGET_SIZE 67108864;
DESCRIBE AUTO OPTIMIZE events;

-- Inspect defaults on a table that has never been configured
DESCRIBE AUTO OPTIMIZE staging.raw_logs;

Pitfalls

The command returns engine defaults for properties that have never been set. A value of 'false' does not necessarily mean the property was explicitly disabled; it may simply be the default.
DESCRIBE AUTO OPTIMIZE reads from the latest committed snapshot. If a concurrent SET AUTO OPTIMIZE transaction has not yet committed, the new values will not appear.
The table must be registered in the current session. If the table was created in a different session and not reopened, the command will fail with a 'not registered' error.
This command does not report the runtime state of the background AutoOptimizeManager (queue depth, in-progress jobs). Use DESCRIBE MAINTENANCE STATUS to inspect runtime optimization activity.