You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by gi...@apache.org on 2026/06/18 22:15:32 UTC
(iceberg-go) branch gh-pages updated: deploy: 97a00beaad781b23d19e7402cddf6239a13f6504
This is an automated email from the ASF dual-hosted git repository.
github-actions[bot] pushed a commit to branch gh-pages
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git
The following commit(s) were added to refs/heads/gh-pages by this push:
new 0e559a9a deploy: 97a00beaad781b23d19e7402cddf6239a13f6504
0e559a9a is described below
commit 0e559a9a9cc870e52ec1310b1807e11534521c4f
Author: zeroshade <ze...@users.noreply.github.com>
AuthorDate: Thu Jun 18 22:15:26 2026 +0000
deploy: 97a00beaad781b23d19e7402cddf6239a13f6504
---
404.html | 2 +-
api.html | 2 +-
cli.html | 2 +-
community.html | 2 +-
contributing.html => concurrent-writes.html | 106 +++++++++++++++++-----------
configuration.html | 2 +-
contributing.html | 2 +-
ecosystem.html | 2 +-
expression-dsl.html | 6 +-
feature-status.html | 6 +-
getting-started.html | 2 +-
glossary.html | 2 +-
how-to-release.html | 2 +-
index.html | 2 +-
install.html | 2 +-
introduction.html | 2 +-
print.html | 82 ++++++++++++++++++++-
releases.html | 2 +-
row-filter-syntax.html | 2 +-
searchindex.js | 2 +-
searchindex.json | 2 +-
verify-release.html | 2 +-
22 files changed, 170 insertions(+), 66 deletions(-)
diff --git a/404.html b/404.html
index 825ebe44..ce764bde 100644
--- a/404.html
+++ b/404.html
@@ -124,7 +124,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/api.html b/api.html
index 8d8eec20..9c4bd591 100644
--- a/api.html
+++ b/api.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/cli.html b/cli.html
index 43867895..e195949d 100644
--- a/cli.html
+++ b/cli.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/community.html b/community.html
index cdf70fcd..dc41292b 100644
--- a/community.html
+++ b/community.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/contributing.html b/concurrent-writes.html
similarity index 70%
copy from contributing.html
copy to concurrent-writes.html
index 985d919f..de1d3730 100644
--- a/contributing.html
+++ b/concurrent-writes.html
@@ -3,7 +3,7 @@
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
- <title>Contributing - Iceberg Golang</title>
+ <title>Concurrent Writes - Iceberg Golang</title>
<!-- Custom HTML head -->
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
@@ -185,7 +185,7 @@
<a href="https://github.com/apache/iceberg-go" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
- <a href="https://github.com/apache/iceberg-go/edit/main/website/src/contributing.md" title="Suggest an edit" aria-label="Suggest an edit">
+ <a href="https://github.com/apache/iceberg-go/edit/main/website/src/concurrent-writes.md" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
@@ -232,54 +232,78 @@
~ specific language governing permissions and limitations
~ under the License.
-->
-<h1 id="contributing"><a class="header" href="#contributing">Contributing</a></h1>
-<h2 id="get-in-touch"><a class="header" href="#get-in-touch">Get in Touch</a></h2>
+<h1 id="concurrent-writes"><a class="header" href="#concurrent-writes">Concurrent Writes</a></h1>
+<p>When multiple writers commit to the same table, iceberg-go uses optimistic
+concurrency control: every commit is validated against the table state it was
+built on. If another writer committed first, the commit is rejected rather than
+silently clobbering their snapshot.</p>
+<h2 id="conflict-detection"><a class="header" href="#conflict-detection">Conflict detection</a></h2>
+<p>Each producer (<code>Append</code>, <code>Overwrite</code>, <code>Delete</code>, <code>RowDelta</code>, <code>RewriteDataFiles</code>)
+runs a set of validators before the commit lands. They check that the files the
+operation assumed (added, deleted, or filtered) still match the current table
+state. A failed validation surfaces as one of:</p>
<ul>
-<li><a href="https://iceberg.apache.org/community/">Iceberg community</a></li>
-<li><a href="https://apache-iceberg.slack.com/archives/C05J3MJ42BD">Iceberg-Go Slack</a></li>
+<li><code>table.ErrCommitFailed</code> — the base snapshot moved on; the commit can be
+retried after refreshing (see below).</li>
+<li><code>table.ErrCommitDiverged</code> — terminal. The base snapshot is no longer on the
+branch at all, so a retry cannot reconcile the change.</li>
</ul>
-<h2 id="picking-up-issues"><a class="header" href="#picking-up-issues">Picking Up Issues</a></h2>
-<p>Before starting work on an issue:</p>
-<ol>
-<li><strong>Check for existing PRs.</strong> Search the <a href="https://github.com/apache/iceberg-go/pulls">open pull requests</a> to make sure nobody is already working on it.</li>
-<li><strong>Claim the issue.</strong> Leave a comment on the issue (e.g., "I'd like to work on this") and wait for a maintainer to acknowledge before writing code.</li>
-<li><strong>One at a time for new contributors.</strong> If you haven't had a PR merged into iceberg-go yet, please work on one issue at a time. Get it reviewed, address feedback, get it merged — then pick up the next one. This helps us give your work the attention it deserves and avoids wasted effort from overlapping contributions.</li>
-</ol>
-<p>If two PRs land for the same issue, we will generally keep the one from the contributor who claimed it first.</p>
-<h2 id="submitting-a-pull-request"><a class="header" href="#submitting-a-pull-request">Submitting a Pull Request</a></h2>
-<ul>
-<li>Reference the issue number in your PR description (e.g., "Fixes #123").</li>
-<li>Keep PRs focused — one issue per PR.</li>
-<li>Run <code>go test ./...</code>, <code>gofmt</code>, and <code>golangci-lint run</code> before pushing. CI runs all of these too, but catching issues locally saves a round-trip.</li>
-<li>All commits must have a <code>Signed-off-by</code> line (<a href="https://developercertificate.org/">DCO</a>).</li>
-</ul>
-<h2 id="code-review"><a class="header" href="#code-review">Code Review</a></h2>
-<ul>
-<li>Maintainers may request changes. This is normal — it doesn't mean the PR is bad, it means we want to get it right.</li>
-<li>Respond to review comments by pushing new commits (don't force-push over reviewed code).</li>
-<li>If your PR has been waiting for review for more than a few days, ping on <a href="https://apache-iceberg.slack.com/archives/C05J3MJ42BD">Slack</a>.</li>
-</ul>
-<h2 id="development-setup"><a class="header" href="#development-setup">Development Setup</a></h2>
-<pre><code class="language-bash">git clone https://github.com/apache/iceberg-go.git
-cd iceberg-go
-go build ./...
-go test ./...
+<pre><code class="language-go">import (
+ "context"
+ "errors"
+
+ "github.com/apache/iceberg-go/table"
+)
+
+_, err := txn.Commit(context.Background())
+switch {
+case errors.Is(err, table.ErrCommitDiverged):
+ // unrecoverable: rebuild the operation from the latest table
+case errors.Is(err, table.ErrCommitFailed):
+ // retriable: refresh and try again (the retry loop does this for you)
+}
</code></pre>
-<h3 id="integration-tests"><a class="header" href="#integration-tests">Integration Tests</a></h3>
-<p>Integration tests require Docker and are gated behind a build tag:</p>
-<pre><code class="language-bash">docker compose -f internal/recipe/docker-compose.yml up -d rest minio mc --wait
-go test -tags integration ./...
+<h2 id="isolation-levels"><a class="header" href="#isolation-levels">Isolation levels</a></h2>
+<p>Delete and update operations are validated under an isolation level, set per
+operation through table properties:</p>
+<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Property</th><th style="text-align: left">Default</th><th style="text-align: left">Values</th></tr></thead><tbody>
+<tr><td style="text-align: left"><code>write.delete.isolation-level</code></td><td style="text-align: left"><code>serializable</code></td><td style="text-align: left"><code>serializable</code>, <code>snapshot</code></td></tr>
+<tr><td style="text-align: left"><code>write.update.isolation-level</code></td><td style="text-align: left"><code>serializable</code></td><td style="text-align: left"><code>serializable</code>, <code>snapshot</code></td></tr>
+</tbody></table>
+</div>
+<p><code>serializable</code> rejects the commit if <em>any</em> concurrent snapshot added data
+matching the operation's filter. <code>snapshot</code> is more permissive — it only
+rejects when concurrent deletes touch the same files.</p>
+<h2 id="automatic-retry"><a class="header" href="#automatic-retry">Automatic retry</a></h2>
+<p>iceberg-go can refresh the table and replay the operation against the latest
+snapshot between attempts. On each retry the table metadata is reloaded, the
+producer's validators re-run against the fresh snapshot, and the commit is
+re-submitted only if it is still valid.</p>
+<p>Retry is <strong>off by default</strong> (<code>commit.retry.num-retries</code> is <code>0</code>). Opt in by
+setting the retry properties — see <a href="./configuration.html#manifest-and-commit">Manifest and commit</a>
+in the configuration reference for the full list:</p>
+<pre><code class="language-go">// Opt in to retries (e.g. 4 attempts after the first) for a contended table.
+_, err := cat.CreateTable(ctx, ident, schema,
+ catalog.WithProperties(iceberg.Properties{
+ "commit.retry.num-retries": "4",
+ }),
+)
</code></pre>
+<blockquote>
+<p><strong>Catalog support:</strong> retry currently engages on the REST catalog, which wraps
+commit conflicts as <code>ErrCommitFailed</code>. The Glue, SQL, and Hive catalogs do
+not yet wrap their conflict errors, so the retry loop will not fire on them.</p>
+</blockquote>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
- <a rel="prev" href="feature-status.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+ <a rel="prev" href="expression-dsl.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
- <a rel="next prefetch" href="community.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+ <a rel="next prefetch" href="feature-status.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
@@ -289,11 +313,11 @@ go test -tags integration ./...
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
- <a rel="prev" href="feature-status.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+ <a rel="prev" href="expression-dsl.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
- <a rel="next prefetch" href="community.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+ <a rel="next prefetch" href="feature-status.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
diff --git a/configuration.html b/configuration.html
index c55f527b..fe2e791b 100644
--- a/configuration.html
+++ b/configuration.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html" class="active">Configuration</a></li><li class="chapter-item expa [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html" class="active">Configuration</a></li><li class="chapter-item expa [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/contributing.html b/contributing.html
index 985d919f..9b7ee006 100644
--- a/contributing.html
+++ b/contributing.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/ecosystem.html b/ecosystem.html
index 7f977306..9d61dd6b 100644
--- a/ecosystem.html
+++ b/ecosystem.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/expression-dsl.html b/expression-dsl.html
index 88139cd0..3a731223 100644
--- a/expression-dsl.html
+++ b/expression-dsl.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
@@ -319,7 +319,7 @@ inverted := expr.Negate() // equivalent to NotEqualTo(...)
<i class="fa fa-angle-left"></i>
</a>
- <a rel="next prefetch" href="feature-status.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+ <a rel="next prefetch" href="concurrent-writes.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
@@ -333,7 +333,7 @@ inverted := expr.Negate() // equivalent to NotEqualTo(...)
<i class="fa fa-angle-left"></i>
</a>
- <a rel="next prefetch" href="feature-status.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+ <a rel="next prefetch" href="concurrent-writes.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
diff --git a/feature-status.html b/feature-status.html
index ee5c5dc2..03006d07 100644
--- a/feature-status.html
+++ b/feature-status.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
@@ -332,7 +332,7 @@
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
- <a rel="prev" href="expression-dsl.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+ <a rel="prev" href="concurrent-writes.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
@@ -346,7 +346,7 @@
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
- <a rel="prev" href="expression-dsl.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
+ <a rel="prev" href="concurrent-writes.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
diff --git a/getting-started.html b/getting-started.html
index 3e8897ad..5bc40d19 100644
--- a/getting-started.html
+++ b/getting-started.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html" class="active">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html" class="active">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/glossary.html b/glossary.html
index 6483c927..f73d5503 100644
--- a/glossary.html
+++ b/glossary.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/how-to-release.html b/how-to-release.html
index e8144960..82e5c483 100644
--- a/how-to-release.html
+++ b/how-to-release.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/index.html b/index.html
index c25a13ab..b1d5de08 100644
--- a/index.html
+++ b/index.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html" class="active">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html" class="active">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/install.html b/install.html
index d107ae4a..37a0894c 100644
--- a/install.html
+++ b/install.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html" class="active">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html" class="active">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/introduction.html b/introduction.html
index c25a13ab..b1d5de08 100644
--- a/introduction.html
+++ b/introduction.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html" class="active">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html" class="active">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expa [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/print.html b/print.html
index 13dc4504..96f16fc3 100644
--- a/print.html
+++ b/print.html
@@ -124,7 +124,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
@@ -1680,6 +1680,86 @@ inverted := expr.Negate() // equivalent to NotEqualTo(...)
~ specific language governing permissions and limitations
~ under the License.
-->
+<h1 id="concurrent-writes"><a class="header" href="#concurrent-writes">Concurrent Writes</a></h1>
+<p>When multiple writers commit to the same table, iceberg-go uses optimistic
+concurrency control: every commit is validated against the table state it was
+built on. If another writer committed first, the commit is rejected rather than
+silently clobbering their snapshot.</p>
+<h2 id="conflict-detection"><a class="header" href="#conflict-detection">Conflict detection</a></h2>
+<p>Each producer (<code>Append</code>, <code>Overwrite</code>, <code>Delete</code>, <code>RowDelta</code>, <code>RewriteDataFiles</code>)
+runs a set of validators before the commit lands. They check that the files the
+operation assumed (added, deleted, or filtered) still match the current table
+state. A failed validation surfaces as one of:</p>
+<ul>
+<li><code>table.ErrCommitFailed</code> — the base snapshot moved on; the commit can be
+retried after refreshing (see below).</li>
+<li><code>table.ErrCommitDiverged</code> — terminal. The base snapshot is no longer on the
+branch at all, so a retry cannot reconcile the change.</li>
+</ul>
+<pre><code class="language-go">import (
+ "context"
+ "errors"
+
+ "github.com/apache/iceberg-go/table"
+)
+
+_, err := txn.Commit(context.Background())
+switch {
+case errors.Is(err, table.ErrCommitDiverged):
+ // unrecoverable: rebuild the operation from the latest table
+case errors.Is(err, table.ErrCommitFailed):
+ // retriable: refresh and try again (the retry loop does this for you)
+}
+</code></pre>
+<h2 id="isolation-levels"><a class="header" href="#isolation-levels">Isolation levels</a></h2>
+<p>Delete and update operations are validated under an isolation level, set per
+operation through table properties:</p>
+<div class="table-wrapper"><table><thead><tr><th style="text-align: left">Property</th><th style="text-align: left">Default</th><th style="text-align: left">Values</th></tr></thead><tbody>
+<tr><td style="text-align: left"><code>write.delete.isolation-level</code></td><td style="text-align: left"><code>serializable</code></td><td style="text-align: left"><code>serializable</code>, <code>snapshot</code></td></tr>
+<tr><td style="text-align: left"><code>write.update.isolation-level</code></td><td style="text-align: left"><code>serializable</code></td><td style="text-align: left"><code>serializable</code>, <code>snapshot</code></td></tr>
+</tbody></table>
+</div>
+<p><code>serializable</code> rejects the commit if <em>any</em> concurrent snapshot added data
+matching the operation's filter. <code>snapshot</code> is more permissive — it only
+rejects when concurrent deletes touch the same files.</p>
+<h2 id="automatic-retry"><a class="header" href="#automatic-retry">Automatic retry</a></h2>
+<p>iceberg-go can refresh the table and replay the operation against the latest
+snapshot between attempts. On each retry the table metadata is reloaded, the
+producer's validators re-run against the fresh snapshot, and the commit is
+re-submitted only if it is still valid.</p>
+<p>Retry is <strong>off by default</strong> (<code>commit.retry.num-retries</code> is <code>0</code>). Opt in by
+setting the retry properties — see <a href="./configuration.html#manifest-and-commit">Manifest and commit</a>
+in the configuration reference for the full list:</p>
+<pre><code class="language-go">// Opt in to retries (e.g. 4 attempts after the first) for a contended table.
+_, err := cat.CreateTable(ctx, ident, schema,
+ catalog.WithProperties(iceberg.Properties{
+ "commit.retry.num-retries": "4",
+ }),
+)
+</code></pre>
+<blockquote>
+<p><strong>Catalog support:</strong> retry currently engages on the REST catalog, which wraps
+commit conflicts as <code>ErrCommitFailed</code>. The Glue, SQL, and Hive catalogs do
+not yet wrap their conflict errors, so the retry loop will not fire on them.</p>
+</blockquote>
+<div style="break-before: page; page-break-before: always;"></div><!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+-->
<h1 id="feature-status"><a class="header" href="#feature-status">Feature Status</a></h1>
<p>This page tracks what Apache Iceberg Go currently supports. The matrix is kept in sync with the project <a href="https://github.com/apache/iceberg-go/blob/main/README.md"><code>README.md</code></a>; if you spot a discrepancy, file an issue.</p>
<h2 id="spec-format-version-coverage"><a class="header" href="#spec-format-version-coverage">Spec format version coverage</a></h2>
diff --git a/releases.html b/releases.html
index 496d0020..df25edfb 100644
--- a/releases.html
+++ b/releases.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/row-filter-syntax.html b/row-filter-syntax.html
index a941f901..7489a294 100644
--- a/row-filter-syntax.html
+++ b/row-filter-syntax.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
diff --git a/searchindex.js b/searchindex.js
index b8b01226..c0534e89 100644
--- a/searchindex.js
+++ b/searchindex.js
@@ -1 +1 @@
-Object.assign(window.search, {"doc_urls":["introduction.html#iceberg-go","introduction.html#where-to-start","introduction.html#what-works-today","introduction.html#beyond-go","introduction.html#help-and-contribution","install.html#install","install.html#requirements","install.html#installation","getting-started.html#getting-started","getting-started.html#1-install","getting-started.html#2-open-a-local-catalog","getting-started.html#3-create-a-namespace-and-a-table","getting-started.html# [...]
\ No newline at end of file
+Object.assign(window.search, {"doc_urls":["introduction.html#iceberg-go","introduction.html#where-to-start","introduction.html#what-works-today","introduction.html#beyond-go","introduction.html#help-and-contribution","install.html#install","install.html#requirements","install.html#installation","getting-started.html#getting-started","getting-started.html#1-install","getting-started.html#2-open-a-local-catalog","getting-started.html#3-create-a-namespace-and-a-table","getting-started.html# [...]
\ No newline at end of file
diff --git a/searchindex.json b/searchindex.json
index 6ff74e8e..fe87e186 100644
--- a/searchindex.json
+++ b/searchindex.json
@@ -1 +1 @@
-{"doc_urls":["introduction.html#iceberg-go","introduction.html#where-to-start","introduction.html#what-works-today","introduction.html#beyond-go","introduction.html#help-and-contribution","install.html#install","install.html#requirements","install.html#installation","getting-started.html#getting-started","getting-started.html#1-install","getting-started.html#2-open-a-local-catalog","getting-started.html#3-create-a-namespace-and-a-table","getting-started.html#4-write-some-arrow-data","get [...]
\ No newline at end of file
+{"doc_urls":["introduction.html#iceberg-go","introduction.html#where-to-start","introduction.html#what-works-today","introduction.html#beyond-go","introduction.html#help-and-contribution","install.html#install","install.html#requirements","install.html#installation","getting-started.html#getting-started","getting-started.html#1-install","getting-started.html#2-open-a-local-catalog","getting-started.html#3-create-a-namespace-and-a-table","getting-started.html#4-write-some-arrow-data","get [...]
\ No newline at end of file
diff --git a/verify-release.html b/verify-release.html
index a3316707..b7fd0a2f 100644
--- a/verify-release.html
+++ b/verify-release.html
@@ -123,7 +123,7 @@
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
- <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
+ <ol class="chapter"><li class="chapter-item expanded "><a href="introduction.html">Introduction</a></li><li class="chapter-item expanded affix "><li class="part-title">User Guide</li><li class="chapter-item expanded "><a href="install.html">Install</a></li><li class="chapter-item expanded "><a href="getting-started.html">Getting Started</a></li><li class="chapter-item expanded "><a href="configuration.html">Configuration</a></li><li class="chapter-item expanded "><a href= [...]
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>