### Setup Integration Tests with Docker

Source: https://github.com/apache/iceberg-go/blob/main/README.md

Prepare the environment for integration tests by starting Docker containers. Requires Docker and Docker Compose.

```shell
make integration-setup
```

--------------------------------

### Build and Install Iceberg Go CLI

Source: https://github.com/apache/iceberg-go/blob/main/README.md

Build the CLI executable from the repository root or install it globally using `go install`. This prepares the `iceberg` command for use.

```bash
go build ./cmd/iceberg
```

```bash
go install github.com/apache/iceberg-go/cmd/iceberg@latest
```

--------------------------------

### Build and Install Iceberg CLI

Source: https://github.com/apache/iceberg-go/blob/main/website/src/cli.md

Instructions to build the CLI executable or install it to your GOPATH.

```bash
go build ./cmd/iceberg
```

```bash
go install github.com/apache/iceberg-go/cmd/iceberg
```

--------------------------------

### Schema Creation Examples

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Examples demonstrating how to create simple, nested, and complex schemas using the `iceberg.NewSchemaWithIdentifiers` function.

```APIDOC
## Schema Creation

Here are some examples of creating different types of schemas:

```go
// Simple schema with primitive types
simpleSchema := iceberg.NewSchemaWithIdentifiers(1, []int{2},
    iceberg.NestedField{ID: 1, Name: "id", Type: iceberg.PrimitiveTypes.Int32, Required: true},
    iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
    iceberg.NestedField{ID: 3, Name: "active", Type: iceberg.PrimitiveTypes.Bool, Required: false},
)

// Schema with nested struct
nestedSchema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
    iceberg.NestedField{ID: 1, Name: "person", Type: &iceberg.StructType{
        FieldList: []iceberg.NestedField{
            {ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
            {ID: 3, Name: "age", Type: iceberg.PrimitiveTypes.Int32, Required: true},
        },
    }, Required: false},
)

// Schema with list and map types
complexSchema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
    iceberg.NestedField{ID: 1, Name: "tags", Type: &iceberg.ListType{
        ElementID: 2, Element: iceberg.PrimitiveTypes.String, ElementRequired: true,
    }, Required: false},
    iceberg.NestedField{ID: 3, Name: "metadata", Type: &iceberg.MapType{
        KeyID: 4, KeyType: iceberg.PrimitiveTypes.String,
        ValueID: 5, ValueType: iceberg.PrimitiveTypes.String, ValueRequired: true,
    }, Required: false},
)
```
```

--------------------------------

### Creating Tables with Partitioning

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Example of creating an Iceberg table with a specified schema and partition specification.

```APIDOC
## Creating Tables with Partitioning

You can create tables with partitioning:

```go
import (
    "github.com/apache/iceberg-go"
    "github.com/apache/iceberg-go/catalog"
)

// Create schema
schema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
    iceberg.NestedField{ID: 1, Name: "id", Type: iceberg.PrimitiveTypes.Int32, Required: true},
    iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
    iceberg.NestedField{ID: 3, Name: "date", Type: iceberg.PrimitiveTypes.Date, Required: false},
)

// Create a partition spec
partitionSpec := iceberg.NewPartitionSpec(
    iceberg.PartitionField{SourceID: 3, FieldID: 1000, Transform: iceberg.IdentityTransform{}, Name: "date"},
)

// Create a table with partitioning
tbl, err := cat.CreateTable(
    context.Background(),
    tableIdent,
    schema,
    catalog.WithPartitionSpec(&partitionSpec),
    catalog.WithLocation("s3://my-bucket/tables/partitioned_table"),
)
if err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### Clone and Build Iceberg Go

Source: https://github.com/apache/iceberg-go/blob/main/README.md

Clone the repository and build the iceberg command-line tool. Ensure Go 1.25 or later is installed.

```shell
git clone https://github.com/apache/iceberg-go.git
cd iceberg-go/cmd/iceberg && go build .
```

--------------------------------

### Install mdbook

Source: https://github.com/apache/iceberg-go/blob/main/website/README.md

Installs the mdbook tool, which is required for building and serving the documentation.

```shell
cargo install mdbook
```

--------------------------------

### Traverse Schema with Visit and PreOrderVisit

Source: https://context7.com/apache/iceberg-go/llms.txt

Implement `SchemaVisitor[T]` to traverse schema trees using `Visit` (post-order) or `PreOrderVisit` (pre-order). This example demonstrates counting total fields.

```go
import "github.com/apache/iceberg-go"

// Count total fields in a schema (including nested)
type fieldCounter struct{}

func (fieldCounter) Schema(_ *iceberg.Schema, structResult int) int { return structResult }
func (fieldCounter) Struct(_ iceberg.StructType, results []int) int {
    total := 0
    for _, r := range results { total += r }
    return total
}
func (fieldCounter) Field(_ iceberg.NestedField, result int) int { return result + 1 }
func (fieldCounter) List(_ iceberg.ListType, r int) int          { return r }
func (fieldCounter) Map(_ iceberg.MapType, k, v int) int         { return k + v }
func (fieldCounter) Primitive(_ iceberg.PrimitiveType) int       { return 0 }

schema := iceberg.NewSchema(0,
    iceberg.NestedField{ID: 1, Name: "id",   Type: iceberg.PrimitiveTypes.Int64, Required: true},
    iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String},
)

count, err := iceberg.Visit(schema, fieldCounter{})
if err != nil { log.Fatal(err) }
fmt.Println(count) // 2

// AssignFreshSchemaIDs re-numbers all field IDs sequentially
fresh, err := iceberg.AssignFreshSchemaIDs(schema, nil) // starts at 1
fmt.Println(fresh.Field(0).ID) // 1
```

