Apache Iceberg Tutorial: Build Your First Table with Spark

This short tutorial creates a local Iceberg table with Spark SQL. It assumes Spark is installed; the Iceberg runtime package must match your Spark and Scala versions.

1. Start Spark with Iceberg

Start spark-sql with the Iceberg Spark runtime and a local Hadoop catalog. Replace the package placeholders with versions compatible with your Spark installation:

spark-sql \
  --packages org.apache.iceberg:iceberg-spark-runtime-<spark-version>_<scala-version>:<iceberg-version> \
  --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
  --conf spark.sql.catalog.local=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.local.type=hadoop \
  --conf spark.sql.catalog.local.warehouse=./warehouse

The local catalog stores table data and metadata in the warehouse directory relative to where Spark is started. This setup is for local learning, not a shared production catalog.

2. Create a table and add rows

At the spark-sql prompt, create a namespace and an Iceberg table, then insert a couple of rows:

CREATE NAMESPACE IF NOT EXISTS local.demo;

CREATE TABLE local.demo.events (
  event_id BIGINT,
  event_name STRING
) USING iceberg;

INSERT INTO local.demo.events
VALUES (1, 'table-created'), (2, 'first-write');

3. Read the table

Query the table to confirm the rows were written:

SELECT * FROM local.demo.events ORDER BY event_id;

You now have a working Iceberg table. Spark’s catalog resolves the table name, while Iceberg metadata tracks the table state and the files that contain its data.

For more options, see the Iceberg Spark getting-started guide and the Spark configuration reference.