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 d21df2da feat(cli): add info command for single-screen table summary
(#1064)
d21df2da is described below
commit d21df2da13dce1519a9038d7f7c8a8fd148a0ebf
Author: Tanmay Rauth <[email protected]>
AuthorDate: Mon May 11 13:01:41 2026 -0700
feat(cli): add info command for single-screen table summary (#1064)
Add `iceberg info TABLE_ID` showing UUID, format version, location,
schema, partition spec, sort order, snapshot/ref counts, properties.
Related: #957
---
cmd/iceberg/info.go | 166 ++++++++++++++++++++++++++++++++++++
cmd/iceberg/info_test.go | 216 +++++++++++++++++++++++++++++++++++++++++++++++
cmd/iceberg/main.go | 4 +
cmd/iceberg/output.go | 1 +
4 files changed, 387 insertions(+)
diff --git a/cmd/iceberg/info.go b/cmd/iceberg/info.go
new file mode 100644
index 00000000..25356e08
--- /dev/null
+++ b/cmd/iceberg/info.go
@@ -0,0 +1,166 @@
+// 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 main
+
+import (
+ "encoding/json"
+ "fmt"
+ "os"
+ "strconv"
+ "strings"
+ "time"
+
+ "github.com/apache/iceberg-go/table"
+ "github.com/pterm/pterm"
+)
+
+type InfoCmd struct {
+ TableID string `arg:"positional,required" help:"full path to a table"`
+}
+
+type TableInfo struct {
+ Table string `json:"table"`
+ UUID string `json:"uuid"`
+ FormatVersion int `json:"format_version"`
+ Location string `json:"location"`
+ LastUpdated string `json:"last_updated"`
+ CurrentSnapshotID *int64 `json:"current_snapshot_id"`
+ NextRowID *int64 `json:"next_row_id,omitempty"`
+ SchemaID int `json:"schema_id"`
+ SchemaFieldCount int `json:"schema_field_count"`
+ PartitionSpec string `json:"partition_spec"`
+ SortOrder string `json:"sort_order"`
+ SnapshotCount int `json:"snapshot_count"`
+ Refs RefSummary `json:"refs"`
+ PropertyCount int `json:"property_count"`
+}
+
+type RefSummary struct {
+ Branches int `json:"branches"`
+ Tags int `json:"tags"`
+}
+
+func tableIDString(tbl *table.Table) string {
+ return strings.Join(tbl.Identifier(), ".")
+}
+
+func buildTableInfo(tbl *table.Table) TableInfo {
+ meta := tbl.Metadata()
+
+ lastUpdated :=
time.UnixMilli(meta.LastUpdatedMillis()).UTC().Format(time.RFC3339)
+
+ var currentSnapshotID *int64
+ if snap := meta.CurrentSnapshot(); snap != nil {
+ id := snap.SnapshotID
+ currentSnapshotID = &id
+ }
+
+ var nextRowID *int64
+ if rid := meta.NextRowID(); rid > 0 {
+ nextRowID = &rid
+ }
+
+ schema := meta.CurrentSchema()
+
+ specStr := meta.PartitionSpec().String()
+
+ var sortOrderStr string
+ if meta.SortOrder().Len() == 0 {
+ sortOrderStr = "unsorted"
+ } else {
+ sortOrderStr = meta.SortOrder().String()
+ }
+
+ var refs RefSummary
+ for _, ref := range meta.Refs() {
+ switch ref.SnapshotRefType {
+ case table.BranchRef:
+ refs.Branches++
+ case table.TagRef:
+ refs.Tags++
+ }
+ }
+
+ return TableInfo{
+ Table: tableIDString(tbl),
+ UUID: meta.TableUUID().String(),
+ FormatVersion: meta.Version(),
+ Location: meta.Location(),
+ LastUpdated: lastUpdated,
+ CurrentSnapshotID: currentSnapshotID,
+ NextRowID: nextRowID,
+ SchemaID: schema.ID,
+ SchemaFieldCount: schema.NumFields(),
+ PartitionSpec: specStr,
+ SortOrder: sortOrderStr,
+ SnapshotCount: len(meta.Snapshots()),
+ Refs: refs,
+ PropertyCount: len(meta.Properties()),
+ }
+}
+
+func pluralize(n int, singular, plural string) string {
+ if n == 1 {
+ return "1 " + singular
+ }
+
+ return strconv.Itoa(n) + " " + plural
+}
+
+func (t textOutput) Info(tbl *table.Table) {
+ info := buildTableInfo(tbl)
+
+ snapStr := "-"
+ if info.CurrentSnapshotID != nil {
+ snapStr = strconv.FormatInt(*info.CurrentSnapshotID, 10)
+ }
+
+ schemaStr := fmt.Sprintf("%d (%d fields)", info.SchemaID,
info.SchemaFieldCount)
+ refsStr := pluralize(info.Refs.Branches, "branch", "branches") + ", " +
pluralize(info.Refs.Tags, "tag", "tags")
+
+ data := pterm.TableData{
+ {"Table:", info.Table},
+ {"UUID:", info.UUID},
+ {"Format version:", strconv.Itoa(info.FormatVersion)},
+ {"Location:", info.Location},
+ {"Last updated:", info.LastUpdated},
+ {"Current snapshot:", snapStr},
+ }
+
+ if info.NextRowID != nil {
+ data = append(data, []string{"Next row ID:",
strconv.FormatInt(*info.NextRowID, 10)})
+ }
+
+ data = append(data,
+ []string{"Schema ID:", schemaStr},
+ []string{"Partition spec:", info.PartitionSpec},
+ []string{"Sort order:", info.SortOrder},
+ []string{"Snapshots:", strconv.Itoa(info.SnapshotCount)},
+ []string{"Refs:", refsStr},
+ []string{"Properties:", strconv.Itoa(info.PropertyCount)},
+ )
+
+ pterm.DefaultTable.WithData(data).Render()
+}
+
+func (j jsonOutput) Info(tbl *table.Table) {
+ info := buildTableInfo(tbl)
+ if err := json.NewEncoder(os.Stdout).Encode(info); err != nil {
+ j.Error(err)
+ }
+}
diff --git a/cmd/iceberg/info_test.go b/cmd/iceberg/info_test.go
new file mode 100644
index 00000000..e5a8d360
--- /dev/null
+++ b/cmd/iceberg/info_test.go
@@ -0,0 +1,216 @@
+// 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 main
+
+import (
+ "bytes"
+ "os"
+ "testing"
+
+ "github.com/apache/iceberg-go/table"
+ "github.com/pterm/pterm"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+const infoTestMetadata = `{
+ "format-version": 2,
+ "table-uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
+ "location": "s3://bucket/test/location",
+ "last-sequence-number": 34,
+ "last-updated-ms": 1602638573590,
+ "last-column-id": 3,
+ "current-schema-id": 1,
+ "schemas": [
+ {"type": "struct", "schema-id": 0, "fields": [{"id": 1, "name": "x",
"required": true, "type": "long"}]},
+ {
+ "type": "struct",
+ "schema-id": 1,
+ "identifier-field-ids": [1, 2],
+ "fields": [
+ {"id": 1, "name": "x", "required": true, "type": "long"},
+ {"id": 2, "name": "y", "required": true, "type": "long",
"doc": "comment"},
+ {"id": 3, "name": "z", "required": true, "type": "long"}
+ ]
+ }
+ ],
+ "default-spec-id": 0,
+ "partition-specs": [{"spec-id": 0, "fields": [{"name": "x", "transform":
"identity", "source-id": 1, "field-id": 1000}]}],
+ "last-partition-id": 1000,
+ "default-sort-order-id": 3,
+ "sort-orders": [
+ {
+ "order-id": 3,
+ "fields": [
+ {"transform": "identity", "source-id": 2, "direction": "asc",
"null-order": "nulls-first"},
+ {"transform": "bucket[4]", "source-id": 3, "direction":
"desc", "null-order": "nulls-last"}
+ ]
+ }
+ ],
+ "properties": {"read.split.target.size": "134217728"},
+ "current-snapshot-id": 3055729675574597004,
+ "snapshots": [
+ {
+ "snapshot-id": 3051729675574597004,
+ "timestamp-ms": 1515100955770,
+ "sequence-number": 0,
+ "summary": {"operation": "append"},
+ "manifest-list": "s3://a/b/1.avro",
+ "schema-id": 1
+ },
+ {
+ "snapshot-id": 3055729675574597004,
+ "parent-snapshot-id": 3051729675574597004,
+ "timestamp-ms": 1555100955770,
+ "sequence-number": 1,
+ "summary": {"operation": "append"},
+ "manifest-list": "s3://a/b/2.avro",
+ "schema-id": 1
+ }
+ ],
+ "snapshot-log": [
+ {"snapshot-id": 3051729675574597004, "timestamp-ms": 1515100955770},
+ {"snapshot-id": 3055729675574597004, "timestamp-ms": 1555100955770}
+ ],
+ "metadata-log": [{"metadata-file": "s3://bucket/.../v1.json",
"timestamp-ms": 1515100}],
+ "refs": {"test": {"snapshot-id": 3051729675574597004, "type": "tag",
"max-ref-age-ms": 10000000}}
+}`
+
+const infoTestMetadataUnsorted = `{
+ "format-version": 2,
+ "table-uuid": "9c12d441-03fe-4693-9a96-a0705ddf69c1",
+ "location": "s3://bucket/test/location",
+ "last-sequence-number": 0,
+ "last-updated-ms": 1602638573590,
+ "last-column-id": 3,
+ "current-schema-id": 0,
+ "schemas": [
+ {"type": "struct", "schema-id": 0, "fields": [{"id": 1, "name": "x",
"required": true, "type": "long"}]}
+ ],
+ "default-spec-id": 0,
+ "partition-specs": [{"spec-id": 0, "fields": []}],
+ "last-partition-id": 1000,
+ "default-sort-order-id": 0,
+ "sort-orders": [{"order-id": 0, "fields": []}],
+ "properties": {},
+ "current-snapshot-id": -1,
+ "snapshots": [],
+ "snapshot-log": [],
+ "metadata-log": [],
+ "refs": {}
+}`
+
+func TestBuildTableInfo(t *testing.T) {
+ meta, err := table.ParseMetadataBytes([]byte(infoTestMetadata))
+ require.NoError(t, err)
+
+ tbl := table.New([]string{"db", "events"}, meta, "", nil, nil)
+ info := buildTableInfo(tbl)
+
+ assert.Equal(t, "db.events", info.Table)
+ assert.Equal(t, "9c12d441-03fe-4693-9a96-a0705ddf69c1", info.UUID)
+ assert.Equal(t, 2, info.FormatVersion)
+ assert.Equal(t, "s3://bucket/test/location", info.Location)
+ assert.Equal(t, "2020-10-14T01:22:53Z", info.LastUpdated)
+ require.NotNil(t, info.CurrentSnapshotID)
+ assert.Equal(t, int64(3055729675574597004), *info.CurrentSnapshotID)
+ assert.Equal(t, 1, info.SchemaID)
+ assert.Equal(t, 3, info.SchemaFieldCount)
+ assert.Contains(t, info.PartitionSpec, "identity")
+ assert.NotEqual(t, "unsorted", info.SortOrder)
+ assert.Equal(t, 2, info.SnapshotCount)
+ assert.Equal(t, 1, info.Refs.Branches)
+ assert.Equal(t, 1, info.Refs.Tags)
+ assert.Equal(t, 1, info.PropertyCount)
+}
+
+func TestBuildTableInfoUnsorted(t *testing.T) {
+ meta, err := table.ParseMetadataBytes([]byte(infoTestMetadataUnsorted))
+ require.NoError(t, err)
+
+ tbl := table.New([]string{"db", "empty"}, meta, "", nil, nil)
+ info := buildTableInfo(tbl)
+
+ assert.Equal(t, "db.empty", info.Table)
+ assert.Nil(t, info.CurrentSnapshotID)
+ assert.Equal(t, "unsorted", info.SortOrder)
+ assert.Equal(t, 0, info.SnapshotCount)
+ assert.Equal(t, 0, info.PropertyCount)
+}
+
+func TestTableIDString(t *testing.T) {
+ meta, err := table.ParseMetadataBytes([]byte(infoTestMetadataUnsorted))
+ require.NoError(t, err)
+
+ tbl := table.New([]string{"catalog", "db", "tbl"}, meta, "", nil, nil)
+ assert.Equal(t, "catalog.db.tbl", tableIDString(tbl))
+}
+
+func TestTextOutputInfo(t *testing.T) {
+ var buf bytes.Buffer
+ pterm.SetDefaultOutput(&buf)
+ pterm.DisableColor()
+
+ meta, err := table.ParseMetadataBytes([]byte(infoTestMetadata))
+ require.NoError(t, err)
+
+ tbl := table.New([]string{"db", "events"}, meta, "", nil, nil)
+ buf.Reset()
+
+ textOutput{}.Info(tbl)
+
+ output := buf.String()
+ assert.Contains(t, output, "Table:")
+ assert.Contains(t, output, "db.events")
+ assert.Contains(t, output, "UUID:")
+ assert.Contains(t, output, "9c12d441-03fe-4693-9a96-a0705ddf69c1")
+ assert.Contains(t, output, "Format version:")
+ assert.Contains(t, output, "Location:")
+ assert.Contains(t, output, "Current snapshot:")
+ assert.Contains(t, output, "3055729675574597004")
+ assert.Contains(t, output, "Schema ID:")
+ assert.Contains(t, output, "1 (3 fields)")
+ assert.Contains(t, output, "1 branch, 1 tag")
+}
+
+func TestJSONOutputInfo(t *testing.T) {
+ oldStdout := os.Stdout
+ r, w, _ := os.Pipe()
+ os.Stdout = w
+ defer func() {
+ os.Stdout = oldStdout
+ }()
+
+ meta, err := table.ParseMetadataBytes([]byte(infoTestMetadata))
+ require.NoError(t, err)
+
+ tbl := table.New([]string{"db", "events"}, meta, "", nil, nil)
+
+ jsonOutput{}.Info(tbl)
+
+ w.Close()
+ var buf bytes.Buffer
+ _, _ = buf.ReadFrom(r)
+
+ output := buf.String()
+ assert.Contains(t, output, `"table":"db.events"`)
+ assert.Contains(t, output,
`"uuid":"9c12d441-03fe-4693-9a96-a0705ddf69c1"`)
+ assert.Contains(t, output, `"format_version":2`)
+ assert.Contains(t, output, `"current_snapshot_id":3055729675574597004`)
+ assert.Contains(t, output, `"snapshot_count":2`)
+}
diff --git a/cmd/iceberg/main.go b/cmd/iceberg/main.go
index 06942cf3..ecc93f8c 100644
--- a/cmd/iceberg/main.go
+++ b/cmd/iceberg/main.go
@@ -179,6 +179,7 @@ type Args struct {
Rename *RenameCmd `arg:"subcommand:rename" help:"rename a
table"`
Properties *PropertiesCmd `arg:"subcommand:properties" help:"manage
properties on tables/namespaces"`
Compact *CompactCmd `arg:"subcommand:compact" help:"analyze or
run bin-pack compaction"`
+ Info *InfoCmd `arg:"subcommand:info" help:"show
single-screen table summary"`
Catalog string `arg:"--catalog" default:"rest" help:"catalog type"`
CatalogName string `arg:"--catalog-name" default:"default"
help:"catalog name from config"`
@@ -286,6 +287,9 @@ func main() {
runProperties(ctx, output, cat, args.Properties)
case args.Compact != nil:
runCompact(ctx, output, cat, args.Compact)
+ case args.Info != nil:
+ tbl := loadTable(ctx, output, cat, args.Info.TableID)
+ output.Info(tbl)
}
}
diff --git a/cmd/iceberg/output.go b/cmd/iceberg/output.go
index 32a3a101..03ecf9f0 100644
--- a/cmd/iceberg/output.go
+++ b/cmd/iceberg/output.go
@@ -39,6 +39,7 @@ type Output interface {
DescribeTable(*table.Table)
Files(tbl *table.Table, history bool)
DescribeProperties(iceberg.Properties)
+ Info(tbl *table.Table)
Text(string)
Schema(*iceberg.Schema)
Spec(iceberg.PartitionSpec)
