Maintenance SQL reference

ReferenceApplies to: Unified engine deployments

CALL submits one table maintenance operation. The target catalog and connector must support its action. The current native Iceberg provider supports data compaction, positional-delete compaction, and manifest optimization on format-v2 tables.

Procedure names and target resolution

Accepted name forms are:

CALL procedure_name(...);
CALL system.procedure_name(...);
CALL maintenance.procedure_name(...);
CALL catalog_name.system.procedure_name(...);
CALL catalog_name.maintenance.procedure_name(...);

Without a catalog qualifier, the target table name is resolved using the session’s catalog and namespace. With a procedure catalog qualifier, the table must resolve to that same catalog. Use an explicit namespace and table name to make the target clear. Use either named arguments or positional arguments in one call. Do not mix them. Named arguments make maintenance settings easier to review. The examples below reuse the private tables created by the recipes.

Data compaction

Aliases: compact_data, rewrite_data_files.

Argument	Meaning	Default
`table`	Table name as a string	Required
`strategy`	`binpack`, `sort`, or `zorder`	`binpack`
`sort_order`	Sort expression string for `sort`	Required for `sort`
`columns`	Array of distinct column-name strings for `zorder`	Required unless supplied by a Z-order sort expression
`target_file_size_bytes`	Approximate output file target	`134217728` bytes, or configured instance default
`max_group_size_bytes`	Input grouping limit	`1073741824` bytes, or configured instance default
`min_input_files`	Minimum candidate files in a group	`2`, or configured instance default

CALL system.rewrite_data_files(
  table => 'maintenance_docs.data_demo',
  strategy => 'binpack',
  options => map(
    'target-file-size-bytes', '1048576',
    'max-file-group-size-bytes', '8388608',
    'min-input-files', '2'
  )
);

Direct named options and the options => map(...) form feed the same settings. Hyphenated option keys are normalized to underscores. max_file_group_size_bytes is an alias for max_group_size_bytes. Repeating the same setting through both forms is rejected. Sizes and file counts must be positive. The target file size cannot exceed the requested group size. Runtime input, output, and decoded-memory limits also apply. where filtering is not supported by this implementation. Sort expressions accept column paths, direction, and null order, such as region ASC NULLS LAST, id DESC NULLS FIRST. Z-order also accepts strategy => 'sort', sort_order => 'zorder(id, amount)'. The explicit strategy => 'zorder', columns => array('id', 'amount') form is often clearer. Result columns: rewritten_data_files_count, added_data_files_count, rewritten_bytes_count.

Positional-delete compaction

Aliases: compact_deletes, rewrite_position_delete_files.

Argument	Meaning	Default
`table`	Table name as a string	Required
`target_file_size_bytes`	Approximate replacement delete-file target	`134217728` bytes, or configured instance default

CALL maintenance.compact_deletes(
  table => 'maintenance_docs.delete_demo',
  target_file_size_bytes => 1048576
);

Result columns: rewritten_delete_files_count, added_delete_files_count, rewritten_bytes_count. This action compacts positional-delete files; it does not expire snapshots or physically purge all old row data.

Manifest optimization

Aliases: optimize_metadata, rewrite_manifests.

Argument	Meaning	Default
`table`	Table name as a string	Required
`target_metadata_size_bytes`	Approximate metadata output target	`8388608` bytes, or configured instance default

CALL system.optimize_metadata(
  table => 'maintenance_docs.manifest_demo',
  target_metadata_size_bytes => 1048576
);

Result columns: rewritten_manifests_count, added_manifests_count. rewrite_manifests is an alias for the same action. Named options can supply the metadata target with either name.

Recognized but unsupported by native Iceberg

Action	Recognized procedure names
Expire history	`expire_history`, `expire_snapshots`
Clean unreferenced files	`clean_unreferenced_files`, `remove_orphan_files`
Clean obsolete metadata	`clean_obsolete_metadata`, `delete_old_metadata_files`, `remove_old_metadata`
Compute statistics	`compute_statistics`, `compute_table_stats`, `compute_partition_stats`

These names are parsed into maintenance actions, but the current provider rejects those actions. They are not runnable cleanup or retention recipes. A dry-run argument does not enable an unsupported action.

Completion, no-ops, and retries

Wait for the operation’s successful completion and confirmed publication. Prepared files or intermediate counters alone are not proof that a new table state is visible. Read the table again after completion. A no-op can succeed when no files qualify. Check counters and the actual table rather than assuming every call must rewrite files. For a lost response, retry the original operation with its original identity. A fresh CALL is a new operation against the table state resolved for that request. Review any concurrent table changes before starting a replacement operation. Instance defaults and limits are described in maintenance configuration. Saved properties for future writes are described in TBLPROPERTIES.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Maintenance SQL reference

Procedure names and target resolution

Data compaction

Positional-delete compaction

Manifest optimization

Recognized but unsupported by native Iceberg

Completion, no-ops, and retries

​Procedure names and target resolution

​Data compaction

​Positional-delete compaction

​Manifest optimization

​Recognized but unsupported by native Iceberg

​Completion, no-ops, and retries

Procedure names and target resolution

Data compaction

Positional-delete compaction

Manifest optimization

Recognized but unsupported by native Iceberg

Completion, no-ops, and retries