TBLPROPERTIES

ReferenceApplies to: Unified engine deployments

TBLPROPERTIES saves named settings on a table. Use it to record custom metadata, choose an Iceberg format version at creation, or control supported options for later writes. This page covers Unified’s Iceberg table path. The properties a catalog can store are broader than the settings the Unified writer actually uses. A saved key does not, by itself, prove that a writer feature is supported.

Create a table with properties

Choose a writable Iceberg catalog in Workbench. Use an unused maintenance_docs namespace, or replace that name throughout the example. This script uses inline data and replaces only properties_demo.

SET spark.sql.caseSensitive = true;
CREATE NAMESPACE IF NOT EXISTS maintenance_docs;
DROP TABLE IF EXISTS maintenance_docs.properties_demo;
CREATE TABLE maintenance_docs.properties_demo (
  id BIGINT,
  category STRING,
  amount BIGINT
) USING iceberg
TBLPROPERTIES (
  'format-version' = '2',
  'docs.owner' = 'analytics',
  'write.target-file-size-bytes' = '1048576',
  'write.parquet.compression-codec' = 'zstd',
  'write.parquet.compression-level' = '3'
);

INSERT INTO maintenance_docs.properties_demo
VALUES (1, 'Books', 10), (2, 'Games', 20), (3, 'Books', 30);

SHOW TBLPROPERTIES maintenance_docs.properties_demo;
SELECT COUNT(*) AS row_count, SUM(amount) AS total_amount
FROM maintenance_docs.properties_demo;

The row check returns three rows and total amount 60. The saved custom property docs.owner is analytics, and the saved compression codec is zstd. Property keys and values are quoted strings in these examples. Use the full property key, including dots and hyphens, exactly as shown.

Inspect all properties or one key

SHOW TBLPROPERTIES maintenance_docs.properties_demo;
SHOW TBLPROPERTIES maintenance_docs.properties_demo (
  'write.parquet.compression-codec'
);

The first statement returns saved key/value pairs. The second returns the value of the requested key, here zstd. Asking for a key that is not saved reports a missing-property error. Saved properties do not necessarily list every effective default. An omitted compression key can still use the writer’s default. Iceberg’s format version is special metadata; it is not handled as an ordinary custom key in every properties result. Use the table definition and extended description when reviewing the format.

Change later write settings

This block reuses the table created above. It changes the compression for the next insert and sets a custom owner value.

ALTER TABLE maintenance_docs.properties_demo SET TBLPROPERTIES (
  'docs.owner' = 'reporting',
  'write.parquet.compression-codec' = 'gzip',
  'write.parquet.compression-level' = '6'
);
INSERT INTO maintenance_docs.properties_demo
VALUES (4, 'Garden', 40);
SHOW TBLPROPERTIES maintenance_docs.properties_demo (
  'write.parquet.compression-codec'
);
SELECT COUNT(*) AS row_count, SUM(amount) AS total_amount
FROM maintenance_docs.properties_demo;

The selected property returns gzip. The table now has four rows and total amount 100. Existing files keep their earlier encoding. The insert uses the settings resolved for its own write. Changing properties does not convert old files to the new codec or resize them. To rewrite existing files, use a suitable maintenance action or a deliberate data rewrite. Confirm the physical output through table inspection.

Remove a saved property

ALTER TABLE maintenance_docs.properties_demo
UNSET TBLPROPERTIES IF EXISTS (
  'docs.owner',
  'write.parquet.compression-level'
);
SHOW TBLPROPERTIES maintenance_docs.properties_demo;

IF EXISTS tolerates a key that has already been removed. Without it, removing a missing property fails. Removing the explicit compression level lets the next write use the remaining codec’s default level. It does not reset the codec or rewrite existing files.

Iceberg format version

New Iceberg tables default to v3. Explicitly request v2 at creation when using the current native maintenance provider:

CREATE TABLE table_name (...) USING iceberg
TBLPROPERTIES ('format-version' = '2');

format-version changes the actual Iceberg table format. It is not a label. The Iceberg path supports version increases through supported versions, rejects downgrades, and does not allow this key to be unset. The following is an upgrade template, rather than a required step in the practice flow:

ALTER TABLE table_name SET TBLPROPERTIES ('format-version' = '3');

Choose a format supported by your readers and writers. Upgrading a v2 table to v3 also takes it outside the current format-v2 native maintenance support. Setting the property back to 2 is not a supported downgrade.

Supported file and Parquet write properties

A row group is a block of rows inside a Parquet file. Pages hold smaller blocks of column values. A dictionary stores repeated values that pages can refer to by code.

