Iceberg Golang

iceberg is a Golang implementation of the Iceberg table spec.

Build From Source

Prerequisites

• Go 1.25 or later

Build

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

Running Tests

Use the Makefile so commands stay in sync with CI (e.g. golangci-lint version).

Unit tests

make test

Linting

make lint

Install the linter first

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

Integration tests

Prerequisites: Docker, Docker Compose

1. Start the Docker containers using docker compose:

shell make integration-setup

1. Export the required environment variables:

shell export AWS_S3_ENDPOINT=http://$(docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' minio):9000 export AWS_REGION=us-east-1 export SPARK_CONTAINER_ID=$(docker ps -qf 'name=spark-iceberg') export DOCKER_API_VER=$(docker version -f '{{.Server.APIVersion}}')

1. Run the integration tests:

shell make integration-test

Or run a single suite: make integration-scanner, make integration-io, make integration-rest, make integration-spark.

Feature Support / Roadmap

FileSystem Support

Metadata

Catalog Support

Read/Write Data Support

• Data can currently be read as an Arrow Table or as a stream of Arrow record batches.

Supported Write Operations

As long as the FileSystem is supported and the Catalog supports altering the table, the following tracks the current write support:

CLI Usage

Run go build ./cmd/iceberg from the root of this repository to build the CLI executable, alternately you can run go install github.com/apache/iceberg-go/cmd/iceberg@latest to install it to the bin directory of your GOPATH.

The iceberg CLI usage is very similar to pyiceberg CLI \ You can pass the catalog URI with --uri argument.

Example: You can start the Iceberg REST API docker image which runs on default in port 8181

docker pull apache/iceberg-rest-fixture:latest
docker run -p 8181:8181 apache/iceberg-rest-fixture:latest

and run the iceberg CLI pointing to the REST API server.

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

Create Namespace

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

List Namespace

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

Get in Touch

• Iceberg community