icegraph
/icegraph
Use the icegraph-client CLI to talk to a remote IceGraph server — list tables, fetch snapshot history, build the metadata graph, and describe non-Iceberg tables — and construct working deep-link URLs into the IceGraph web UI (e.g. pointing at a specific table, snapshot range, or graph node). Use when the user references an IceGraph server or table, asks to inspect/debug an Iceberg table via command line, or wants a link/URL that shows them a specific view or node instead of raw JSON.
- Author
- yanivzalach ↗
- Repository
- icegraph ↗
- Licence
- AGPL-3.0
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 8
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
AGPL-3.0, copyleft: przeróbki udostępniane innym muszą mieć tę samą licencję.
What it does and when to use it
Use the icegraph-client CLI to talk to a remote IceGraph server — list tables, fetch snapshot history, build the metadata graph, and describe non-Iceberg tables — and construct working deep-link URLs into the IceGraph web UI (e.g. pointing at a specific table, snapshot range, or graph node). Use when the user references an IceGraph server or table, asks to inspect/debug an Iceberg table via command line, or wants a link/URL that shows them a specific view or node instead of raw JSON.
Original author description
Use the icegraph-client CLI to talk to a remote IceGraph server — list tables, fetch snapshot history, build the metadata graph, and describe non-Iceberg tables — and construct working deep-link URLs into the IceGraph web UI (e.g. pointing at a specific table, snapshot range, or graph node). Use when the user references an IceGraph server or table, asks to inspect/debug an Iceberg table via command line, or wants a link/URL that shows them a specific view or node instead of raw JSON.
How it works
- 0. The server is remote — never assume otherwise
- 1. Prerequisites
- 2. Commands
- 3. If a command fails and it looks like an auth problem
- 3a. If a command fails and it looks like a TLS/SSL problem
- 4. Building a link into the web UI
- 5. Tracing a snapshot back to the Spark job that wrote it
- 6. Cache a table's data to a tmp file for the rest of the session
- Example flow
SKILL.md preview
---
name: icegraph
description: Use the icegraph-client CLI to talk to a remote IceGraph server — list tables, fetch snapshot history, build the metadata graph, and describe non-Iceberg tables — and construct working deep-link URLs into the IceGraph web UI (e.g. pointing at a specific table, snapshot range, or graph node). Use when the user references an IceGraph server or table, asks to inspect/debug an Iceberg table via command line, or wants a link/URL that shows them a specific view or node instead of raw JSON.
user-invocable: true
---
# icegraph
Wraps the `icegraph` CLI (from the `icegraph-client` PyPI package) for scripted access to an
IceGraph server, and covers how to turn what the CLI returns into a working link into the actual
IceGraph web UI. The CLI and the UI talk to the exact same backend API — this skill treats them as
one workflow, not two separate tools.
While using this skill, act as a big-data expert in Iceberg table metadata, infrastructure, and
engineering — not just a relay for CLI output. Interpret schemas, partition specs, snapshot
lineage, and errors/warnings with real domain judgment (what a given partition transform implies
for query planning, what a sequence-number or orphaned-file issue suggests actually went wrong,
why a given schema evolution or table property is or isn't a good idea). Summarize and explain,
don't just paste JSON back at the user.
**Naming:** table names are `catalog → database → table`. The `table` argument the CLI/UI take is
the fully-qualified `database.table` (add the catalog prefix only when the user is on a non-default
catalog: `catalog.database.table`). Always call the middle part the **database** — never abbreviate
it to "db" or guess at a shortened form. Use the exact name the user gives you, or whatever a
`tables` call actually returned — don't assume a database is named "default" or anything else.
## 0. The server is remote — never assume otherwise
IceGraph servers almost never run on the same machine as this session. Unless the user has already
told you a `--base-url` / `$ICEGRAPH_BASE_URL` this conversation, **ask for it** — don't guess
`localhost` and don't try to auto-start anything. The only exception is when you're clearly doing
IceGraph *development* work inside this repo itself (e.g. `docker_demo` is running) — only then is
suggesting a local URL reasonable.
Once you have it, reuse it for the rest of the task instead of re-asking per command.
**Remember the URL across sessions.** The moment the user gives you a base URL, save it to memory
(one entry, e.g. "IceGraph server base URL: `<url>`", along with any token/cookie *source*, but
never the secret value itself). In a later session, treat that saved URL as the server the user
means and use it without re-asking. Only assume a different server when the user actually says so:
a new URL in the prompt, or an explicit "different/other server". When they do, use the new one and
update the saved entry to match. Don't quietly swap servers, and don't re-ask for a URL you already
have.
## 1. Prerequisites
- **Check the server version once at the start of every session**, before running real commands.
The server may have been upgraded since the last session, and the client is only guaranteed
compatible with the matching server release. Read it from `<base_url>/docs` → Overview →
**Version** (open it with browser automation if available; otherwise fetch the page and grep the
served JS bundle for the version string). Compare it against the installed client
(`pip show icegraph-client`). If they differ, tell the user and suggest
`pip install icegraph-client==<server version>`, but don't install it yourself. If the version
isn't reachable, say so once and continue rather than blocking. Do this check once per session,
not per command.
- Confirm `icegraph` is on PATH with `icegraph --help` before relying on it.
- **If it's not installed, don't just suggest a bare `pip install icegraph-client`.** Check
`<base_url>/docs` first — the Overview section shows a **Version** field — and suggest the
version-pinned install command instead: `pip install icegraph-client==<version>`. The client is
only guaranteed compatible with the matching server release, so pinning matters. Only fall back
to suggesting an unpinned install (and mention that caveat) if the docs page isn't reachable
either. Suggest the command for the user to run — don't install it yourself.
## 2. Commands
```
icegraph [--base-url URL] [--token TOKEN] [--cookie COOKIE] [--no-verify-ssl] tables
icegraph [...] snapshots <table> [-b/--before-snapshot-id ID]
icegraph [...] metadata <table>
icegraph [...] sparkdesc <table>
icegraph [...] graph <table> [-s/--start-snapshot-id ID] [-e/--end-snapshot-id ID]
```
Every flag also has an env var fallback: `ICEGRAPH_BASE_URL`, `ICEGRAPH_TOKEN`, `ICEGRAPH_COOKIE`,
`ICEGRAPH_NO_VERIFY_SSL`.
Each command prints its result as **JSON on stdout only** — status messages ("Fetching tables...",
etc.) go to stderr, so stdout is always safe to parse directly.
**Output shapes:**
- `tables` → a JSON array of table name strings.
- `snapshots <table>` → `{snapshots: [...], next_before_snapshot_id}`. `snapshots` is one page of
`{timestamp, snapshot_id, operation}` objects (timestamp is ISO 8601, converted to local time),
starting from the table's newest snapshots. To reach older snapshots, pass
`next_before_snapshot_id` as `--before-snapshot-id`; it is `null` when no older snapshots remain.
- `metadata <table>` → the latest table metadata dictionary, including `metadata_file_path` and
`current-snapshot` (the current snapshot's entry from the metadata file, with its `summary`
counts such as `total-records`, `total-data-files`, and `total-files-size-bytes`), and
`warnings`, which maps a source to messages, such as a warning that only format versions 1, 2, and 3
are currently supported.
- `sparkdesc <table>` → `{spark_schema, spark_partitions, sections, properties, warnings}` for any table Spark
can resolve, Iceberg or not. Use it when another command reports that the table is not an Iceberg
table. `spark_schema` is the table schema as Spark reports it, with Spark type names (`int`,
`bigint`, `timestamp`, ...), in the Iceberg schema JSON layout (`struct`/`list`/`map`, `required`,
`doc`), without field IDs. `spark_partitions` lists the partitions as Spark reports them as
`[{name, value, comment}]`, empty when unpartitioned. `sections` lists the other
`DESCRIBE FORMATTED` sections as `{title, rows: [{name, value, comment}]}`, and `properties` maps
table property keys to values. If Spark cannot read the schema, `spark_schema` is `null` and the
column rows appear as a `Columns` section; if it cannot read the properties, `properties` is
`null` and the raw `Table Properties` row stays in its section. Each such fallback adds the Spark
error to `warnings`, which maps `spark_schema` or `properties` to a list of messages.
- `graph <table>` → `{nodes: [...], metadata: {...}, issues: {errors: {...}, warnings: {...}}}`.
`errors` and `warnings` each map a source, such as a file path, to a list of messages.
Each entry in `nodes` is one file's fields as a flat dict, with no wrapper object around them, so
a field is read directly as `node["summary"]`. Every node carries `file_path`, `type`, and
`child_files`, plus fields specific to its type. A node's identity for
linking purposes is its `file_path`, the underlying Iceberg file's storage path. **If you call
`graph` with no start/end snapshot id, it auto-selects only the latest snapshot** (the CLI prints
which one to stderr) — don't assume it covers full history unless you passed a range.
When summarizing a `graph` result to the user, lead with `issues.errors`, then `issues.warnings`,
before general structure/counts — errors are what the Issues panel in the UI leads with too.
For a question about a table that the latest metadata can answer, try `metadata <table>` first.
This is faster than building a graph. Examples include columns and schemas, partition specs,
sort orders, table properties, branches and tags, table location, and format version. Use
`snapshots` for snapshot history or recent operations, and `graph` for files, lineage, issues,
or a requested snapshot range. The `metadata` command returns the metadata dictionary directly;
`graph` places it under the top-level `metadata` key. Both include `metadata_file_path`, which
identifies the file used for that result.
**For "what's my table's schema/properties/partition spec" questions, use the metadata result or
the graph's top-level `metadata` key, not a node's own fields.** This dictionary is close to a raw
dump of the table's current `metadata.json` (original Iceberg field names, hyphenated) — `schemas` (full column definitions),
`partition-specs`, `sort-orders`, `properties`, `refs`, `format-version`, `location`, `table-uuid`,
`current-schema-id`, `default-spec-id`, `current-snapshot` (row and file counts in its `summary`),
etc. A metadata-file *node*, by contrast,
only carries IDs (`current_schema_id`, `partition_spec_id`, `sort_order_id`) plus `properties`/
`refs` — it does **not** contain the actual schema or partition-spec definitions, so it's the wrong
place to look for those.
**Failure modes:**
- Exit code `2` with "No IceGraph server address was given" → the base URL wasn't resolved; go
back to step 0.
- Exit code `1` with `Error: ...` on stderr → the request itself failed (network, auth rejection,
bad table name, etc.). Don't retry blindly — surface the message and move to step 3 if it looks
auth-related (connection refused, 401/403), or step 3a if it looks TLS-related (`SSLError`,
`CERTIFICATE_VERIFY_FAILED`, "self-signed certificate", etc.).
## 3. If a command fails and it looks like an auth problem
**Try without a token/cookie first** — most servers don't need one. IceGraph itself has no login
system; a token or cookie is only needed when whoever runs the server has put it behind their own
outside proxy. If a request looks rejected for that reason:
- If the user can already reach the IceGraph UI in a browser, that proxy has already authenticated
their session — the value is sitting in that browser. Tell them to open DevTools →
Application/Storage → Cookies (or Network tab → any request → Request Headers) on the IceGraph
page to find the cookie or `Authorization` value in use.
- Otherwise, tell them to check with whoever set up their IceGraph server — the proxy is theirs,
IceGraph has no visibility into it.
- Once they give you a value, pass it via `--token`/`--cookie` or `$ICEGRAPH_TOKEN`/`$ICEGRAPH_COOKIE`.
Never guess or fabricate a token/cookie value.
## 3a. If a command fails and it looks like a TLS/SSL problem
An `SSLError`/`CERTIFICATE_VERIFY_FAILED`/"self-signed certificate" failure means the server's TLS
certificate isn't trusted by this machine, most often a self-signed or internal-CA cert on an
internal IceGraph server.
**Never add `--no-verify-ssl` on your own.** It disables certificate verification for the request,
which has real security implications (no protection against a MITM'd connection) — explain that
plainly and ask the user whether they want to proceed with it before you re-run the command.
Only add it after they say yes; if they decline, stop and suggest they fix the underlying cert
trust instead (import the internal CA, use the correct hostname, etc.) — that's their call, not
something to solve for them.
## 4. Building a link into the web UI
Don't wait to be asked — default to including one. Practically any answer about a specific table,
snapshot, node, error, or schema is more useful with a link the user can actually look at, so treat
including one as the norm and leaving it out as the exception, not the other way around. Treat
"show me"/"link me to" as confirmation you're on the right track, not as a precondition. The only
time to skip it is when there's genuinely nothing to point at — a bare `tables` listing with no
particular table in focus.
```
<base_url>/table/graph?table=<uri-encoded database.table>&start_snapshot_id=<id>&end_snapshot_id=<id>&select_node_id=<uri-encoded node_id>
```
- Reuse the exact same `base_url` you already resolved for the CLI. There is no extra path prefix
to guess — the `/IceGraph` prefix only exists on the public GitHub Pages *demo* build (a static,
mocked deployment); a real server has none.
- To link to a table before graph generation, use
`<base_url>/snapshots-selection?table=<uri-encoded database.table>`.
- URI-encode `table` and `select_node_id`.
- `select_node_id` is a node's `node_id` — get it from a `graph` command's `nodes` output. It is
the node's Iceberg file path, except for a deletion vector, which shares its Puffin file with
other deletion vectors: its `node_id` is `<file path>#<content_offset>`. It stays valid as long as that file is still part of
the selected snapshot range.
### FileTree links
When linking to `/table/filetree`, the following optional parameters reproduce the user's
FileTree view:
- `filetree_branch=<branch name>` selects a branch. An empty value selects all branches. If the
parameter is omitted, FileTree selects `main` when that branch exists.
- `filetree_snapshot_id=<snapshot id>` selects a snapshot from the loaded range and selected
branch. Use an ID returned by the CLI, and keep both `start_snapshot_id` and `end_snapshot_id`
in the URL so the snapshot is available to the page.
- `filetree_scope=commit|snapshot` selects files added in the commit or all files present at the
snapshot. The default is `snapshot`.
- `filetree_grouping=flat|tree` selects flat partition groups or the partition-path tree. The
default is `tree`.
- `filetree_search=<uri-encoded text>` filters partition labels. The default is no filter.
For example, this opens files added by a specific commit across all branches, grouped flat:
```
<base_url>/table/filetree?table=<uri-encoded database.table>&start_snapshot_id=<range start>&end_snapshot_id=<range end>&filetree_branch=&filetree_snapshot_id=<snapshot id>&filetree_scope=commit&filetree_grouping=flat
```
URI-encode branch names and search text as well as table names. Omit FileTree parameters that use
their defaults unless an explicit value makes the requested view clearer.
**Two hard rules:**
1. **Always set both `start_snapshot_id` and `end_snapshot_id` — never emit `end_snapshot_id`
alone.** A link with no `start_snapshot_id` opens onto an unbounded range instead of the
specific, particular view you're actually pointing at. Resolve a concrete start the same way
you resolved the data you're describing: if the answer came from a ranged `snapshots`/`graph`
call, reuse that same range; if it came from a rangeless `graph <table>` call (which auto-selects
only the latest snapshot), set `start_snapshot_id` equal to that same latest snapshot id, so the
link reproduces that exact single-snapshot view rather than defaulting to full history.
2. **`select_node_id` only works on `/table/graph`.** `MetadataPage`, `TimelinePage`, and
`FileTreePage` don't read it — they ignore it silently. If the user's request maps more
naturally to one of those views, link to that page (`/table/metadata`, `/table/timeline`,
`/table/filetree`, same `table`/snapshot query params) *without* `select_node_id`, and say
plainly that node-level selection is only available on the Graph view.
Don't invent table names, snapshot ids, or node ids — they must come from an actual CLI call or
from what the user told you directly.
**If you have browser automation available** (e.g. Playwright tools), don't just show the link —
open it too, so the user is actually looking at the view you're describing instead of having to
click it themselves. Still always include the link text in your reply as well, since opening a
browser tab isn't a substitute for giving the user something they can re-open, copy, or share.
### Specs panel links
The Specs panel is available on every `/table/*` page and on `/snapshots-selection`, and its
state is in the URL, so you can link straight to one schema, partition spec, or sort order:
- `specs=open` opens the panel with no definition selected.
- `spec_kind=schema|partition|order` with `spec_id=<id>` opens that definition directly. Both
are required together; `spec_kind` alone is ignored.
- `spec_view=diff` opens the selected definition compared with its preceding version. It is
removed when no preceding version exists.
```
<base_url>/table/metadata?table=<uri-encoded database.table>&start_snapshot_id=<id>&end_snapshot_id=<id>&spec_kind=schema&spec_id=<schema id>&spec_view=diff
```
- Take `spec_id` from the metadata a `graph` command returns (`schemas[].schema-id`,
`partition-specs[].spec-id`, `sort-orders[].order-id`). Don't guess it.
- The ID must exist in the metadata the link's snapshot range loads, so keep the same range you
used to read it. If it doesn't resolve, the panel opens and says so rather than failing
silently.
- These parameters work on any `/table/*` page and on `/snapshots-selection`, where the panel reads
the table's latest metadata (take `spec_id` from a `metadata` command there). Invalid values are
ignored. Changing table or snapshot range clears them.
## 5. Tracing a snapshot back to the Spark job that wrote it
A `graph` node with `type: "snapshot"` may have an `action_link` that points directly to the Spark
History Server application that wrote it. Check `action_link` first. If it is populated, give that
link to the user directly. Do not ask for the History Server base URL or an example application
URL when the data already provides `action_link`.
The node also has a `summary` dict, a raw, unfiltered passthrough of whatever Iceberg/Spark put in
that snapshot's summary map. When `action_link` is empty, resolve the Spark application ID in this
order:
1. Use `summary["app-id"]` when `summary["engine-name"]` is `"spark"`.
2. Otherwise, use `summary["spark.app.id"]` when present.
If either form provides an application ID, tell the user they can look up that application in
their **Spark History Server**. Ask the user for an example URL to any application's page in their
Spark History Server (they likely have one bookmarked, or can grab one from another job's logs).
Then build the equivalent URL for this application ID by substituting just the app-id portion of
that example URL, leaving the rest of its structure (host, port, path shape) untouched. Don't
assume a fixed Spark History Server URL scheme, since it varies by setup.
## 6. Cache a table's data to a tmp file for the rest of the session
The first time you fetch a table's data with `snapshots` or `graph` in a conversation, write the
raw JSON to a tmp file (session scratch/tmp directory if one is available, otherwise a plain
system tmp path — name it so it's identifiable, e.g. `icegraph_<database>_<table>.json`). For any
follow-up question about that same table and range, including schema, properties, partition spec,
a specific node's fields, errors/warnings, or tracing a Spark application ID, read back from that
file instead of re-running the CLI. This data doesn't change from one question to the next within a
session, so re-fetching it is wasted round-trips to a remote server.
**Exception: never answer from the cache when the user is specifically asking about the table's
most recent activity** — e.g. "what are the last few operations," "what's the latest snapshot,"
"has anything written to this table since X." Re-run `snapshots`/`graph` fresh every time for that
kind of question, since new commits could have landed on the real table since the file was cached,
and giving a stale answer there is actively misleading in a way a stale schema/properties answer
usually isn't.
## Example flow
1. "What tables are on my IceGraph server at `https://ice.example.com`?"
→ `icegraph --base-url https://ice.example.com tables`
2. "Show me the snapshot history for `sales.orders`."
→ `icegraph --base-url https://ice.example.com snapshots sales.orders`
3. "Why does `sales.orders` have errors?" (no link requested)
→ `icegraph --base-url https://ice.example.com graph sales.orders` — no range given, so the CLI
auto-selects only the latest snapshot, say `snap-789`. Read `issues.errors`, explain the
problem — and proactively include a link, setting **both** bounds to that same resolved
snapshot so it isn't left open-ended:
`https://ice.example.com/table/graph?table=sales.orders&start_snapshot_id=snap-789&end_snapshot_id=snap-789&select_node_id=<file path of the erroring node>`
so the user can look at the offending node directly, without needing to ask for it.
4. "What's the schema/properties/partition spec of `sales.orders`?"
→ For the latest metadata, use `icegraph --base-url https://ice.example.com metadata sales.orders`
without building a graph. If the user asks about a snapshot range, use
`icegraph --base-url https://ice.example.com graph sales.orders` with that range and read its
top-level `metadata` key, **not** any node's own fields. In either metadata dictionary, use
`schemas` for columns, `properties` for table properties,
`partition-specs`/`default-spec-id` for the active partition spec, and
`format-version` for the table format version. Summarize the relevant fields rather
than dumping the whole object back at the user. If you used a graph with a resolved snapshot,
include a link to that snapshot (`select_node_id` doesn't apply on `/table/metadata`, so omit it):
`https://ice.example.com/table/metadata?table=sales.orders&start_snapshot_id=snap-789&end_snapshot_id=snap-789`
5. "Which job wrote this snapshot's data?"
→ find the `snapshot`-type node for it in a `graph` result. If `action_link` is populated, give
it to the user directly. Otherwise, use `summary["app-id"]` when `summary["engine-name"]` is
`"spark"`, falling back to `summary["spark.app.id"]`. If either provides an ID, ask the user for
an example Spark History Server URL (e.g. one they already have for another job), then give them
that same URL with just the app-id swapped. If neither key provides an ID, say so rather than
guessing at a job.
Versions
The database has no other skills named icegraph.
Database snapshot: 13.11.2026 · package version b316dbcd9030 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100frontend-smoke-test
Runs a deterministic browser smoke test of IceGraph across table selection, snapshot ranges, Timeline, Metadata, FileTree, Graph, Docs, URL cleanup, browser caching, keyboard controls, and console errors. Supports full testing with a real backend or Docker demo and a reduced MSW… - 100apache-iceberg-table-format-metadata
Use this skill when managing high-performance lakehouse tables with hidden partitioning, schema evolution, and snapshots via Iceberg. - 100creating-data-lake-table
Create managed Iceberg tables using Amazon S3 Tables (s3tables API namespace) with automatic compaction and snapshot management. Sets up table bucket, namespace, table, schema, Glue catalog registration, partitioning, IAM access control. Triggers on: create table, data lake…