Skip to main content

icegraph-client

Python client and CLI for the IceGraph server API - script access to tables, snapshot history, and the metadata graph.

Install

icegraph-client is only guaranteed compatible with the exact version of the IceGraph server it talks to - pin to that version:

pip install icegraph-client==<version>

CLI

icegraph --base-url http://<icegraph-server-host> tables
icegraph --base-url http://<icegraph-server-host> snapshots <database.table> [--before-snapshot-id ID]
icegraph --base-url http://<icegraph-server-host> metadata <database.table>
icegraph --base-url http://<icegraph-server-host> sparkdesc <database.table>
icegraph --base-url http://<icegraph-server-host> graph <database.table> [--start-snapshot-id ID] [--end-snapshot-id ID]

--base-url also falls back to the ICEGRAPH_BASE_URL environment variable. If your server sits behind a proxy that requires auth, pass --token/--cookie (or ICEGRAPH_TOKEN/ICEGRAPH_COOKIE).

Each command prints its result as JSON on stdout; status messages go to stderr, so output pipes cleanly.

snapshots returns one page, starting from the table's newest snapshots, as {"snapshots": [...], "next_before_snapshot_id": ...}. Pass next_before_snapshot_id as --before-snapshot-id to get the next older page; it is null when no older snapshots remain.

metadata returns the table's latest metadata, plus warnings, which maps a source to a list of messages and is empty when there are none. For example, it warns when the table uses an Iceberg format version other than 1, 2, or 3, which IceGraph doesn't fully support yet.

sparkdesc returns Spark's description of any table Spark can resolve, Iceberg or not, as {"spark_schema": {...}, "spark_partitions": [...], "sections": [...], "properties": {...}, "warnings": {...}}. Use it when another command reports that the table is not an Iceberg table.

Python

from icegraph_client import IceGraphClient

client = IceGraphClient("http://<icegraph-server-host>")
client.list_tables()
page = client.get_snapshot_map("database.table")
if page.next_before_snapshot_id is not None:  # None when no older snapshots remain
    client.get_snapshot_map("database.table", before_snapshot_id=page.next_before_snapshot_id)
client.get_table_metadata("database.table")
client.get_table_description("database.table")
client.get_graph("database.table", start_snapshot_id, end_snapshot_id)

Anonymous user ID

The CLI and IceGraphClient send a random anonymous ID in the X-IceGraph-User-Id header, so a server can estimate its number of users from its logs. The ID is created on first use and saved in ~/.config/icegraph/client_id, and if that file can't be written, a new ID is used for each process. The same ID is sent to every server you connect to. To replace it, delete ~/.config/icegraph/client_id.

Docs

Product page: https://yanivzalach.github.io/IceGraph-Site/

Full documentation, the IceGraph application, and the source code: github.com/YanivZalach/IceGraph

License

icegraph-client is licensed under the Apache License, Version 2.0.

Copyright (c) 2026 Yaniv Zalach and the IceGraph contributors.

Metadata

Release files for icegraph-client 0.24.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for icegraph-client 0.24.0
File Size Uploaded Provenance Actions
icegraph_client-0.24.0.tar.gz 27.6 kB Without provenance Details for icegraph_client-0.24.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for icegraph-client 0.24.0
File Interpreter ABI Platform Actions
icegraph_client-0.24.0-py3-none-any.whl Python 3 none any Details for icegraph_client-0.24.0-py3-none-any.whl

Total release size: 41.9 kB

Release files / icegraph_client-0.24.0.tar.gz

Download URL icegraph_client-0.24.0.tar.gz
Size 27.6 kB
Tags Source
SHA-256 checksum
How to use checksums
8a671419c4106a1f2467382f6f8d8bf3fc22161dc7714c62d3afadb13ea3245a
BLAKE2b-256 checksum
How to use checksums
b39368d8a49f7c1ea1d4af0702ebae3a4b71826d28347a17780278745f44e1e5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Release files / icegraph_client-0.24.0-py3-none-any.whl

Download URL icegraph_client-0.24.0-py3-none-any.whl
Size 14.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
83c7b844e8ffd00e3fd2f2861f094f051dca3021362824b3ef8e8e539c89e727
BLAKE2b-256 checksum
How to use checksums
26b8459881a46a4c45d6bdb796025e7e92c6639a0d783be4eaae1b8171268d92
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.4

Security for icegraph-client 0.24.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.24.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page