Iceberg format version support（Iceberg 格式版本支持）¶
The Apache Iceberg table format specification ↗ is versioned, with each version extending the previous, though not all tools and clients may support the latest versions.
Foundry supports reading and writing Iceberg tables in format versions 2 and 3.
Format version defaults¶
The format version used by default depends on whether client-side Iceberg table encryption is enabled.
Foundry defaults to v2 for tables where client-side encryption is disabled, due to limited client support for the v3 specification.
Foundry defaults to v3 for tables where client-side encryption is enabled, as Iceberg table encryption ↗ is a v3 feature.
Override format versions¶
You can optionally override the default format version by specifying the version explicitly using the format-version table property.
For example, you can run:
```python tab="PySpark transforms" @transform.spark.using( output=TableOutput("/path/table_name"), ) def compute(ctx: TransformContext, output: TableTransformOutput) -> None:
df_custom = ctx.spark_session.createDataFrame([["Hello"], ["World"]], schema=["phrase"])
df_custom.writeTo(output.identifier)\
.using("iceberg") \
.tableProperty("format-version", "3") \
.createOrReplace()
sql tab="SQL maintenance"
ALTER TABLE ri.tables.main.table.00000002...
SET TBLPROPERTIES ('format-version' = '3');
```
```python tab="External client (PyIceberg)" catalog.create_table( "path.table", schema=schema, properties={"format-version": "3"} )
:::callout{theme="neutral"}
While you can upgrade tables from v2 to v3, you cannot downgrade v3 tables to v2.
:::
---
# 中文翻译
# Iceberg 格式版本支持
[Apache Iceberg 表格式规范 ↗](https://iceberg.apache.org/spec/) 采用版本化管理，每个新版本都在前一版本基础上进行扩展，但并非所有工具和客户端都支持最新版本。
Foundry 支持以格式版本 2 和 3 读写 Iceberg 表。
## 格式版本默认值
默认使用的格式版本取决于是否启用了[客户端侧 Iceberg 表加密](https://palantir.com/docs/foundry/iceberg/storage/#encryption-settings)。
由于客户端对 v3 规范的支持有限，当客户端侧加密禁用时，Foundry 默认使用 v2 版本。
当客户端侧加密启用时，Foundry 默认使用 v3 版本，因为 [Iceberg 表加密 ↗](https://iceberg.apache.org/docs/nightly/encryption/) 是 v3 的一项功能。
## 覆盖格式版本
您可以通过使用 `format-version` 表属性显式指定版本来覆盖默认格式版本。
例如，您可以运行：
```python tab="PySpark 转换"
@transform.spark.using(
output=TableOutput("/path/table_name"),
)
def compute(ctx: TransformContext, output: TableTransformOutput) -> None:
df_custom = ctx.spark_session.createDataFrame([["Hello"], ["World"]], schema=["phrase"])
df_custom.writeTo(output.identifier)\
.using("iceberg") \
.tableProperty("format-version", "3") \
.createOrReplace()
``sql tab="SQL 维护"
ALTER TABLEri.tables.main.table.00000002...`
SET TBLPROPERTIES ('format-version' = '3');
```python tab="外部客户端 (PyIceberg)"
catalog.create_table(
"path.table",
schema=schema,
properties={"format-version": "3"}
)
:::callout{theme="neutral"} 虽然您可以将表从 v2 升级到 v3，但无法将 v3 表降级回 v2。 :::