Skip to content
Skills Library
Data & analytics · Tool integration

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.

Repository
icegraph ↗
Licence
AGPL-3.0
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
8
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

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

  1. 0. The server is remote — never assume otherwise
  2. 1. Prerequisites
  3. 2. Commands
  4. 3. If a command fails and it looks like an auth problem
  5. 3a. If a command fails and it looks like a TLS/SSL problem
  6. 4. Building a link into the web UI
  7. 5. Tracing a snapshot back to the Spark job that wrote it
  8. 6. Cache a table's data to a tmp file for the rest of the session
  9. Example flow
Original SKILL.md headings · 328 lines, 3,191 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.