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 4dac36517 docs: mark sentinel-gated Ref accessors as module-internal
(#2348)
4dac36517 is described below
commit 4dac365176b5bebfd42e1e6849debb5e6988dd3b
Author: Matt Topol <[email protected]>
AuthorDate: Thu Oct 29 16:12:38 2026 +0000
docs: mark sentinel-gated Ref accessors as module-internal (#2348)
Schema.FieldsRef, Schema.FindFieldByIDRef and PartitionSpec.FieldsRef take
an argument from the internal package, so only iceberg-go's own packages
can call them. Document that they are not covered by compatibility
guarantees and point external users at the cloning accessors.
---
partitions.go | 4 ++++
schema.go | 8 ++++++++
2 files changed, 12 insertions(+)
diff --git a/partitions.go b/partitions.go
index d365d907b..d190beb36 100644
--- a/partitions.go
+++ b/partitions.go
@@ -599,6 +599,10 @@ func (ps *PartitionSpec) Fields() iter.Seq2[int,
PartitionField] {
// FieldsRef returns the partition fields owned by this spec for trusted
// internal callers. The returned slice and everything reachable through the
// fields must be treated as read-only.
+//
+// FieldsRef is for use by iceberg-go's own packages only: its sentinel
argument
+// cannot be constructed outside this module. It is not covered by the module's
+// compatibility guarantees. Use [PartitionSpec.Fields] instead.
func (ps *PartitionSpec) FieldsRef(_ internal.PartitionSpecRef)
[]PartitionField {
return ps.fields
}
diff --git a/schema.go b/schema.go
index 548255aef..94c8fc0e4 100644
--- a/schema.go
+++ b/schema.go
@@ -282,6 +282,10 @@ func (s *Schema) Fields() []NestedField { return
cloneFields(s.fields) }
// FieldsRef returns the schema-owned fields for trusted internal callers.
// The returned slice and everything reachable through the fields must be
// treated as read-only.
+//
+// FieldsRef is for use by iceberg-go's own packages only: its sentinel
argument
+// cannot be constructed outside this module. It is not covered by the module's
+// compatibility guarantees. Use [Schema.Fields] instead.
func (s *Schema) FieldsRef(_ internal.SchemaRef) []NestedField { return
s.fields }
func (s *Schema) FieldIDs() []int {
@@ -475,6 +479,10 @@ func (s *Schema) FindFieldByID(id int) (NestedField, bool)
{
// field is a value copy, but its Type and everything reachable from that Type
// are shared with the schema and must be treated as read-only. This method is
// limited to internal callers that need to avoid clone-on-read overhead.
+//
+// FindFieldByIDRef is for use by iceberg-go's own packages only: its sentinel
+// argument cannot be constructed outside this module. It is not covered by the
+// module's compatibility guarantees. Use [Schema.FindFieldByID] instead.
func (s *Schema) FindFieldByIDRef(id int, _ internal.SchemaRef) (NestedField,
bool) {
idx, _ := s.lazyIDToField()
f, ok := idx[id]
