Getting started

From an email address to a queryable Apache Iceberg catalog in a few minutes, from the terminal or from an agent. Everything here works against https://api.tablemere.eu today; nothing is described that the service does not do.

What you get

A catalog is one Iceberg REST catalog with its own object storage, run in Nuremberg, Germany, by Tablemere SL: it organises your tables and connects them to your tools; Tablemere includes the storage and the table maintenance. You bring the engine: DuckDB, PyIceberg or Spark read and write it directly; Tablemere is never in the query path. Credentials are per catalog, storage sessions are per table and short-lived, and every tenant is separated at the catalog. (The API calls a catalog a warehouse: /v1/warehouses, warehouse_id; the CLI accepts both words.) The free plan meters one thing, storage: 5 GB. No card.

1. Install the command line

One Python file, standard library only, verified against a published SHA-256. Python 3.9 or newer. No sudo.

curl -fsSL https://tablemere.com/install.sh | sh
export TABLEMERE_URL=https://api.tablemere.eu
tablemere --version

Or with pip tooling: pipx install tablemere (the package on PyPI follows the same file; until the first release is published there, install from the URL above). The installer puts tablemere in ~/.local/bin and prints a PATH hint if that directory is not on your PATH. The CLI talks to https://api.tablemere.eu by default; set TABLEMERE_URL only for a self-hosted or local stack. Details: CLI reference.

2. Create your account and catalog

Two calls. A six-digit code goes to your inbox (from no-reply@tablemere.eu), valid for ten minutes, five attempts. Verifying it creates your account, an organisation you own, and a catalog named lake. Accepting the Terms of Service is required and recorded with the version you accepted; an agent should show them to a person and ask.

tablemere signup --email you@company.com --workspace acme
# A 6-digit code was sent to your inbox for you@company.com (valid 10 minutes). Finish with:
tablemere signup --email you@company.com --code 123456 --accept-terms --save

--save writes the API key to ~/.config/tablemere/credentials.json (mode 0600, keyed by API URL) so later commands find it. Without it, export TABLEMERE_API_KEY=al_live_… works, but the line lands in your shell history; prefer the file. The key is shown once and cannot be recovered, only replaced (tablemere recover --email …, or /recover). Over HTTP: POST /v1/signup/start then POST /v1/signup/verify (API reference). In a browser, /signup asks for your name, email, organisation name and handle and mails you a link to set your password; you then log in at /app/ with your email and password and create tokens for your agents there; no API key is shown to a person on that path. tablemere login logs the CLI in through the browser (a code shown in the terminal, approved at /app/device) and saves an API key of yours with --save.

3. Connect your engine

tablemere connect --catalog lake --engine duckdb      # or pyiceberg, spark

Prints a paste-ready recipe with the catalog's credential inside. For DuckDB it is four statements; the one that matters is ATTACH 'w-<uuid>' AS lake (TYPE ICEBERG, …) with the bare bucket name: the s3:// form attaches read-only. Engines exchange the credential for catalog tokens (900 s) and per-table storage sessions themselves. All three recipes and their gotchas: Engines.

4. Load and query

CREATE TABLE lake.demo.cities AS SELECT * FROM read_parquet('cities.parquet');
SELECT country, count(*) FROM lake.demo.cities GROUP BY 1 ORDER BY 2 DESC;

That is an Iceberg table now: versioned, compacted by the catalog's maintenance, readable by any engine pointed at the catalog. To choose identifier fields, required columns or partitioning, create the table first with tablemere table create --column id:long:required:identifier … and then INSERT. Check what landed with tablemere table get --catalog lake --namespace demo --name cities.

5. Give agents their own keys

tablemere agent create --name reporter --grant <warehouse_id>:write
# Agent reporter created (member of the organisation; grants: lake:write). Its API key, shown once: al_live_…

An agent key holds exactly the grants you give it, read or write per catalog (none until granted), is revoked on its own (tablemere agent revoke --agent-id …) and never manages the organisation or its people. Invite colleagues with tablemere org invite --email …; claim your company's email domain with tablemere org domain --domain … so verified colleagues can join.

For agents

Output is JSON whenever stdout is not a terminal; every error is a typed object with a code, a message and usually a remedy; the exit code carries the class (1 fix the input, 2 a real limit or conflict, 3 auth, 4 not found, 5 retry, 6 malformed command). tablemere usage (GET /v1/usage) lists every limit with its headroom so a limit is never met by failing. Every mutation takes --idempotency-key. The whole documentation as one plain-text file: /llms-full.txt; the index: /llms.txt.

Limits on the free plan

Storage is measured hourly by maintenance and summed over the organisation; over the limit, creating catalogs or tables and vending write credentials answer 409 quota_exceeded (reading still works) until space is freed. Guards are abuse limits, not prices; the live values are whatever GET /v1/usage returns. Paid plans are to be announced.

Not available today

• A Snowflake data path (the catalog integration connects; reading data needs work on both sides).
• Sign in with Google or any social login; accounts are created with your email address (a password set from the signup mail in the browser, a six-digit code in the CLI). A self-hosted deployment may trust its own OpenID Connect issuer instead.
• A full web dashboard. There is /app/, "Your account" (small, for people; agents use the API): log in with email and password (the session stays in the tab), see the organisation's catalogs with your level on each, create one, delete one by typing its name, create tokens for agents with read or write per catalog (the key is shown once), invite and manage members, read usage against the 5 GB, and run SQL with DuckDB compiled to WebAssembly in the browser (the site never sees the data; it talks to the catalog and the object store with your own scoped credentials). It refuses writes as a courtesy, not as a permission; the API and the CLI remain the primary interface.
• An SLA; we publish what we measure instead. One site, daily off-host backups, rehearsed restore.
• Paid plans (waiting for the company registration).

Help

hello@tablemere.eu. Security reports: security@tablemere.eu (security.txt). Legal: Terms, Privacy, Acceptable use, Data processing, Security overview, Legal notice.