--------------------------------

### Install iceberg-go Package

Source: https://github.com/apache/iceberg-go/blob/main/website/src/install.md

Use this command to download and install the iceberg-go package. Ensure you have Go 1.25 or later installed and your Go workspace is set up.

```sh
go get -u github.com/apache/iceberg-go
```

--------------------------------

### Create Glue Catalog and Table

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Set up an AWS configuration and create an Iceberg catalog using AWS Glue. This example also demonstrates creating a table within the Glue catalog, specifying its identifier, schema, and location.

```go
import (
    "github.com/apache/iceberg-go/catalog/glue"
    "github.com/aws/aws-sdk-go-v2/config"
)

// Create AWS config
awsCfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Fatal(err)
}

// Create Glue catalog
cat := glue.NewCatalog(glue.WithAwsConfig(awsCfg))

// Create a table in Glue
tableIdent := catalog.ToIdentifier("my_database", "my_table")
tbl, err := cat.CreateTable(
    context.Background(),
    tableIdent,
    schema,
    catalog.WithLocation("s3://my-bucket/tables/my_table"),
)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Release RC1 with GitHub Token

Source: https://github.com/apache/iceberg-go/blob/main/dev/release/README.md

Example command to release the first release candidate (RC1) for version 1.0.0. Requires a GitHub token for authentication.

```bash
GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release_rc.sh 1.0.0 1
```

--------------------------------

### Lint Code with GolangCI-Lint

Source: https://github.com/apache/iceberg-go/blob/main/README.md

Perform code linting to maintain code style and identify potential issues. Install the linter first if needed.

```shell
make lint
```

```shell
make lint-install
# or: go install github.com/golangci/golangci-lint/cmd/golangci-lint@v2.8.0
```

--------------------------------

### Basic Iceberg Transaction in Go

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Group multiple operations into a single atomic commit using a transaction. This example shows appending data and setting table properties before committing. Requires 'github.com/apache/iceberg-go' import.

```go
import (
    "context"

    "github.com/apache/iceberg-go"
)

txn := tbl.NewTransaction()

// Append new data
err := txn.Append(context.Background(), recordReader, nil)
if err != nil {
    log.Fatal(err)
}

// Set table properties
err = txn.SetProperties(iceberg.Properties{
    "commit.user": "data-pipeline",
})
if err != nil {
    log.Fatal(err)
}

// Commit all changes atomically
newTable, err := txn.Commit(context.Background())
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Creating a REST Catalog

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Demonstrates how to initialize a REST catalog with authentication.

```APIDOC
## Creating a REST Catalog

### Description
Initializes a REST catalog client, allowing interaction with a remote Iceberg catalog service. Supports authentication via OAuth tokens.

### Method
`rest.NewCatalog`

### Parameters
- `ctx` (context.Context) - The context for the operation.
- `name` (string) - The name of the catalog.
- `uri` (string) - The base URI of the REST catalog service.
- `options` ([]rest.Option) - Optional configuration settings for the catalog.
  - `rest.WithOAuthToken(token string)`: Sets the OAuth token for authentication.

### Request Example
```go
import (
    "context"
    "github.com/apache/iceberg-go/catalog"
    "github.com/apache/iceberg-go/catalog/rest"
)

// Create a REST catalog
cat, err := rest.NewCatalog(context.Background(), "rest", "http://localhost:8181", 
    rest.WithOAuthToken("your-token"))
if err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### Build mdbook documentation

Source: https://github.com/apache/iceberg-go/blob/main/website/README.md

Builds the static HTML documentation for deployment.

```shell
mdbook build
```

--------------------------------

### Serve mdbook documentation

Source: https://github.com/apache/iceberg-go/blob/main/website/README.md

Serves the documentation locally, allowing for live preview during development.

```shell
mdbook serve
```

--------------------------------

### Import iceberg-go Package in Go

Source: https://github.com/apache/iceberg-go/blob/main/website/src/install.md

Add this import statement to your Go source files to use the iceberg-go package. This is required after installing the package.

```go
import "github.com/apache/iceberg-go"
```

--------------------------------

### Build and Test Iceberg-Go

Source: https://github.com/apache/iceberg-go/blob/main/CONTRIBUTING.md

Standard commands to clone the repository, build all Go modules, and run unit tests.

```bash
git clone https://github.com/apache/iceberg-go.git
cd iceberg-go
go build ./...
go test ./...
```

--------------------------------

### Run Iceberg-Go Integration Tests

Source: https://github.com/apache/iceberg-go/blob/main/CONTRIBUTING.md

Instructions for setting up Docker Compose for integration tests and running them with the 'integration' tag. Ensure Docker is running and the necessary services are up.

```bash
docker compose -f internal/recipe/docker-compose.yml up -d rest minio mc --wait
go test -tags integration ./...
```

--------------------------------

### Get Table Schema using Iceberg CLI

Source: https://github.com/apache/iceberg-go/blob/main/catalog/README.md

Retrieve the schema of a specific Iceberg table using the CLI. This command requires the catalog name, URI, and the fully qualified table name.

```bash
go run ./cmd/iceberg schema --catalog rest --uri http://localhost:8181 demo.nyc.taxis
```

--------------------------------

### Creating a Glue Catalog

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Initializes a catalog that integrates with AWS Glue.

```APIDOC
## Creating a Glue Catalog

### Description
Initializes a catalog that uses AWS Glue Data Catalog as its backend. Requires AWS SDK configuration.

### Method
`glue.NewCatalog`

### Parameters
- `options` ([]glue.Option) - Optional configuration settings for the Glue catalog.
  - `glue.WithAwsConfig(cfg aws.Config)`: Provides the AWS SDK configuration.

### Request Example
```go
import (
    "github.com/apache/iceberg-go/catalog"
    "github.com/apache/iceberg-go/catalog/glue"
    "github.com/aws/aws-sdk-go-v2/config"
)

