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 a2df5901e deploy: 21e85b611b13625a340cfe29f0344fbd1cc0d54f
a2df5901e is described below
commit a2df5901e4310907cc3a6a2c1a625b900e0c6d99
Author: laskoviymishka <[email protected]>
AuthorDate: Wed Sep 23 19:29:43 2026 +0000
deploy: 21e85b611b13625a340cfe29f0344fbd1cc0d54f
---
404.html | 2 +-
api.html | 8 +-
cli.html | 2 +-
community.html | 2 +-
concurrent-writes.html | 2 +-
configuration.html | 2 +-
contributing.html | 2 +-
ecosystem.html | 2 +-
expression-dsl.html | 4 +-
feature-status.html | 5 +-
getting-started.html | 2 +-
glossary.html | 2 +-
how-to-release.html | 2 +-
index.html | 2 +-
install.html | 2 +-
introduction.html | 2 +-
metrics-reporting.html | 2 +-
print.html | 119 ++++++++++++++++++++++++++-
releases.html | 2 +-
row-filter-syntax.html | 20 ++++-
searchindex.js | 2 +-
searchindex.json | 2 +-
concurrent-writes.html => variant.html | 142 ++++++++++++++++++---------------
verify-release.html | 2 +-
24 files changed, 240 insertions(+), 94 deletions(-)
diff --git a/404.html b/404.html
index 514be9102..8cd7b778f 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 9e30c11bb..231fe0c6a 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>
@@ -667,7 +667,7 @@ v.Properties() // iceberg.Properties
<tr><td><code>struct<...></code></td><td><code>arrow.StructOf(...)</code></td></tr>
<tr><td><code>list<E></code></td><td><code>arrow.ListOf(E)</code> (or
<code>LargeListOf</code> if <code>useLargeTypes</code>)</td></tr>
<tr><td><code>map<K, V></code></td><td><code>arrow.MapOf(K,
V)</code></td></tr>
-<tr><td><code>variant</code></td><td><code>arrow.ExtensionType</code> for
Variant</td></tr>
+<tr><td><code>variant</code></td><td><code>arrow.ExtensionType</code> for
Variant (see <a href="./variant.html">Variant Type</a>)</td></tr>
</tbody></table>
</div>
<p>Helpers in <a
href="https://github.com/apache/iceberg-go/blob/main/table/arrow_utils.go";><code>table/arrow_utils.go</code></a>:</p>
@@ -685,7 +685,7 @@ v.Properties() // iceberg.Properties
<i class="fa fa-angle-left"></i>
</a>
- <a rel="next prefetch"
href="row-filter-syntax.html" class="mobile-nav-chapters next" title="Next
chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+ <a rel="next prefetch" href="variant.html"
class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter"
aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
@@ -699,7 +699,7 @@ v.Properties() // iceberg.Properties
<i class="fa fa-angle-left"></i>
</a>
- <a rel="next prefetch" href="row-filter-syntax.html"
class="nav-chapters next" title="Next chapter" aria-label="Next chapter"
aria-keyshortcuts="Right">
+ <a rel="next prefetch" href="variant.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/cli.html b/cli.html
index 0578ba705..1980f97ba 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 2da22bd0f..8a8782dfa 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/concurrent-writes.html b/concurrent-writes.html
index dbe499a4f..4be21e7e5 100644
--- a/concurrent-writes.html
+++ b/concurrent-writes.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/configuration.html b/configuration.html
index 26a1a9b1e..e26ad1d36 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 cbe2f855f..02bf397dc 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 0e2c80463..497394686 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 5fbdbb8be..b79f50e99 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>
@@ -260,6 +260,7 @@ iceberg.AlwaysFalse{}
<ul>
<li><code>Reference("column_name")</code> - an unbound term that
names a column (<code>exprs.go:373</code>). Typing happens at bind time, when
the expression is matched against a schema. This is what you almost always
want.</li>
<li><code>BoundReference</code> - the resolved form, produced by
<code>Reference.Bind(schema, caseSensitive)</code> (<code>exprs.go:389</code>).
You only encounter these when writing custom expression visitors.</li>
+<li><code>Extract(ref, path, typ)</code> - a variant sub-path term that
navigates a member-selector path (<code>$.a.b</code> or
<code>$['a']['b']</code>; no array indexing or wildcards) into a
<code>variant</code> column and casts the leaf to <code>typ</code>
(<code>variant_extract.go</code>). Use it inside any predicate builder to
filter on a field within a variant. See <a
href="./row-filter-syntax.html#variant-extraction">Row Filter Syntax</a>.</li>
</ul>
<p>The interfaces are:</p>
<pre><code class="language-go">type Term interface { ... }
// shared marker
@@ -306,6 +307,7 @@ inverted := expr.Negate() // equivalent to NotEqualTo(...)
<tr><td>Filter a scan or row-level delete</td><td>Convenience builders +
<code>NewAnd</code>/<code>NewOr</code>/<code>NewNot</code></td></tr>
<tr><td>Combine many clauses dynamically</td><td>Start from
<code>AlwaysTrue{}</code> (for AND) or <code>AlwaysFalse{}</code> (for OR),
fold with <code>NewAnd</code>/<code>NewOr</code></td></tr>
<tr><td>Construct a predicate whose operator is chosen at
runtime</td><td><code>UnaryPredicate(op, term)</code>,
<code>LiteralPredicate(op, term, lit)</code>, <code>SetPredicate(op, term,
lits)</code></td></tr>
+<tr><td>Filter on a field inside a variant column</td><td><code>Extract(ref,
path, typ)</code> inside a predicate builder</td></tr>
<tr><td>Walk an expression tree</td><td>A custom
<code>BooleanExprVisitor</code> from <code>visitors.go</code></td></tr>
</tbody></table>
</div>
diff --git a/feature-status.html b/feature-status.html
index 1e914d072..366c3261c 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>
@@ -256,7 +256,8 @@
<tr><td>Row lineage (<code>_row_id</code>,
<code>_last_updated_sequence_number</code>)</td><td>Supported</td></tr>
<tr><td>Encryption keys in metadata</td><td>Supported</td></tr>
<tr><td>Variant type, non-shredded</td><td>Supported (PR <a
href="https://github.com/apache/iceberg-go/pull/932";>#932</a>; umbrella <a
href="https://github.com/apache/iceberg-go/issues/929";>#929</a>)</td></tr>
-<tr><td>Variant type, shredded reader / writer</td><td>In progress (<a
href="https://github.com/apache/iceberg-go/issues/986";>#986</a>, <a
href="https://github.com/apache/iceberg-go/issues/987";>#987</a>)</td></tr>
+<tr><td>Variant type, shredded reader / writer</td><td>Supported (reader <a
href="https://github.com/apache/iceberg-go/pull/1238";>#1238</a>, writer <a
href="https://github.com/apache/iceberg-go/pull/1351";>#1351</a>)</td></tr>
+<tr><td>Variant predicate pushdown / field extract</td><td>Supported (PR <a
href="https://github.com/apache/iceberg-go/pull/1607";>#1607</a>)</td></tr>
<tr><td>Deletion vectors, read</td><td>Supported</td></tr>
<tr><td>Deletion vectors, write (unpartitioned)</td><td>Supported</td></tr>
<tr><td>Deletion vectors, write (partitioned)</td><td>In progress (<a
href="https://github.com/apache/iceberg-go/issues/1135";>#1135</a>, PR <a
href="https://github.com/apache/iceberg-go/pull/1151";>#1151</a>)</td></tr>
diff --git a/getting-started.html b/getting-started.html
index ed7a17771..03e9ea596 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 e674c85ab..c2142899c 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 113200df8..11aae6593 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 182a1ab39..5f2b44d43 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 5bff2a81b..d4bf2e26f 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 182a1ab39..5f2b44d43 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/metrics-reporting.html b/metrics-reporting.html
index 008383dc1..66dbb15a8 100644
--- a/metrics-reporting.html
+++ b/metrics-reporting.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/print.html b/print.html
index f5ad990a2..31511838b 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>
@@ -1546,7 +1546,7 @@ v.Properties() // iceberg.Properties
<tr><td><code>struct<...></code></td><td><code>arrow.StructOf(...)</code></td></tr>
<tr><td><code>list<E></code></td><td><code>arrow.ListOf(E)</code> (or
<code>LargeListOf</code> if <code>useLargeTypes</code>)</td></tr>
<tr><td><code>map<K, V></code></td><td><code>arrow.MapOf(K,
V)</code></td></tr>
-<tr><td><code>variant</code></td><td><code>arrow.ExtensionType</code> for
Variant</td></tr>
+<tr><td><code>variant</code></td><td><code>arrow.ExtensionType</code> for
Variant (see <a href="./variant.html">Variant Type</a>)</td></tr>
</tbody></table>
</div>
<p>Helpers in <a
href="https://github.com/apache/iceberg-go/blob/main/table/arrow_utils.go";><code>table/arrow_utils.go</code></a>:</p>
@@ -1573,6 +1573,102 @@ v.Properties() // iceberg.Properties
~ specific language governing permissions and limitations
~ under the License.
-->
+<h1 id="variant-type"><a class="header" href="#variant-type">Variant
Type</a></h1>
+<p><code>variant</code> is the Iceberg v3 semi-structured type: a single
self-describing column
+that holds arbitrary JSON-like values (objects, arrays, and scalars) without a
+fixed schema. iceberg-go supports both non-shredded and shredded variants, and
can
+push predicates down into individual variant fields.</p>
+<h2 id="reading-and-writing"><a class="header"
href="#reading-and-writing">Reading and writing</a></h2>
+<p>A variant column is declared with <code>iceberg.VariantType{}</code> in the
table schema and
+maps to the Arrow <code>variant</code> extension type (see <a
href="./api.html">API</a>). Non-shredded
+variant values need no extra configuration: write an Arrow record whose variant
+column uses the extension type, and read it back the same way.</p>
+<p>Build the column with a variant builder and write it like any other Arrow
column
+(the table must be format version 3):</p>
+<pre><code class="language-go">import (
+ "fmt"
+
+ "github.com/apache/arrow-go/v18/arrow"
+ "github.com/apache/arrow-go/v18/arrow/array"
+ "github.com/apache/arrow-go/v18/arrow/extensions"
+ "github.com/apache/arrow-go/v18/arrow/memory"
+ "github.com/apache/arrow-go/v18/parquet/variant"
+ "github.com/apache/iceberg-go"
+ "github.com/apache/iceberg-go/table"
+)
+
+// tbl was created with table.PropertyFormatVersion = "3" and this
schema.
+schema := iceberg.NewSchema(0,
+ iceberg.NestedField{ID: 1, Name: "payload", Type:
iceberg.VariantType{}},
+)
+arrowSchema, _ := table.SchemaToArrowSchema(schema, nil, true, false)
+
+bldr := extensions.NewVariantBuilder(memory.DefaultAllocator,
extensions.NewDefaultVariantType())
+defer bldr.Release()
+
+var vb variant.Builder
+_ = vb.Append(map[string]any{"x": int64(320), "target":
"button-submit"})
+val, _ := vb.Build()
+bldr.Append(val)
+
+col := bldr.NewArray()
+defer col.Release()
+rec := array.NewRecordBatch(arrowSchema, []arrow.Array{col}, 1)
+defer rec.Release()
+
+tx := tbl.NewTransaction()
+arrTable := array.NewTableFromRecords(arrowSchema, []arrow.Record{rec})
+defer arrTable.Release()
+_ = tx.AppendTable(ctx, arrTable, 1024, nil)
+tbl, _ = tx.Commit(ctx)
+</code></pre>
+<p>A normal scan reads it back; the variant column comes back as an
<code>*extensions.VariantArray</code>:</p>
+<pre><code class="language-go">result, _ := tbl.Scan().ToArrowTable(ctx)
+defer result.Release()
+
+variants := result.Column(0).Data().Chunk(0).(*extensions.VariantArray)
+v, _ := variants.Value(0)
+fmt.Println(v.Value()) // variant.ObjectValue for the object above
+</code></pre>
+<h2 id="shredding"><a class="header" href="#shredding">Shredding</a></h2>
+<p>Shredding stores the fields of a variant as typed Parquet sub-columns
instead of a
+single opaque blob. This lets scans read and filter a field as a native column
+rather than decoding every value. Shredding is opt-in and configured with two
write
+properties (see <a
href="./configuration.html#parquet-writer">Configuration</a>):</p>
+<ul>
+<li><code>write.parquet.shred-variants</code> - enable shredding of top-level
variant columns
+(default <code>false</code>).</li>
+<li><code>write.parquet.variant-inference-buffer-size</code> - rows buffered
per file to infer
+the shredding schema (default <code>100</code>).</li>
+</ul>
+<p>The reader accepts both shredded and non-shredded data; no read-side
+configuration is required.</p>
+<h2 id="filtering-on-variant-fields"><a class="header"
href="#filtering-on-variant-fields">Filtering on variant fields</a></h2>
+<p>Filter on a field inside a variant with <code>iceberg.Extract</code>, which
plugs into the
+usual predicate builders. See <a
href="./row-filter-syntax.html#variant-extraction">Row Filter Syntax</a>
+for usage, supported target types, and caveats.</p>
+<h2 id="constraints"><a class="header" href="#constraints">Constraints</a></h2>
+<ul>
+<li>A variant column cannot be a partition source or an identity-transform
source.</li>
+</ul>
+<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="row-filter-syntax"><a class="header" href="#row-filter-syntax">Row
Filter Syntax</a></h1>
<p>Row filters drive predicate pushdown during scans, partition pruning, and
row-level deletes. The DSL lives in the root <code>iceberg</code> package - all
you need is the import:</p>
<pre><code class="language-go">import "github.com/apache/iceberg-go"
@@ -1615,6 +1711,20 @@ iceberg.NotNaN(iceberg.Reference("ratio"))
iceberg.NotStartsWith(iceberg.Reference("name"), "tmp_")
</code></pre>
<p>Operators <code>OpStartsWith</code> and <code>OpNotStartsWith</code>
(<code>exprs.go:53-54</code>). The value must be a <code>string</code>.</p>
+<h2 id="variant-extraction"><a class="header"
href="#variant-extraction">Variant extraction</a></h2>
+<p><code>iceberg.Extract(ref, path, typ)</code> builds a term that navigates a
member-selector path into a <code>variant</code> column and casts the leaf to
<code>typ</code>. The path uses dot (<code>$.user.age</code>) or quoted-bracket
(<code>$['user']['age']</code>) notation; array indexing
(<code>$.items[0]</code>), wildcards, filters, and recursive descent are
rejected at bind time. It is an <code>UnboundTerm</code>, so it plugs into the
same predicate builders as <code>iceberg.Refer [...]
+<pre><code class="language-go">filter := iceberg.EqualTo(
+ iceberg.Extract(iceberg.Reference("payload"),
"$.user.age", iceberg.PrimitiveTypes.Int64),
+ int64(30),
+)
+</code></pre>
+<p>The referenced column must be a <code>variant</code>, and a target type is
required. Supported target types: <code>bool</code>, <code>int32</code>,
<code>int64</code>, <code>float32</code>, <code>float64</code>,
<code>date</code>, <code>time</code>, <code>timestamp</code>,
<code>timestamptz</code>, <code>timestamp_ns</code>,
<code>timestamptz_ns</code>, <code>string</code>, <code>fixed</code>,
<code>binary</code>, <code>decimal</code>, <code>uuid</code>.</p>
+<p>Caveats:</p>
+<ul>
+<li>Extract predicates prune whole data files by shredded-field bounds
(best-effort, and only for shredded fields), then filter row by row. Row-group
statistics and bloom filters do not apply to them.</li>
+<li>Extract terms are DSL-only (no string row-filter form) and are not
REST-serializable. Under local scan planning (the default) they run as local
residuals; with remote scan planning, a filter containing an Extract term fails
to serialize rather than being silently dropped.</li>
+</ul>
+<p>See <a href="./variant.html">Variant Type</a> for shredding.</p>
<h2 id="constants"><a class="header" href="#constants">Constants</a></h2>
<pre><code class="language-go">iceberg.AlwaysTrue{}
iceberg.AlwaysFalse{}
@@ -1702,6 +1812,7 @@ iceberg.AlwaysFalse{}
<ul>
<li><code>Reference("column_name")</code> - an unbound term that
names a column (<code>exprs.go:373</code>). Typing happens at bind time, when
the expression is matched against a schema. This is what you almost always
want.</li>
<li><code>BoundReference</code> - the resolved form, produced by
<code>Reference.Bind(schema, caseSensitive)</code> (<code>exprs.go:389</code>).
You only encounter these when writing custom expression visitors.</li>
+<li><code>Extract(ref, path, typ)</code> - a variant sub-path term that
navigates a member-selector path (<code>$.a.b</code> or
<code>$['a']['b']</code>; no array indexing or wildcards) into a
<code>variant</code> column and casts the leaf to <code>typ</code>
(<code>variant_extract.go</code>). Use it inside any predicate builder to
filter on a field within a variant. See <a
href="./row-filter-syntax.html#variant-extraction">Row Filter Syntax</a>.</li>
</ul>
<p>The interfaces are:</p>
<pre><code class="language-go">type Term interface { ... }
// shared marker
@@ -1748,6 +1859,7 @@ inverted := expr.Negate() // equivalent to
NotEqualTo(...)
<tr><td>Filter a scan or row-level delete</td><td>Convenience builders +
<code>NewAnd</code>/<code>NewOr</code>/<code>NewNot</code></td></tr>
<tr><td>Combine many clauses dynamically</td><td>Start from
<code>AlwaysTrue{}</code> (for AND) or <code>AlwaysFalse{}</code> (for OR),
fold with <code>NewAnd</code>/<code>NewOr</code></td></tr>
<tr><td>Construct a predicate whose operator is chosen at
runtime</td><td><code>UnaryPredicate(op, term)</code>,
<code>LiteralPredicate(op, term, lit)</code>, <code>SetPredicate(op, term,
lits)</code></td></tr>
+<tr><td>Filter on a field inside a variant column</td><td><code>Extract(ref,
path, typ)</code> inside a predicate builder</td></tr>
<tr><td>Walk an expression tree</td><td>A custom
<code>BooleanExprVisitor</code> from <code>visitors.go</code></td></tr>
</tbody></table>
</div>
@@ -2011,7 +2123,8 @@ instance to <code>table.WithReporter</code> or
<code>table.WithMetricsReporter</
<tr><td>Row lineage (<code>_row_id</code>,
<code>_last_updated_sequence_number</code>)</td><td>Supported</td></tr>
<tr><td>Encryption keys in metadata</td><td>Supported</td></tr>
<tr><td>Variant type, non-shredded</td><td>Supported (PR <a
href="https://github.com/apache/iceberg-go/pull/932";>#932</a>; umbrella <a
href="https://github.com/apache/iceberg-go/issues/929";>#929</a>)</td></tr>
-<tr><td>Variant type, shredded reader / writer</td><td>In progress (<a
href="https://github.com/apache/iceberg-go/issues/986";>#986</a>, <a
href="https://github.com/apache/iceberg-go/issues/987";>#987</a>)</td></tr>
+<tr><td>Variant type, shredded reader / writer</td><td>Supported (reader <a
href="https://github.com/apache/iceberg-go/pull/1238";>#1238</a>, writer <a
href="https://github.com/apache/iceberg-go/pull/1351";>#1351</a>)</td></tr>
+<tr><td>Variant predicate pushdown / field extract</td><td>Supported (PR <a
href="https://github.com/apache/iceberg-go/pull/1607";>#1607</a>)</td></tr>
<tr><td>Deletion vectors, read</td><td>Supported</td></tr>
<tr><td>Deletion vectors, write (unpartitioned)</td><td>Supported</td></tr>
<tr><td>Deletion vectors, write (partitioned)</td><td>In progress (<a
href="https://github.com/apache/iceberg-go/issues/1135";>#1135</a>, PR <a
href="https://github.com/apache/iceberg-go/pull/1151";>#1151</a>)</td></tr>
diff --git a/releases.html b/releases.html
index 15a2218c0..139e645a0 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 831a90880..5a23b7b12 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>
@@ -274,6 +274,20 @@ iceberg.NotNaN(iceberg.Reference("ratio"))
iceberg.NotStartsWith(iceberg.Reference("name"), "tmp_")
</code></pre>
<p>Operators <code>OpStartsWith</code> and <code>OpNotStartsWith</code>
(<code>exprs.go:53-54</code>). The value must be a <code>string</code>.</p>
+<h2 id="variant-extraction"><a class="header"
href="#variant-extraction">Variant extraction</a></h2>
+<p><code>iceberg.Extract(ref, path, typ)</code> builds a term that navigates a
member-selector path into a <code>variant</code> column and casts the leaf to
<code>typ</code>. The path uses dot (<code>$.user.age</code>) or quoted-bracket
(<code>$['user']['age']</code>) notation; array indexing
(<code>$.items[0]</code>), wildcards, filters, and recursive descent are
rejected at bind time. It is an <code>UnboundTerm</code>, so it plugs into the
same predicate builders as <code>iceberg.Refer [...]
+<pre><code class="language-go">filter := iceberg.EqualTo(
+ iceberg.Extract(iceberg.Reference("payload"),
"$.user.age", iceberg.PrimitiveTypes.Int64),
+ int64(30),
+)
+</code></pre>
+<p>The referenced column must be a <code>variant</code>, and a target type is
required. Supported target types: <code>bool</code>, <code>int32</code>,
<code>int64</code>, <code>float32</code>, <code>float64</code>,
<code>date</code>, <code>time</code>, <code>timestamp</code>,
<code>timestamptz</code>, <code>timestamp_ns</code>,
<code>timestamptz_ns</code>, <code>string</code>, <code>fixed</code>,
<code>binary</code>, <code>decimal</code>, <code>uuid</code>.</p>
+<p>Caveats:</p>
+<ul>
+<li>Extract predicates prune whole data files by shredded-field bounds
(best-effort, and only for shredded fields), then filter row by row. Row-group
statistics and bloom filters do not apply to them.</li>
+<li>Extract terms are DSL-only (no string row-filter form) and are not
REST-serializable. Under local scan planning (the default) they run as local
residuals; with remote scan planning, a filter containing an Extract term fails
to serialize rather than being silently dropped.</li>
+</ul>
+<p>See <a href="./variant.html">Variant Type</a> for shredding.</p>
<h2 id="constants"><a class="header" href="#constants">Constants</a></h2>
<pre><code class="language-go">iceberg.AlwaysTrue{}
iceberg.AlwaysFalse{}
@@ -320,7 +334,7 @@ scan := tbl.Scan(table.WithRowFilter(filter))
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
- <a rel="prev" href="api.html"
class="mobile-nav-chapters previous" title="Previous chapter"
aria-label="Previous chapter" aria-keyshortcuts="Left">
+ <a rel="prev" href="variant.html"
class="mobile-nav-chapters previous" title="Previous chapter"
aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
@@ -334,7 +348,7 @@ scan := tbl.Scan(table.WithRowFilter(filter))
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
- <a rel="prev" href="api.html" class="nav-chapters
previous" title="Previous chapter" aria-label="Previous chapter"
aria-keyshortcuts="Left">
+ <a rel="prev" href="variant.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/searchindex.js b/searchindex.js
index 5fa351c56..ef1a6ef6d 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 247398a6a..ead48439a 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/concurrent-writes.html b/variant.html
similarity index 69%
copy from concurrent-writes.html
copy to variant.html
index dbe499a4f..7443bb77c 100644
--- a/concurrent-writes.html
+++ b/variant.html
@@ -3,7 +3,7 @@
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
- <title>Concurrent Writes - Iceberg Golang</title>
+ <title>Variant Type - 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/concurrent-writes.md";
title="Suggest an edit" aria-label="Suggest an edit">
+ <a
href="https://github.com/apache/iceberg-go/edit/main/website/src/variant.md";
title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
@@ -232,78 +232,94 @@
~ 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>
+<h1 id="variant-type"><a class="header" href="#variant-type">Variant
Type</a></h1>
+<p><code>variant</code> is the Iceberg v3 semi-structured type: a single
self-describing column
+that holds arbitrary JSON-like values (objects, arrays, and scalars) without a
+fixed schema. iceberg-go supports both non-shredded and shredded variants, and
can
+push predicates down into individual variant fields.</p>
+<h2 id="reading-and-writing"><a class="header"
href="#reading-and-writing">Reading and writing</a></h2>
+<p>A variant column is declared with <code>iceberg.VariantType{}</code> in the
table schema and
+maps to the Arrow <code>variant</code> extension type (see <a
href="./api.html">API</a>). Non-shredded
+variant values need no extra configuration: write an Arrow record whose variant
+column uses the extension type, and read it back the same way.</p>
+<p>Build the column with a variant builder and write it like any other Arrow
column
+(the table must be format version 3):</p>
<pre><code class="language-go">import (
- "context"
- "errors"
-
+ "fmt"
+
+ "github.com/apache/arrow-go/v18/arrow"
+ "github.com/apache/arrow-go/v18/arrow/array"
+ "github.com/apache/arrow-go/v18/arrow/extensions"
+ "github.com/apache/arrow-go/v18/arrow/memory"
+ "github.com/apache/arrow-go/v18/parquet/variant"
+ "github.com/apache/iceberg-go"
"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",
- }),
+// tbl was created with table.PropertyFormatVersion = "3" and this
schema.
+schema := iceberg.NewSchema(0,
+ iceberg.NestedField{ID: 1, Name: "payload", Type:
iceberg.VariantType{}},
)
+arrowSchema, _ := table.SchemaToArrowSchema(schema, nil, true, false)
+
+bldr := extensions.NewVariantBuilder(memory.DefaultAllocator,
extensions.NewDefaultVariantType())
+defer bldr.Release()
+
+var vb variant.Builder
+_ = vb.Append(map[string]any{"x": int64(320), "target":
"button-submit"})
+val, _ := vb.Build()
+bldr.Append(val)
+
+col := bldr.NewArray()
+defer col.Release()
+rec := array.NewRecordBatch(arrowSchema, []arrow.Array{col}, 1)
+defer rec.Release()
+
+tx := tbl.NewTransaction()
+arrTable := array.NewTableFromRecords(arrowSchema, []arrow.Record{rec})
+defer arrTable.Release()
+_ = tx.AppendTable(ctx, arrTable, 1024, nil)
+tbl, _ = tx.Commit(ctx)
+</code></pre>
+<p>A normal scan reads it back; the variant column comes back as an
<code>*extensions.VariantArray</code>:</p>
+<pre><code class="language-go">result, _ := tbl.Scan().ToArrowTable(ctx)
+defer result.Release()
+
+variants := result.Column(0).Data().Chunk(0).(*extensions.VariantArray)
+v, _ := variants.Value(0)
+fmt.Println(v.Value()) // variant.ObjectValue for the object above
</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>
+<h2 id="shredding"><a class="header" href="#shredding">Shredding</a></h2>
+<p>Shredding stores the fields of a variant as typed Parquet sub-columns
instead of a
+single opaque blob. This lets scans read and filter a field as a native column
+rather than decoding every value. Shredding is opt-in and configured with two
write
+properties (see <a
href="./configuration.html#parquet-writer">Configuration</a>):</p>
+<ul>
+<li><code>write.parquet.shred-variants</code> - enable shredding of top-level
variant columns
+(default <code>false</code>).</li>
+<li><code>write.parquet.variant-inference-buffer-size</code> - rows buffered
per file to infer
+the shredding schema (default <code>100</code>).</li>
+</ul>
+<p>The reader accepts both shredded and non-shredded data; no read-side
+configuration is required.</p>
+<h2 id="filtering-on-variant-fields"><a class="header"
href="#filtering-on-variant-fields">Filtering on variant fields</a></h2>
+<p>Filter on a field inside a variant with <code>iceberg.Extract</code>, which
plugs into the
+usual predicate builders. See <a
href="./row-filter-syntax.html#variant-extraction">Row Filter Syntax</a>
+for usage, supported target types, and caveats.</p>
+<h2 id="constraints"><a class="header" href="#constraints">Constraints</a></h2>
+<ul>
+<li>A variant column cannot be a partition source or an identity-transform
source.</li>
+</ul>
</main>
<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="api.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="metrics-reporting.html" class="mobile-nav-chapters next" title="Next
chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
+ <a rel="next prefetch"
href="row-filter-syntax.html" class="mobile-nav-chapters next" title="Next
chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
@@ -313,11 +329,11 @@ not yet wrap their conflict errors, so the retry loop
will not fire on them.</p>
</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="api.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="metrics-reporting.html"
class="nav-chapters next" title="Next chapter" aria-label="Next chapter"
aria-keyshortcuts="Right">
+ <a rel="next prefetch" href="row-filter-syntax.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/verify-release.html b/verify-release.html
index 65ca365df..0bb2cb894 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>