Property	What it controls	Default before runtime limits
`write.target-file-size-bytes`	Approximate output file target	`536870912` bytes, 512 MiB
`write.parquet.compression-codec`	Column compression codec	`zstd`
`write.parquet.compression-level`	Level for Zstd, Gzip, or Brotli	`3`, `6`, or `1`, respectively
`write.parquet.row-group-size-bytes`	Approximate row-group target	`134217728` bytes, 128 MiB
`write.parquet.page-size-bytes`	Approximate data-page target	`1048576` bytes, 1 MiB
`write.parquet.page-row-limit`	Data-page row limit	`20000`
`write.parquet.dict-size-bytes`	Dictionary size target	`2097152` bytes, 2 MiB

The writer accepts uncompressed, snappy, zstd, gzip, brotli, lz4, and lz4_raw. LZO is unsupported. A compression level must be valid for its codec. A level paired with Snappy, LZ4, or uncompressed output is rejected. Sizes and row limits must be positive. File and encoding targets are capped by runtime memory and buffer limits. Batch boundaries can produce small files even when the configured file target is large. A file-size setting is a target, not an exact output size.

Content-defined chunking

Content-defined chunking chooses Parquet page boundaries from the data values before encoding and compression. It is separate from file compaction and from row-level change data capture.

Property	Default
`write.parquet.content-defined-chunking.enabled`	`false`
`write.parquet.content-defined-chunking.min-chunk-size`	`262144` bytes
`write.parquet.content-defined-chunking.max-chunk-size`	`1048576` bytes
`write.parquet.content-defined-chunking.norm-level`	`0`

An optional example for the existing practice table:

ALTER TABLE maintenance_docs.properties_demo SET TBLPROPERTIES (
  'write.parquet.content-defined-chunking.enabled' = 'true',
  'write.parquet.content-defined-chunking.min-chunk-size' = '262144',
  'write.parquet.content-defined-chunking.max-chunk-size' = '1048576',
  'write.parquet.content-defined-chunking.norm-level' = '0'
);

When enabled, the minimum must be positive and smaller than the maximum. The normalization level must be in the encoder’s supported range, currently -63 through 63. These options affect later writes; the statement above does not create new data files by itself.

Table settings, write options, and maintenance arguments

Mechanism	Scope	Example
`TBLPROPERTIES`	Saved on the table for later writes	`'write.target-file-size-bytes' = '1048576'`
DataFrame per-write options	Override supported settings for one write	`.option('target-file-size-bytes', '1048576')`
Maintenance `CALL` arguments	Control one maintenance action	`target_file_size_bytes => 1048576`
Instance configuration	Supplies defaults and limits	Maintenance task memory budget

Supported per-write overrides take priority over table properties, then encoder defaults. They do not change the saved properties. SQL INSERT has no per-write OPTIONS clause. See options for one DataFrame write. The default normal-write target is 512 MiB. The default maintenance compaction target is 128 MiB before instance overrides. They are separate settings. Choose maintenance arguments for the maintenance call rather than assuming a table write target configures every rewrite. Use PARTITIONED BY for a table’s partition transforms. Storing an arbitrary partition or sort key as a property does not enable partition evolution, enforced write sort order, per-column Parquet controls, or writer distribution in this path.

Validation and custom metadata

Custom properties such as docs.owner can be saved as table metadata. They do not change the writer unless a supported feature reads them. Unknown write.parquet.* and write.target-* keys are rejected when a write is planned. Invalid sizes or codec settings may be saved by the catalog and then rejected by the writer. Check both the saved properties and the next write’s outcome; property storage alone is not end-to-end validation. The Streaming Iceberg sink has its own connector options. Do not copy these dotted Unified write properties into a Streaming sink without checking the Streaming sink options.

Clean up

After the examples complete, remove only the practice table:

DROP TABLE IF EXISTS maintenance_docs.properties_demo;

Keep the practice namespace while you are using the other maintenance recipes.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Create a table with properties

Inspect all properties or one key

Change later write settings

Remove a saved property

Iceberg format version

Supported file and Parquet write properties

Content-defined chunking

Table settings, write options, and maintenance arguments

Validation and custom metadata

Clean up

​Create a table with properties

​Inspect all properties or one key

​Change later write settings

​Remove a saved property

​Iceberg format version

​Supported file and Parquet write properties

​Content-defined chunking

​Table settings, write options, and maintenance arguments

​Validation and custom metadata

​Clean up

Create a table with properties

Inspect all properties or one key

Change later write settings

Remove a saved property

Iceberg format version

Supported file and Parquet write properties

Content-defined chunking

Table settings, write options, and maintenance arguments

Validation and custom metadata

Clean up