// Create AWS config
awsCfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Fatal(err)
}

// Create Glue catalog
cat := glue.NewCatalog(glue.WithAwsConfig(awsCfg))
```
```

--------------------------------

### Create Table with REST Catalog and Minio

Source: https://github.com/apache/iceberg-go/blob/main/website/src/cli.md

Create a simple table with specified properties, partition spec, sort order, and schema using a REST catalog. Identity transform is the only supported partition transform currently.

```bash
./iceberg create table default.table-1 
        --properties write.format.default=parquet \
        --partition-spec foo \
        --sort-order foo:desc:nulls-last \
        --schema '[{"id":1,"name":"foo","type":"string","required":false},{"id":2,"name":"bar","type":"int","required":true}]' \
        --catalog rest \
        --uri http://localhost:8181
Table default.table-1 created successfully
```

--------------------------------

### Create REST Catalog

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Instantiate a REST catalog client. Requires specifying the catalog name, endpoint URL, and optionally authentication tokens.

```go
import (
    "context"
    "github.com/apache/iceberg-go/catalog"
    "github.com/apache/iceberg-go/catalog/rest"
)

// Create a REST catalog
cat, err := rest.NewCatalog(context.Background(), "rest", "http://localhost:8181", 
    rest.WithOAuthToken("your-token"))
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### List Root Namespaces

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Retrieve and print all top-level namespaces from the catalog. Ensure the catalog is initialized before calling.

```go
// List all root namespaces
namespaces, err := cat.ListNamespaces(context.Background(), nil)
if err != nil {
    log.Fatal(err)
}

for _, ns := range namespaces {
    fmt.Printf("Namespace: %v\n", ns)
}
```

--------------------------------

### Clone Repository and Prepare Release Candidate

Source: https://github.com/apache/iceberg-go/blob/main/dev/release/README.md

Clone the official Apache Iceberg Go repository and run the release candidate preparation script. This script requires the version and release candidate number as arguments. Ensure you are using a working copy not from your fork.

```bash
git clone git@github.com:apache/iceberg-go.git
dev/release/release_rc.sh ${VERSION} ${RC}
```

--------------------------------

### Publish Release to Apache.org

Source: https://github.com/apache/iceberg-go/blob/main/dev/release/README.md

Run the release script to publish the new version to apache.org. This command requires the version and release candidate number, along with a GitHub token.

```bash
GH_TOKEN=${YOUR_GITHUB_TOKEN} dev/release/release.sh ${VERSION} ${RC}
```

--------------------------------

### Load Catalog with catalog.Load

Source: https://context7.com/apache/iceberg-go/llms.txt

Use `catalog.Load` to obtain a `catalog.Catalog` instance. It resolves the catalog type from properties or URI scheme, falling back to configuration files. Ensure necessary catalog implementations are imported.

```go
import (
    "context"
    "github.com/apache/iceberg-go"
    "github.com/apache/iceberg-go/catalog"
    _ "github.com/apache/iceberg-go/catalog/rest"   // registers "rest", "http", "https"
    _ "github.com/apache/iceberg-go/catalog/glue"   // registers "glue"
    _ "github.com/apache/iceberg-go/catalog/hive"   // registers "hive"
    _ "github.com/apache/iceberg-go/catalog/sql"    // registers "sql"
    _ "github.com/apache/iceberg-go/catalog/hadoop" // registers "hadoop"
)

ctx := context.Background()

// Load a REST catalog
cat, err := catalog.Load(ctx, "my-rest", iceberg.Properties{
    "type": "rest",
    "uri":  "http://localhost:8181",
    "token": "my-oauth-token",
})
if err != nil { log.Fatal(err) }

// Load from a URI scheme (http → REST catalog)
cat, err = catalog.Load(ctx, "", iceberg.Properties{
    "uri": "http://localhost:8181",
})

// Load a SQL/SQLite catalog
cat, err = catalog.Load(ctx, "local", iceberg.Properties{
    "type":        "sql",
    "uri":         "file:iceberg.db",
    "sql.dialect": "sqlite",
    "warehouse":   "file:///tmp/warehouse",
})

fmt.Println(cat.CatalogType()) // rest / sql / etc.
```

--------------------------------

### Load SQL Catalog

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Initialize a SQL-based catalog, such as SQLite. Requires connection details and dialect information. Supports S3 credentials and warehouse configuration.

```go
import (
    "github.com/apache/iceberg-go/catalog"
    "github.com/apache/iceberg-go/io"
)

// Create a SQLite catalog
cat, err := catalog.Load(context.Background(), "local", iceberg.Properties{
    "type":               "sql",
    "uri":                "file:iceberg-catalog.db",
    "sql.dialect":        "sqlite",
    "sql.driver":         "sqlite",
    io.S3Region:          "us-east-1",
    io.S3AccessKeyID:     "admin",
    io.S3SecretAccessKey: "password",
    "warehouse":          "file:///tmp/warehouse",
})
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Create Schema with List and Map Types

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Demonstrates the creation of a schema that incorporates list and map types. Specify element types for lists and key/value types for maps.

```go
complexSchema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
    iceberg.NestedField{ID: 1, Name: "tags", Type: &iceberg.ListType{
        ElementID: 2, Element: iceberg.PrimitiveTypes.String, ElementRequired: true,
    }, Required: false},
    iceberg.NestedField{ID: 3, Name: "metadata", Type: &iceberg.MapType{
        KeyID: 4, KeyType: iceberg.PrimitiveTypes.String,
        ValueID: 5, ValueType: iceberg.PrimitiveTypes.String, ValueRequired: true,
    }, Required: false},
)
```

