Metadata-Version: 2.4
Name: icegraph-client
Version: 0.25.3
Summary: Python client and CLI for the IceGraph server API
Author: Yaniv Zalach
License-Expression: Apache-2.0
Project-URL: Homepage, https://yanivzalach.github.io/IceGraph-Site/
Project-URL: Source, https://github.com/YanivZalach/IceGraph
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: requests>=2.25
Requires-Dist: arrow>=1.0
Dynamic: license-file

# icegraph-client

Python client and CLI for the [IceGraph](https://github.com/YanivZalach/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:

```bash
pip install icegraph-client==<version>
```

## CLI

```bash
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

```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/](https://yanivzalach.github.io/IceGraph-Site/)

Full documentation, the IceGraph application, and the source code: [github.com/YanivZalach/IceGraph](https://github.com/YanivZalach/IceGraph)

## License

`icegraph-client` is licensed under the
[Apache License, Version 2.0](https://github.com/YanivZalach/IceGraph/blob/master/LICENSE).

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