Guides · Apache Iceberg

How to load CSV or Parquet files into an Apache Iceberg table

Turn CSV or Parquet files into an Apache Iceberg table with one command, from a browser tab, or by asking your AI agent. One commit for the whole set.

2 min read

The short answer.

lhbox table import analytics.sensors.readings 'data/2026/*.parquet'

One command, one commit, however many files match. The rest is the detail: appending later, CSV, and doing the same from a browser or through an agent.

Why one commit matters

Every Iceberg commit adds a snapshot, and commits get slower as snapshots pile up. A loop that inserts file by file makes one commit, and one wait, per file. Reading every file in one statement lands the whole set as one snapshot.

From the command line

lhbox doctor                                                                         # finds DuckDB 1.5.5+ on your machine
lhbox table import analytics.sensors.readings 'data/2026/*.parquet'                  # a new table
lhbox table import analytics.sensors.readings 'data/2026-11/*.parquet' --mode append # more files later
lhbox table get analytics.sensors.readings                                           # schema, snapshots, rows
  • Formats: Parquet, and CSV or TSV, also compressed (.gz, .zst, .bz2). Columns are matched by name across files.
  • Sources: local files, globs (** works) and URLs DuckDB reads directly (s3://…, https://…).
  • Quote the glob, so that lhbox expands it, not your shell.
  • DuckDB runs on your machine; the catalog credential never appears on screen.
  • Tables are written to be read: large files (128 MiB target), ZSTD compression, rows sorted by a date column.

From the account page

Drop the files on the account page and choose Import into…. It writes the table the same way, as one commit, from your browser.

Ask your agent

  • An agent with a shell (Claude Code, Codex and the like) installs the CLI and runs the same import. You approve the connection once in the browser; no key is pasted into the chat.
  • An agent in a chat, connected through the LakehouseBox MCP server, reads your tables with SQL. When you approve write, it can also change them with SQL, one statement per call.

When something goes wrong

Every error says what to do next:

error meaning what to do
table_exists the table is already there add --mode append
columns_not_in_table the files have a column the table lacks add the column, or import into a new table
mixed_formats CSV and Parquet in one run import each format in its own run
import_outcome_unknown the commit's result was unclear check with lhbox table get before running again, so rows are not written twice

Once the files are a table, any engine that speaks the Iceberg REST catalog can read it, and your agents can come back to it next week.

Explore how it works

Related articleAlways-learning analytics: why agents don't have to start over