--------------------------------

### List Namespaces After Creation

Source: https://github.com/apache/iceberg-go/blob/main/website/src/cli.md

List namespaces again to verify the creation of 'taxitrips' using the iceberg CLI and a REST API catalog.

```bash
./iceberg --uri http://0.0.0.0:8181 list
┌───────────┐
| IDs       |
| --------- |
| taxitrips |
└───────────┘
```

--------------------------------

### Parse and Construct Iceberg Partition Transforms

Source: https://context7.com/apache/iceberg-go/llms.txt

Demonstrates parsing partition transform strings from an Iceberg spec and constructing them directly. Use these to define how column values map to partition values.

```go
import "github.com/apache/iceberg-go"

// Parse from spec string
identity, _ := iceberg.ParseTransform("identity")
year, _      := iceberg.ParseTransform("year")
month, _     := iceberg.ParseTransform("month")
day, _       := iceberg.ParseTransform("day")
hour, _      := iceberg.ParseTransform("hour")
bucket, _    := iceberg.ParseTransform("bucket[16]")
truncate, _  := iceberg.ParseTransform("truncate[8]")

// Direct construction
_ = iceberg.IdentityTransform{}
_ = iceberg.YearTransform{}
_ = iceberg.MonthTransform{}
_ = iceberg.DayTransform{}
_ = iceberg.HourTransform{}
_ = iceberg.BucketTransform{NumBuckets: 16}
_ = iceberg.TruncateTransform{Width: 8}
_ = iceberg.VoidTransform{}

// Build a partition spec
spec := iceberg.NewPartitionSpec(
    iceberg.PartitionField{
        SourceIDs: []int{3}, // "date" column field ID
        FieldID:   1000,
        Transform: iceberg.DayTransform{},
        Name:      "date_day",
    },
    iceberg.PartitionField{
        SourceIDs: []int{4}, // "region" column field ID
        FieldID:   1001,
        Transform: iceberg.IdentityTransform{},
        Name:      "region",
    },
)

fmt.Println(spec.NumFields()) // 2
fmt.Println(spec.IsUnpartitioned()) // false

// Create table with partition spec
tbl, err := cat.CreateTable(ctx, tableIdent, schema,
    catalog.WithPartitionSpec(&spec),
)
```

--------------------------------

### Create Namespace

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Create a new namespace within the catalog. The namespace is defined by an identifier.

```go
// Create a namespace
namespace := catalog.ToIdentifier("my_namespace")
err = cat.CreateNamespace(context.Background(), namespace, nil)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Loading a SQL Catalog

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Initializes a SQL-based catalog, such as SQLite.

```APIDOC
## Loading a SQL Catalog

### Description
Loads a catalog that uses a SQL database as its backend. This example shows how to configure a SQLite catalog.

### Method
`catalog.Load`

### Parameters
- `ctx` (context.Context) - The context for the operation.
- `name` (string) - The name of the catalog.
- `properties` (iceberg.Properties) - A map of properties to configure the catalog.
  - `type` (string) - Must be "sql".
  - `uri` (string) - The connection URI for the SQL database.
  - `sql.dialect` (string) - The SQL dialect (e.g., "sqlite").
  - `sql.driver` (string) - The database driver name.
  - `warehouse` (string) - The base location for table data.
  - AWS S3 related properties (e.g., `io.S3Region`, `io.S3AccessKeyID`, `io.S3SecretAccessKey`) can also be provided if needed for S3 integration.

### Request Example
```go
import (
    "github.com/apache/iceberg-go"
    "github.com/apache/iceberg-go/catalog"
    "github.com/apache/iceberg-go/io"
)

// Create a SQLite catalog
cat, err := catalog.Load(context.Background(), "local", iceberg.Properties{
    "type":               "sql",
    "uri":                "file:iceberg-catalog.db",
    "sql.dialect":        "sqlite",
    "sql.driver":         "sqlite",
    io.S3Region:          "us-east-1",
    io.S3AccessKeyID:     "admin",
    io.S3SecretAccessKey: "password",
    "warehouse":          "file:///tmp/warehouse",
})
if err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### Construct REST Catalog with Different Auth/Config

Source: https://context7.com/apache/iceberg-go/llms.txt

Use `rest.NewCatalog` to create a catalog instance. Supports static bearer tokens, OAuth2 client credentials, AWS SigV4 signing, and custom headers with TLS configuration. Fetches server-side config overrides on construction.

```go
import (
    "context"
    "github.com/apache/iceberg-go/catalog/rest"
)

ctx := context.Background()

// Static Bearer token
cat, err := rest.NewCatalog(ctx, "prod",
    "https://api.example.com/iceberg",
    rest.WithOAuthToken("eyJhbGci..."),
    rest.WithWarehouseLocation("s3://my-bucket/warehouse"),
)

// OAuth2 client-credentials
cat, err = rest.NewCatalog(ctx, "prod",
    "https://api.example.com/iceberg",
    rest.WithCredential("client_id:client_secret"),
    rest.WithScope("catalog"),
    rest.WithAudience("arn:aws:iam::123456789:role/IcebergRole"),
)

// AWS SigV4 signing (API Gateway-backed catalog)
cat, err = rest.NewCatalog(ctx, "aws",
    "https://xyz.execute-api.us-east-1.amazonaws.com",
    rest.WithSigV4RegionSvc("us-east-1", "execute-api"),
)

// Custom headers + TLS skip verify (for dev/test)
import "crypto/tls"
cat, err = rest.NewCatalog(ctx, "dev",
    "http://localhost:8181",
    rest.WithHeaders(map[string]string{"X-Custom-Header": "value"}),
    rest.WithTLSConfig(&tls.Config{InsecureSkipVerify: true}),
)

