You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by at...@apache.org on 2026/08/30 18:46:16 UTC
(iceberg-go) branch main updated: perf(table): borrow manifest partition summaries (#1908)
This is an automated email from the ASF dual-hosted git repository.
laskoviymishka pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git
The following commit(s) were added to refs/heads/main by this push:
new ffa9df382 perf(table): borrow manifest partition summaries (#1908)
ffa9df382 is described below
commit ffa9df382155a5b74a452fa8be041d8bd5d0fc4a
Author: Minh Vu <vu...@gmail.com>
AuthorDate: Sun Aug 30 20:46:11 2026 +0200
perf(table): borrow manifest partition summaries (#1908)
* perf(table): borrow manifest partition summaries
* test(table): tighten manifest partition borrow checks
---
internal/manifest_file_ref.go | 50 +++++++++++++++++
manifest_file_ref.go | 34 +++++++++++
table/evaluators.go | 2 +-
table/evaluators_bench_test.go | 121 ++++++++++++++++++++++++++++++++++++++++
table/manifest_file_ref.go | 31 ++++++++++
table/manifest_file_ref_test.go | 80 ++++++++++++++++++++++++++
6 files changed, 317 insertions(+), 1 deletion(-)
diff --git a/internal/manifest_file_ref.go b/internal/manifest_file_ref.go
new file mode 100644
index 000000000..c841f684e
--- /dev/null
+++ b/internal/manifest_file_ref.go
@@ -0,0 +1,50 @@
+// 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.
+
+package internal
+
+// ManifestFileRef authorizes zero-copy access to immutable manifest state from
+// trusted packages within this module. Data obtained with this token is
+// borrowed, must be treated as read-only, and must not be retained beyond the
+// current operation. Go's internal-package rule prevents external callers
+// from constructing this token.
+type ManifestFileRef struct{}
+
+// ManifestFilePartitions is the public partition-summary surface needed by
+// the internal borrowed-partition helper. It is parameterized so this package
+// does not need to import the root package.
+type ManifestFilePartitions[T any] interface {
+ Partitions() []T
+}
+
+// ManifestPartitionBorrower is implemented by the built-in manifest file to
+// expose its partition summaries to trusted in-module callers.
+type ManifestPartitionBorrower[T any] interface {
+ ManifestFilePartitionRef(ManifestFileRef) []T
+}
+
+// BorrowedManifestFilePartitions returns partition summaries without copying
+// for the built-in manifest file and falls back to the public getter for
+// external implementations. The returned slice and all nested values are
+// read-only borrows that must not escape the current operation.
+func BorrowedManifestFilePartitions[T any](file ManifestFilePartitions[T]) []T {
+ if ref, ok := file.(ManifestPartitionBorrower[T]); ok {
+ return ref.ManifestFilePartitionRef(ManifestFileRef{})
+ }
+
+ return file.Partitions()
+}
diff --git a/manifest_file_ref.go b/manifest_file_ref.go
new file mode 100644
index 000000000..b3c4f11d7
--- /dev/null
+++ b/manifest_file_ref.go
@@ -0,0 +1,34 @@
+// 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.
+
+package iceberg
+
+import "github.com/apache/iceberg-go/internal"
+
+// ManifestFilePartitionRef returns the manifest's partition summaries without
+// copying for trusted in-module callers. The returned slice and all nested
+// bounds alias the manifest and must be treated as read-only for the current
+// operation.
+func (m *manifestFile) ManifestFilePartitionRef(_ internal.ManifestFileRef) []FieldSummary {
+ if m.PartitionList == nil {
+ return nil
+ }
+
+ // The builder and decoder maintain that a non-nil PartitionList points to
+ // a non-nil slice.
+ return *m.PartitionList
+}
diff --git a/table/evaluators.go b/table/evaluators.go
index e775a90e3..c74ed75f6 100644
--- a/table/evaluators.go
+++ b/table/evaluators.go
@@ -62,7 +62,7 @@ type manifestEvalVisitor struct {
}
func (m *manifestEvalVisitor) Eval(manifest iceberg.ManifestFile) (bool, error) {
- parts := manifest.Partitions()
+ parts := manifestFilePartitions(manifest)
if len(parts) == 0 {
return rowsMightMatch, nil
}
diff --git a/table/evaluators_bench_test.go b/table/evaluators_bench_test.go
new file mode 100644
index 000000000..78fb26570
--- /dev/null
+++ b/table/evaluators_bench_test.go
@@ -0,0 +1,121 @@
+// 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.
+
+package table
+
+import (
+ "fmt"
+ "slices"
+ "testing"
+
+ "github.com/apache/iceberg-go"
+)
+
+var manifestEvaluatorBenchmarkSink int
+
+func BenchmarkManifestEvaluatorBuiltInPartitions(b *testing.B) {
+ for _, manifestCount := range []int{1, 100, 1_000} {
+ for _, fieldCount := range []int{1, 8, 32} {
+ b.Run(fmt.Sprintf("manifests=%d/fields=%d", manifestCount, fieldCount), func(b *testing.B) {
+ spec, schema := manifestEvaluatorBenchmarkSpec(fieldCount)
+ filter := manifestEvaluatorBenchmarkFilter(fieldCount)
+ eval, err := newManifestEvaluator(spec, schema, filter, true)
+ if err != nil {
+ b.Fatal(err)
+ }
+
+ summaries := manifestEvaluatorBenchmarkSummaries(fieldCount)
+ manifests := make([]iceberg.ManifestFile, manifestCount)
+ for i := range manifests {
+ manifests[i] = iceberg.NewManifestFile(
+ 2, fmt.Sprintf("manifest-%d.avro", i), 0, int32(spec.ID()), 1,
+ ).Partitions(summaries).Build()
+ }
+
+ b.ReportAllocs()
+ b.ResetTimer()
+ for range b.N {
+ matched := 0
+ for _, manifest := range manifests {
+ keep, err := eval(manifest)
+ if err != nil {
+ b.Fatal(err)
+ }
+ if keep {
+ matched++
+ }
+ }
+ manifestEvaluatorBenchmarkSink = matched
+ }
+ })
+ }
+ }
+}
+
+func manifestEvaluatorBenchmarkSpec(fieldCount int) (iceberg.PartitionSpec, *iceberg.Schema) {
+ schemaFields := make([]iceberg.NestedField, fieldCount)
+ partitionFields := make([]iceberg.PartitionField, fieldCount)
+ for i := range fieldCount {
+ fieldID := i + 1
+ fieldName := fmt.Sprintf("field_%d", i)
+ schemaFields[i] = iceberg.NestedField{
+ ID: fieldID, Name: fieldName, Type: iceberg.PrimitiveTypes.Int32, Required: true,
+ }
+ partitionFields[i] = iceberg.PartitionField{
+ SourceIDs: []int{fieldID}, FieldID: 1000 + i,
+ Name: fieldName, Transform: iceberg.IdentityTransform{},
+ }
+ }
+
+ return iceberg.NewPartitionSpecID(1, partitionFields...), iceberg.NewSchema(1, schemaFields...)
+}
+
+func manifestEvaluatorBenchmarkFilter(fieldCount int) iceberg.BooleanExpression {
+ var filter iceberg.BooleanExpression = iceberg.GreaterThanEqual(
+ iceberg.Reference("field_0"), int32(0))
+ for i := 1; i < fieldCount; i++ {
+ filter = iceberg.NewAnd(filter,
+ iceberg.GreaterThanEqual(iceberg.Reference(fmt.Sprintf("field_%d", i)), int32(0)))
+ }
+
+ return filter
+}
+
+func manifestEvaluatorBenchmarkSummaries(fieldCount int) []iceberg.FieldSummary {
+ lowerBound, err := iceberg.Int32Literal(0).MarshalBinary()
+ if err != nil {
+ panic(err)
+ }
+ upperBound, err := iceberg.Int32Literal(100).MarshalBinary()
+ if err != nil {
+ panic(err)
+ }
+
+ summaries := make([]iceberg.FieldSummary, fieldCount)
+ for i := range summaries {
+ containsNaN := false
+ lower := slices.Clone(lowerBound)
+ upper := slices.Clone(upperBound)
+ summaries[i] = iceberg.FieldSummary{
+ ContainsNaN: &containsNaN,
+ LowerBound: &lower,
+ UpperBound: &upper,
+ }
+ }
+
+ return summaries
+}
diff --git a/table/manifest_file_ref.go b/table/manifest_file_ref.go
new file mode 100644
index 000000000..e8d450e47
--- /dev/null
+++ b/table/manifest_file_ref.go
@@ -0,0 +1,31 @@
+// 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.
+
+package table
+
+import (
+ "github.com/apache/iceberg-go"
+ iceberginternal "github.com/apache/iceberg-go/internal"
+)
+
+// manifestFilePartitions returns partition summaries without copying for the
+// built-in manifest file and falls back to the public getter for external
+// implementations. Callers must treat the returned slice and nested bounds as
+// read-only and must not retain them beyond the current operation.
+func manifestFilePartitions(file iceberg.ManifestFile) []iceberg.FieldSummary {
+ return iceberginternal.BorrowedManifestFilePartitions(file)
+}
diff --git a/table/manifest_file_ref_test.go b/table/manifest_file_ref_test.go
new file mode 100644
index 000000000..6a19d8b78
--- /dev/null
+++ b/table/manifest_file_ref_test.go
@@ -0,0 +1,80 @@
+// 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.
+
+package table
+
+import (
+ "testing"
+
+ "github.com/apache/iceberg-go"
+ iceberginternal "github.com/apache/iceberg-go/internal"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+type publicManifestFile struct {
+ iceberg.ManifestFile
+ partitionCalls int
+}
+
+func (m *publicManifestFile) Partitions() []iceberg.FieldSummary {
+ m.partitionCalls++
+
+ return m.ManifestFile.Partitions()
+}
+
+func TestManifestFilePartitionsUsesBorrowedView(t *testing.T) {
+ containsNaN := false
+ lower := []byte{1, 2}
+ upper := []byte{3, 4}
+ manifest := iceberg.NewManifestFile(2, "manifest.avro", 0, 1, 1).Partitions(
+ []iceberg.FieldSummary{{
+ ContainsNaN: &containsNaN,
+ LowerBound: &lower,
+ UpperBound: &upper,
+ }},
+ ).Build()
+
+ require.Implements(t, (*iceberginternal.ManifestPartitionBorrower[iceberg.FieldSummary])(nil), manifest)
+ partitions := manifestFilePartitions(manifest)
+ require.Len(t, partitions, 1)
+ assert.Equal(t, []byte{1, 2}, *partitions[0].LowerBound)
+ assert.Equal(t, []byte{3, 4}, *partitions[0].UpperBound)
+
+ // This intentionally violates the read-only borrow contract to prove that
+ // the returned bound aliases manifest storage. Callers must not mutate it.
+ (*partitions[0].LowerBound)[0] = 9
+ borrowedAgain := manifestFilePartitions(manifest)
+ require.NotNil(t, borrowedAgain[0].LowerBound)
+ assert.Equal(t, byte(9), (*borrowedAgain[0].LowerBound)[0])
+ (*partitions[0].LowerBound)[0] = 1
+
+ allocs := testing.AllocsPerRun(100, func() {
+ partitions = manifestFilePartitions(manifest)
+ })
+ assert.Zero(t, allocs)
+}
+
+func TestManifestFilePartitionsFallsBackToPublicGetter(t *testing.T) {
+ manifest := iceberg.NewManifestFile(2, "manifest.avro", 0, 1, 1).
+ Partitions([]iceberg.FieldSummary{{}}).Build()
+ file := &publicManifestFile{ManifestFile: manifest}
+
+ partitions := manifestFilePartitions(file)
+ require.Len(t, partitions, 1)
+ assert.Equal(t, 1, file.partitionCalls)
+}