This is an automated email from the ASF dual-hosted git repository.
mchades pushed a commit to branch branch-1.3
in repository https://gitbox.apache.org/repos/asf/gravitino.git
The following commit(s) were added to refs/heads/branch-1.3 by this push:
new 5e178e364c [Cherry-pick to branch-1.3] [#11606] docs: Document Iceberg
client JAR compatibility for Flink and Spark (#11650) (#11657)
5e178e364c is described below
commit 5e178e364cddf9ef04160f1463f95b10fff6e51b
Author: github-actions[bot]
<41898282+github-actions[bot]@users.noreply.github.com>
AuthorDate: Tue Jun 16 10:20:24 2026 +0800
[Cherry-pick to branch-1.3] [#11606] docs: Document Iceberg client JAR
compatibility for Flink and Spark (#11650) (#11657)
**Cherry-pick Information:**
- Original commit: 6c94cab304b72b105392cdcfe5513a133c7b8cb3
- Target branch: `branch-1.3`
- Status: ✅ Clean cherry-pick (no conflicts)
Co-authored-by: MaSai <[email protected]>
Co-authored-by: Qi Yu <[email protected]>
---
docs/flink-connector/flink-catalog-iceberg.md | 21 +++++++++++++--------
docs/lakehouse-iceberg-catalog.md | 9 +++++++++
docs/spark-connector/spark-catalog-iceberg.md | 16 +++++++++++++++-
3 files changed, 37 insertions(+), 9 deletions(-)
diff --git a/docs/flink-connector/flink-catalog-iceberg.md
b/docs/flink-connector/flink-catalog-iceberg.md
index 3c66dc0a38..42b03c7326 100644
--- a/docs/flink-connector/flink-catalog-iceberg.md
+++ b/docs/flink-connector/flink-catalog-iceberg.md
@@ -37,16 +37,21 @@ To enable the Flink connector, you must download the
Iceberg Flink runtime JAR a
### Prerequisites
-Place the following JAR files in the lib directory of your Flink installation:
+Place the Iceberg Flink runtime JAR and the Gravitino Flink connector runtime
JAR in the `lib` directory of your Flink installation.
-- The Iceberg Flink runtime JAR that matches your Flink minor version
-- The Gravitino Flink connector runtime JAR that matches your Flink minor
version
+Flink clients use a different Iceberg version than the Gravitino server
(1.11.0). Use the table below to choose the correct JARs for your Flink version.
-| Flink version | Iceberg runtime artifact | Gravitino runtime artifact |
-|---------------|--------------------------|----------------------------|
-| 1.18 | `iceberg-flink-runtime-1.18-${iceberg-version}.jar` |
`gravitino-flink-connector-runtime-1.18_2.12-${gravitino-version}.jar` |
-| 1.19 | `iceberg-flink-runtime-1.19-${iceberg-version}.jar` |
`gravitino-flink-connector-runtime-1.19_2.12-${gravitino-version}.jar` |
-| 1.20 | `iceberg-flink-runtime-1.20-${iceberg-version}.jar` |
`gravitino-flink-connector-runtime-1.20_2.12-${gravitino-version}.jar` |
+| Flink version | Scala | Iceberg version | Iceberg client runtime artifact
| Gravitino connector runtime artifact |
+|---------------|-------|-----------------|----------------------------------------|------------------------------------------------------------------------|
+| 1.18 | 2.12 | 1.9.2 |
`iceberg-flink-runtime-1.18-1.9.2.jar` |
`gravitino-flink-connector-runtime-1.18_2.12-${gravitino-version}.jar` |
+| 1.19 | 2.12 | 1.10.2 |
`iceberg-flink-runtime-1.19-1.10.2.jar` |
`gravitino-flink-connector-runtime-1.19_2.12-${gravitino-version}.jar` |
+| 1.20 | 2.12 | 1.11.0 |
`iceberg-flink-runtime-1.20-1.11.0.jar` |
`gravitino-flink-connector-runtime-1.20_2.12-${gravitino-version}.jar` |
+
+Replace `${gravitino-version}` with your Gravitino release version.
+
+:::caution
+Use only the JARs from the matching table row. Mixing Iceberg JARs from
different versions on the client classpath is not compatible and may cause
runtime errors.
+:::
## SQL Example
diff --git a/docs/lakehouse-iceberg-catalog.md
b/docs/lakehouse-iceberg-catalog.md
index 09d1332fd9..93981824f9 100644
--- a/docs/lakehouse-iceberg-catalog.md
+++ b/docs/lakehouse-iceberg-catalog.md
@@ -21,6 +21,15 @@ Apache Gravitino provides the ability to manage Apache
Iceberg metadata.
Builds with Apache Iceberg `1.11.0`. The Apache Iceberg table format version
is `2` by default.
:::
+Flink and Spark clients may use a different Iceberg version than the server.
+
+- [Flink Iceberg catalog](flink-connector/flink-catalog-iceberg.md) — client
JAR requirements
+- [Spark Iceberg catalog](spark-connector/spark-catalog-iceberg.md) — client
JAR requirements
+
+:::caution
+Mixing Iceberg JARs from different versions on the client classpath is not
compatible and may cause runtime errors.
+:::
+
## Catalog
### Catalog Capabilities
diff --git a/docs/spark-connector/spark-catalog-iceberg.md
b/docs/spark-connector/spark-catalog-iceberg.md
index 7f5ef7bdb2..56ec9e0b90 100644
--- a/docs/spark-connector/spark-catalog-iceberg.md
+++ b/docs/spark-connector/spark-catalog-iceberg.md
@@ -12,7 +12,21 @@ The Apache Gravitino Spark connector offers the capability
to read and write Ice
## Preparation
1. Set `spark.sql.gravitino.enableIcebergSupport` to `true` in Spark
configuration.
-2. Download Iceberg Spark runtime jar to Spark classpath.
+2. Download the Iceberg Spark runtime JAR and the Gravitino Spark connector
runtime JAR that match your Spark minor version and Scala version, and place
them in the Spark classpath.
+
+Spark clients use a different Iceberg version than the Gravitino server
(1.11.0). Use the table below to choose the correct JARs for your Spark version.
+
+| Spark version | Scala | Iceberg version | Iceberg client runtime
artifact | Gravitino connector runtime artifact
|
+|---------------|----------------|-----------------|---------------------------------------------------------|-----------------------------------------------------------------------------------|
+| 3.3 | 2.12 or 2.13 | 1.8.1 |
`iceberg-spark-runtime-3.3_${scala-version}-1.8.1.jar` |
`gravitino-spark-connector-runtime-3.3_${scala-version}-${gravitino-version}.jar`
|
+| 3.4 | 2.12 or 2.13 | 1.11.0 |
`iceberg-spark-runtime-3.4_${scala-version}-1.11.0.jar` |
`gravitino-spark-connector-runtime-3.4_${scala-version}-${gravitino-version}.jar`
|
+| 3.5 | 2.12 or 2.13 | 1.11.0 |
`iceberg-spark-runtime-3.5_${scala-version}-1.11.0.jar` |
`gravitino-spark-connector-runtime-3.5_${scala-version}-${gravitino-version}.jar`
|
+
+Replace `${scala-version}` with `2.12` or `2.13`, and `${gravitino-version}`
with your Gravitino release version.
+
+:::caution
+Use only the JARs from the matching table row. Mixing Iceberg JARs from
different versions on the client classpath is not compatible and may cause
runtime errors.
+:::
## Capabilities