if err != nil { log.Fatal(err) }
fmt.Println(cat.Name()) // "prod" / "aws" / "dev"
```

--------------------------------

### Iceberg CLI: Manage Namespaces and Tables

Source: https://context7.com/apache/iceberg-go/llms.txt

Commands for managing Iceberg namespaces and tables using the `iceberg` CLI. Connect to catalogs via `--uri` or use defaults for specific catalog types like AWS Glue.

```shell
# Start the official REST test fixture
docker run -p 8181:8181 apache/iceberg-rest-fixture:latest

# List root namespaces
iceberg --uri http://localhost:8181 list

# Create a namespace
iceberg --uri http://localhost:8181 create namespace taxitrips

# Create a table (schema inferred from Parquet)
iceberg --uri http://localhost:8181 create table \
    taxitrips.rides \
    --infer-schema /tmp/sample.parquet \
    --location-uri s3://my-bucket/taxitrips/rides

# Describe a table
iceberg --uri http://localhost:8181 describe taxitrips.rides

# List files
iceberg --uri http://localhost:8181 files taxitrips.rides

# Show schema
iceberg --uri http://localhost:8181 schema taxitrips.rides

# List snapshots
iceberg --uri http://localhost:8181 snapshots taxitrips.rides

# Manage branches
iceberg --uri http://localhost:8181 branch create taxitrips.rides staging
iceberg --uri http://localhost:8181 branch list   taxitrips.rides

# Analyze compaction plan
iceberg --uri http://localhost:8181 compact analyze taxitrips.rides \
    --target-file-size $((256*1024*1024))

# Run bin-pack compaction
iceberg --uri http://localhost:8181 compact run taxitrips.rides

# Expire old snapshots
iceberg --uri http://localhost:8181 expire-snapshots taxitrips.rides \
    --older-than-ms 1700000000000

# Clean orphan files
iceberg --uri http://localhost:8181 clean-orphan-files taxitrips.rides

# Upgrade table format to v3
iceberg --uri http://localhost:8181 upgrade taxitrips.rides --format-version 3

# AWS Glue catalog (no URI needed)
iceberg --catalog glue list analytics

# Set table property
iceberg --uri http://localhost:8181 properties set table taxitrips.rides owner data-team

# Output as JSON
iceberg --uri http://localhost:8181 --output json describe taxitrips.rides
```

--------------------------------

### Create Table with Partitioning

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Creates a new Iceberg table with a defined schema and a partition specification. Requires specifying the table identifier, schema, partition spec, and location.

```go
import (
    "github.com/apache/iceberg-go"
    "github.com/apache/iceberg-go/catalog"
)

// Create schema
schema := iceberg.NewSchemaWithIdentifiers(1, []int{1},
    iceberg.NestedField{ID: 1, Name: "id", Type: iceberg.PrimitiveTypes.Int32, Required: true},
    iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
    iceberg.NestedField{ID: 3, Name: "date", Type: iceberg.PrimitiveTypes.Date, Required: false},
)

// Create a partition spec
partitionSpec := iceberg.NewPartitionSpec(
    iceberg.PartitionField{SourceID: 3, FieldID: 1000, Transform: iceberg.IdentityTransform{}, Name: "date"},
)

// Create a table with partitioning
tbl, err := cat.CreateTable(
    context.Background(),
    tableIdent,
    schema,
    catalog.WithPartitionSpec(&partitionSpec),
    catalog.WithLocation("s3://my-bucket/tables/partitioned_table"),
)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Describe Created Table

Source: https://github.com/apache/iceberg-go/blob/main/website/src/cli.md

Describe the details of a newly created table, including its format version, metadata location, UUID, and schema.

```bash
./iceberg describe --catalog rest --uri http://localhost:8181 default.table-1
Table format version | 2                                                                                               
Metadata location    | s3://warehouse/default/table-1/metadata/00000-f0ccaadd-d988-482e-99da-3a37870288fe.metadata.json
Table UUID           | 33fa3fac-e638-4335-a085-343c6d9e7de5                                                            
Last updated         | 1753133512562                                                                                   
Sort Order           | 1: [
                     | 1 desc nulls-last
                     | ]                                                                                               
Partition Spec       | [
                     |  1000: foo: identity(1)
                                                                          
                     | ]

Current Schema, id=0
├──1: foo: optional string
└──2: bar: required int

Current Snapshot | 

Snapshots

Properties
key                             | value  
-----------------------------------------
write.format.default            | parquet
write.parquet.compression-codec | zstd   

```

--------------------------------

### Table Operations with Catalog Interface

Source: https://context7.com/apache/iceberg-go/llms.txt

Manage tables including creation with schema and properties, loading, listing, renaming, and dropping. Use `catalog.ToIdentifier` for table and namespace references. Requires a catalog instance and table identifiers.

```go
import (
    "context"
    "fmt"

    "github.com/apache/iceberg-go"
    "github.com/apache/iceberg-go/catalog"
)

ctx := context.Background()

// --- Tables ---
schema := iceberg.NewSchema(0,
    iceberg.NestedField{ID: 1, Name: "id",  Type: iceberg.PrimitiveTypes.Int64, Required: true},
    iceberg.NestedField{ID: 2, Name: "msg", Type: iceberg.PrimitiveTypes.String},
)
tbl, err := cat.CreateTable(ctx,
    catalog.ToIdentifier("analytics", "events"),
    schema,
    catalog.WithLocation("s3://bucket/warehouse/analytics/events"),
    catalog.WithProperties(iceberg.Properties{"write.format.default": "parquet"}),
)

tbl, err = cat.LoadTable(ctx, catalog.ToIdentifier("analytics", "events"))
fmt.Println(tbl.Identifier())           // [analytics events]
fmt.Println(tbl.MetadataLocation())     // s3://...

for ident, err := range cat.ListTables(ctx, catalog.ToIdentifier("analytics")) {
    if err != nil { log.Fatal(err) }
    fmt.Println(ident)
}

renamed, err := cat.RenameTable(ctx,
    catalog.ToIdentifier("analytics", "events"),
    catalog.ToIdentifier("analytics", "events_v2"),
)

err = cat.DropTable(ctx, catalog.ToIdentifier("analytics", "events_v2"))
```

--------------------------------

### Schema Traversal with Visitors

Source: https://context7.com/apache/iceberg-go/llms.txt

Explains how to traverse a schema tree using `Visit` and `PreOrderVisit` with a custom `SchemaVisitor`. This allows for computations or actions on each node of the schema.

```APIDOC
## `iceberg.Visit` / `iceberg.PreOrderVisit` — Schema visitor traversal

Post-order and pre-order schema traversal using generic visitor interfaces. Implement `SchemaVisitor[T]` to compute a value from every node in the schema tree.

```go
import "github.com/apache/iceberg-go"

// Count total fields in a schema (including nested)
type fieldCounter struct{}

func (fieldCounter) Schema(_ *iceberg.Schema, structResult int) int { return structResult }
func (fieldCounter) Struct(_ iceberg.StructType, results []int) int {
    total := 0
    for _, r := range results { total += r }
    return total
}
func (fieldCounter) Field(_ iceberg.NestedField, result int) int { return result + 1 }
func (fieldCounter) List(_ iceberg.ListType, r int) int          { return r }
func (fieldCounter) Map(_ iceberg.MapType, k, v int) int         { return k + v }
func (fieldCounter) Primitive(_ iceberg.PrimitiveType) int       { return 0 }

schema := iceberg.NewSchema(0,
    iceberg.NestedField{ID: 1, Name: "id",   Type: iceberg.PrimitiveTypes.Int64, Required: true},
    iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String},
)

count, err := iceberg.Visit(schema, fieldCounter{})
if err != nil { log.Fatal(err) }
fmt.Println(count) // 2

// AssignFreshSchemaIDs re-numbers all field IDs sequentially
fresh, err := iceberg.AssignFreshSchemaIDs(schema, nil) // starts at 1
fmt.Println(fresh.Field(0).ID) // 1
```
```

--------------------------------

### Create Table with Schema and Properties

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Define a table schema and then create a new Iceberg table using a catalog. Supports specifying table properties and a custom location.

```go
import (
    "github.com/apache/iceberg-go"
    "github.com/apache/iceberg-go/catalog"
    "github.com/apache/iceberg-go/table"
)

// Create a simple schema
schema := iceberg.NewSchemaWithIdentifiers(1, []int{2},
    iceberg.NestedField{ID: 1, Name: "foo", Type: iceberg.PrimitiveTypes.String, Required: false},
    iceberg.NestedField{ID: 2, Name: "bar", Type: iceberg.PrimitiveTypes.Int32, Required: true},
    iceberg.NestedField{ID: 3, Name: "baz", Type: iceberg.PrimitiveTypes.Bool, Required: false},
)

// Create a table identifier
tableIdent := catalog.ToIdentifier("my_namespace", "my_table")

// Create a table with optional properties
tbl, err := cat.CreateTable(
    context.Background(),
    tableIdent,
    schema,
    catalog.WithProperties(map[string]string{"owner": "me"}),
    catalog.WithLocation("s3://my-bucket/tables/my_table"),
)
if err != nil {
    log.Fatal(err)
}
```

--------------------------------

### Run Unit Tests in Iceberg Go

Source: https://github.com/apache/iceberg-go/blob/main/README.md

Execute unit tests using the provided Makefile to ensure code quality and correctness. This command stays in sync with CI.

```shell
make test
```

--------------------------------

### Verify Release Candidate

Source: https://github.com/apache/iceberg-go/blob/main/dev/release/README.md

Execute the script to verify a release candidate. This script checks the integrity of the release artifacts. It automatically downloads Go if not present and uses it solely for verification.

```bash
dev/release/verify_rc.sh ${VERSION} ${RC}
```

--------------------------------

### Run Integration Tests in Iceberg Go

Source: https://github.com/apache/iceberg-go/blob/main/README.md

Execute all integration tests or specific test suites using the Makefile. Ensure Docker containers are running and environment variables are set.

```shell
make integration-test
# Or run a single suite: `make integration-scanner`, `make integration-io`, `make integration-rest`, `make integration-spark`.
```

--------------------------------

### Schema Construction

Source: https://context7.com/apache/iceberg-go/llms.txt

Demonstrates how to create `*Schema` objects using `NewSchema` and `NewSchemaWithIdentifiers`, including defining nested fields and identifier fields. It also shows helper functions for finding fields and column names within a schema.

```APIDOC
## `iceberg.NewSchema` / `iceberg.NewSchemaWithIdentifiers` — Construct a table schema

`NewSchema` creates an immutable `*Schema` from a schema ID and a list of `NestedField` values. `NewSchemaWithIdentifiers` additionally marks a subset of field IDs as the primary-key identifier fields. Duplicate field IDs cause a panic. Lazy indexes (id→field, name→id, id→name) are built on first use and cached atomically.

```go
import "github.com/apache/iceberg-go"

// Schema with primitive types and identifier field (primary key = bar)
schema := iceberg.NewSchemaWithIdentifiers(1, []int{2},
    iceberg.NestedField{ID: 1, Name: "foo",    Type: iceberg.PrimitiveTypes.String,  Required: false},
    iceberg.NestedField{ID: 2, Name: "bar",    Type: iceberg.PrimitiveTypes.Int32,   Required: true},
    iceberg.NestedField{ID: 3, Name: "active", Type: iceberg.PrimitiveTypes.Bool,    Required: false},
    iceberg.NestedField{ID: 4, Name: "score",  Type: iceberg.DecimalTypeOf(10, 4),   Required: false},
)

// Nested struct field
nestedSchema := iceberg.NewSchema(2,
    iceberg.NestedField{ID: 1, Name: "person", Required: false,
        Type: &iceberg.StructType{FieldList: []iceberg.NestedField{
            {ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: true},
            {ID: 3, Name: "age",  Type: iceberg.PrimitiveTypes.Int32,  Required: false},
        }},
    },
    iceberg.NestedField{ID: 4, Name: "tags", Required: false,
        Type: &iceberg.ListType{ElementID: 5, Element: iceberg.PrimitiveTypes.String, ElementRequired: true},
    },
    iceberg.NestedField{ID: 6, Name: "meta", Required: false,
        Type: &iceberg.MapType{
            KeyID: 7, KeyType: iceberg.PrimitiveTypes.String,
            ValueID: 8, ValueType: iceberg.PrimitiveTypes.String, ValueRequired: false,
        },
    },
)

// Lookup helpers
field, ok := schema.FindFieldByName("bar")           // case-sensitive
field, ok  = schema.FindFieldByNameCaseInsensitive("BAR") // case-insensitive
colName, _ := schema.FindColumnName(2)               // "bar"
typ, _      := schema.FindTypeByName("foo")           // iceberg.StringType{}

fmt.Println(schema.NumFields())   // 4
fmt.Println(schema.HighestFieldID()) // 4
```
```

--------------------------------

### Namespace Operations with Catalog Interface

Source: https://context7.com/apache/iceberg-go/llms.txt

Perform namespace management tasks like creation, existence checks, listing, property updates, and deletion using the `catalog.Catalog` interface. Requires a catalog instance and namespace identifiers.

```go
import (
    "context"
    "fmt"

    "github.com/apache/iceberg-go"
    "github.com/apache/iceberg-go/catalog"
)

ctx := context.Background()

// --- Namespaces ---
err := cat.CreateNamespace(ctx, catalog.ToIdentifier("analytics"),
    iceberg.Properties{"description": "analytics tables"})

exists, err := cat.CheckNamespaceExists(ctx, catalog.ToIdentifier("analytics"))
fmt.Println(exists) // true

namespaces, err := cat.ListNamespaces(ctx, nil) // all root namespaces
for _, ns := range namespaces {
    fmt.Printf("ns: %v\n", ns) // [analytics]
}

props, err := cat.LoadNamespaceProperties(ctx, catalog.ToIdentifier("analytics"))
summary, err := cat.UpdateNamespaceProperties(ctx,
    catalog.ToIdentifier("analytics"),
    []string{"old-key"},                  // removals
    iceberg.Properties{"owner": "team-a"}, // additions/updates
)
fmt.Println(summary.Updated, summary.Removed, summary.Missing)

err = cat.DropNamespace(ctx, catalog.ToIdentifier("analytics"))
```

--------------------------------

### Creating a Namespace

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Creates a new namespace within the catalog.

```APIDOC
## Creating a Namespace

### Description
Creates a new namespace in the catalog. Namespaces are used to organize tables.

### Method
`cat.CreateNamespace`

### Parameters
- `ctx` (context.Context) - The context for the operation.
- `namespace` (catalog.Identifier) - The identifier of the namespace to create.
- `properties` (map[string]string) - Optional properties for the namespace.

### Request Example
```go
// Create a namespace
namespace := catalog.ToIdentifier("my_namespace")
err = cat.CreateNamespace(context.Background(), namespace, nil)
if err != nil {
    log.Fatal(err)
}
```
```

--------------------------------

### Plan Iceberg Compaction Tasks

Source: https://context7.com/apache/iceberg-go/llms.txt

Configures and plans compaction tasks for Iceberg tables. Use `compaction.DefaultConfig` for production settings or customize thresholds like `TargetFileSizeBytes` and `MinInputFiles`.

```go
import (
    "context"
    "fmt"

    "github.com/apache/iceberg-go/table/compaction"
    "github.com/apache/iceberg-go/table"
)

ctx := context.Background()

// Default production config (512 MB target, 5 min files, etc.)
cfg := compaction.DefaultConfig()

// Or customize thresholds
cfg = compaction.Config{
    TargetFileSizeBytes: 256 * 1024 * 1024,  // 256 MB
    MinFileSizeBytes:    128 * 1024 * 1024,  // 75% of target
    MaxFileSizeBytes:    512 * 1024 * 1024,  // 200% of target
    MinInputFiles:       3,
    DeleteFileThreshold: 5,
    PackingLookback:     compaction.DefaultPackingLookback,
}

// Plan using file scan tasks from a table scan
scanTasks := tbl.Scan().PlanFiles(ctx)
var tasks []table.FileScanTask
for t, err := range scanTasks {
    if err != nil { log.Fatal(err) }
    tasks = append(tasks, t)
}

plan, err := cfg.PlanCompaction(tasks)
if err != nil { log.Fatal(err) }

for i, group := range plan.Groups() {
    fmt.Printf("Group %d: %d files, %d bytes\n",
        i, len(group.InputFiles), group.InputSize)
}
```

--------------------------------

### Create Namespace with REST Catalog

Source: https://github.com/apache/iceberg-go/blob/main/website/src/cli.md

Create a new namespace named 'taxitrips' using the iceberg CLI and a REST API catalog.

```bash
./iceberg --uri http://0.0.0.0:8181 create namespace taxitrips
```

--------------------------------

### Materialize All Record Batches into an Arrow Table

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Materialize all record batches into a single Arrow Table in memory. Ensure to release the table when done.

```go
// Materialize all record batches into a single Arrow Table.
scan := tbl.Scan()
arrowTable, err := scan.ToArrowTable(context.Background())
if err != nil {
    log.Fatal(err)
}
defer arrowTable.Release()

fmt.Printf("Read %d rows in %d columns\n",
    arrowTable.NumRows(), arrowTable.NumCols())
```

--------------------------------

### List Tables in a Namespace

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Retrieves a list of table identifiers within a specified namespace. Handles potential errors during the listing process.

```go
// List tables in a namespace
tables := cat.ListTables(context.Background(), catalog.ToIdentifier("my_namespace"))
for tableIdent, err := range tables {
    if err != nil {
        log.Printf("Error listing table: %v", err)
        continue
    }
    fmt.Printf("Table: %v\n", tableIdent)
}
```

--------------------------------

### List Namespaces with REST Catalog

Source: https://github.com/apache/iceberg-go/blob/main/website/src/cli.md

Use the iceberg CLI to list namespaces from a REST API catalog running on http://0.0.0.0:8181.

```bash
./iceberg --uri http://0.0.0.0:8181 list
┌─────┐
| IDs |
| --- |
└─────┘
```

--------------------------------

### List Table Files using Iceberg CLI

Source: https://github.com/apache/iceberg-go/blob/main/catalog/README.md

View the data files associated with an Iceberg table using the CLI. This command shows snapshot and manifest information.

```bash
go run ./cmd/iceberg files --catalog rest --uri http://localhost:8181 demo.nyc.taxis
```

--------------------------------

### List All Snapshots

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Iterates through all snapshots associated with a table and prints their IDs and the operation performed in each snapshot.

```go
// List all snapshots
for _, snapshot := range tbl.Snapshots() {
    fmt.Printf("Snapshot %d: %s\n", snapshot.SnapshotID, snapshot.Summary.Operation)
}
```

--------------------------------

### Create Simple Schema with Primitive Types

Source: https://github.com/apache/iceberg-go/blob/main/website/src/api.md

Defines a basic Iceberg schema containing integer, string, and boolean fields. Ensure all required fields are specified.

```go
simpleSchema := iceberg.NewSchemaWithIdentifiers(1, []int{2},
    iceberg.NestedField{ID: 1, Name: "id", Type: iceberg.PrimitiveTypes.Int32, Required: true},
    iceberg.NestedField{ID: 2, Name: "name", Type: iceberg.PrimitiveTypes.String, Required: false},
    iceberg.NestedField{ID: 3, Name: "active", Type: iceberg.PrimitiveTypes.Bool, Required: false},
)
```

--------------------------------

### rest.NewCatalog

Source: https://context7.com/apache/iceberg-go/llms.txt

Constructs a *rest.Catalog with full control over OAuth2, SigV4 signing, TLS, and custom transports. The catalog fetches server-side config overrides from /v1/config during construction.

```APIDOC
## rest.NewCatalog

### Description
Creates a `*rest.Catalog` with full control over OAuth2, SigV4 signing, TLS, and custom transports. The catalog fetches server-side config overrides from `/v1/config` during construction.

### Usage Examples

**Static Bearer token**
```go
ctx := context.Background()
cat, err := rest.NewCatalog(ctx, "prod",
    "https://api.example.com/iceberg",
    rest.WithOAuthToken("eyJhbGci..."),
    rest.WithWarehouseLocation("s3://my-bucket/warehouse"),
)
```

**OAuth2 client-credentials**
```go
ctx := context.Background()
cat, err := rest.NewCatalog(ctx, "prod",
    "https://api.example.com/iceberg",
    rest.WithCredential("client_id:client_secret"),
    rest.WithScope("catalog"),
    rest.WithAudience("arn:aws:iam::123456789:role/IcebergRole"),
)
```

**AWS SigV4 signing (API Gateway-backed catalog)**
```go
ctx := context.Background()
cat, err := rest.NewCatalog(ctx, "aws",
    "https://xyz.execute-api.us-east-1.amazonaws.com",
    rest.WithSigV4RegionSvc("us-east-1", "execute-api"),
)
```

**Custom headers + TLS skip verify (for dev/test)**
```go
import "crypto/tls"
ctx := context.Background()
cat, err := rest.NewCatalog(ctx, "dev",
    "http://localhost:8181",
    rest.WithHeaders(map[string]string{"X-Custom-Header": "value"}),
    rest.WithTLSConfig(&tls.Config{InsecureSkipVerify: true}),
)
```

### Parameters

This function accepts `context.Context`, catalog name (string), catalog URL (string), and a variable number of `rest.Option` functions.

### Options (`rest.Option`)

- `rest.WithOAuthToken(token string)`: Sets a static OAuth2 bearer token.
- `rest.WithWarehouseLocation(location string)`: Sets the warehouse location.
- `rest.WithCredential(credential string)`: Sets client ID and secret for OAuth2 client credentials.
- `rest.WithScope(scope string)`: Sets the OAuth2 scope.
- `rest.WithAudience(audience string)`: Sets the OAuth2 audience.
- `rest.WithSigV4RegionSvc(region, service string)`: Configures AWS SigV4 signing.
- `rest.WithHeaders(headers map[string]string)`: Adds custom HTTP headers.
- `rest.WithTLSConfig(config *tls.Config)`: Configures TLS settings, e.g., `InsecureSkipVerify`.

### Returns

- `*rest.Catalog`: A pointer to the initialized REST catalog.
- `error`: An error if the catalog construction fails.
```