Skip to main content

Ursa

Polars-shaped dataframes for graph data.

Ursa is a graph analytics library for Python. You write a query the way you write a Polars query. A Rust engine runs it: Apache Arrow for the data, DataFusion for the plan, and parallel, deterministic kernels for the algorithms.

There is no Graph object. An edge table is the graph. Every operation returns a table.

Documentation: https://cldixon.github.io/ursa/

Install

pip install ursa-graph     # then: import ursa
# or
uv add ursa-graph

The package on PyPI is ursa-graph. The import name is ursa. Wheels include the compiled core, so you need no Rust toolchain. Python 3.10 or later.

polars is optional. Install pip install 'ursa-graph[polars]' for .to_polars() and ur.from_polars(). Data crosses the boundary as Arrow either way.

Try it

Paste this into a Python session. It needs no files and no network.

import ursa as ur

edges = ur.datasets.load_karate()   # 34 nodes, 78 edges, bundled with the package

top = (
    edges.nodes()
    .with_columns(
        degree=ur.degree(edges, direction="both"),
        triangles=ur.triangle_count(edges),
        community=ur.louvain(edges, seed=1),
    )
    .sort("degree", descending=True)
    .head(5)
    .collect()          # one query in the engine; the result is Arrow data
)
print(top)
shape: (5, 4)
┌───────┬────────┬───────────┬───────────┐
│ id    ┆ degree ┆ triangles ┆ community │
│ ---   ┆ ---    ┆ ---       ┆ ---       │
│ int64 ┆ uint32 ┆ uint32    ┆ uint32    │
╞═══════╪════════╪═══════════╪═══════════╡
│ 33    ┆ 17     ┆ 15        ┆ 2         │
│ 0     ┆ 16     ┆ 18        ┆ 0         │
│ 32    ┆ 12     ┆ 13        ┆ 2         │
│ 2     ┆ 10     ┆ 11        ┆ 0         │
│ 1     ┆ 9      ┆ 12        ┆ 0         │
└───────┴────────┴───────────┴───────────┘

To run the same query over your own data, change the first line:

edges = ur.scan_edges("edges.parquet", src="from_id", dst="to_id")

Nothing after that line changes. See the quickstart.

What it does

  • A dataframe API. with_columns, filter, sort, select, group_by, join. Lazy until collect(). If you know Polars, you know the shape.
  • The standard algorithms. Degree, PageRank, connected components, triangle count, clustering coefficient, closeness, betweenness, Louvain, label propagation. Each with a weighted form, where a weight is an expression over edge columns. Neighbour aggregation. Hops, shortest paths, and random walks.
  • Your data, where it is. Parquet and CSV, local or on S3, GCS, and Azure. Polars, pandas, pyarrow, NetworkX, NumPy, and SciPy in memory. Arrow in, Arrow out, with no copies.
  • Results you can check. Every kernel is deterministic on any thread count. Each one is pinned to the NetworkX call it matches, and the test suite checks it.

Ursa is version 0.4 and in active development. The Limits page lists what does not run yet.

How it is built

Layer Language Role
python/ursa Python The API: signatures and docs, converting your data to Arrow, getting results out. Each frame method calls into Rust.
ursa-plan Rust The plan a frame holds: it validates each step as you add it, and runs the whole plan as one DataFusion query, with graph operations as plan nodes.
ursa-core Rust The CSR topology index and the kernels. Parallel with rayon; compiles for wasm32 without it.
ursa-py Rust PyO3 bindings. Arrow crosses as zero-copy capsules; the GIL is released during compute.

The design document is design/SPEC.md.

Develop

uv sync                  # builds the extension and installs the dev tools
uv run pytest            # the Python suite, including every example in the docs
cargo test --workspace   # the Rust suites
uv run ruff check . && uv run ty check

uv sync --group docs && uv run zensical serve   # the documentation site, served locally

The docs are in docs/, built with Zensical and served by GitHub Pages. Every ```python block in them runs in the test suite, so an example that stops working fails CI. The benchmark harness is in benchmarks/.

License

MIT OR Apache-2.0.

Metadata

Release files for ursa-graph 0.5.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 ursa-graph 0.5.0
File Size Uploaded Provenance Actions
ursa_graph-0.5.0.tar.gz 434.2 kB With provenance Details for ursa_graph-0.5.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for ursa-graph 0.5.0
File Actions
ursa_graph-0.5.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for ursa_graph-0.5.0-cp310-abi3-win_amd64.whl
ursa_graph-0.5.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for ursa_graph-0.5.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
ursa_graph-0.5.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl CPython 3.10 abi3 Linux glibc 2.17+ ARM64 Details for ursa_graph-0.5.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
ursa_graph-0.5.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for ursa_graph-0.5.0-cp310-abi3-macosx_11_0_arm64.whl
ursa_graph-0.5.0-cp310-abi3-macosx_10_12_x86_64.whl CPython 3.10 abi3 macOS 10.12+ x86-64 Details for ursa_graph-0.5.0-cp310-abi3-macosx_10_12_x86_64.whl

Total release size: 147.1 MB

Release files / ursa_graph-0.5.0.tar.gz

Download URL ursa_graph-0.5.0.tar.gz
Size 434.2 kB
Tags Source
SHA-256 checksum
How to use checksums
29cf6623c97ca0d71ad22ec3d5b82d633d6b4b3d023578cc9871ef54fa67dcf3
BLAKE2b-256 checksum
How to use checksums
fe2bf23cf88fffa8e2b0d200c6ffebb9d9df088f7723bb8024f92c0d62adcafb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / ursa_graph-0.5.0-cp310-abi3-win_amd64.whl

Download URL ursa_graph-0.5.0-cp310-abi3-win_amd64.whl
Size 31.0 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
9f605a71514f3bf4fe6985ad3fb2a925db2120b02891a8d085b6a8466d234119
BLAKE2b-256 checksum
How to use checksums
8df4aee491acb9cd855331d37bbb9454681a7ff92c0d0eac795b810842149a17
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / ursa_graph-0.5.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl

Download URL ursa_graph-0.5.0-cp310-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl
Size 31.0 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
ceb8b23d7eba87ab3c93b82ee24d367785554ae26edfae2a4c821c1a2fc3bd8f
BLAKE2b-256 checksum
How to use checksums
06e9ecda52f7697c752fcd6096692254451316a928445fdaf5b5c1c36d3fb80f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / ursa_graph-0.5.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl

Download URL ursa_graph-0.5.0-cp310-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl
Size 26.8 MB
Tags CPython 3.10 Linux glibc 2.17+ ARM64 abi3
SHA-256 checksum
How to use checksums
4d5da7f65a4e10f62fdf77195dc05e23803174c6aa2574b905084fe76419db68
BLAKE2b-256 checksum
How to use checksums
427454c2b7bf1baeb1a5d00b6b6b466c46f493dc1dc231d45e60c54bbcf33137
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / ursa_graph-0.5.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL ursa_graph-0.5.0-cp310-abi3-macosx_11_0_arm64.whl
Size 28.0 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
5554789ec994b6e9e41295b70402de09daece1d5db6e2c9135470b086c8d8bed
BLAKE2b-256 checksum
How to use checksums
62d62d59b2db39f7961114b64ed763762b7654df79e1b66161e7fb15c72c6b1c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Release files / ursa_graph-0.5.0-cp310-abi3-macosx_10_12_x86_64.whl

Download URL ursa_graph-0.5.0-cp310-abi3-macosx_10_12_x86_64.whl
Size 30.0 MB
Tags CPython 3.10 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
1e0f5c6f10dd462d4087ea09dc97162d06229197bc2c221d78fec4e7e92e60f3
BLAKE2b-256 checksum
How to use checksums
4da18d93d48a4ac0a679dd73e64a513e8a38fb8b790cbf97072e9c48dbbb94a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

Security for ursa-graph 0.5.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.

Full provenance

All 6 files in this release have been uploaded with provenance metadata.

Select from 6 files

Attestation for ursa_graph-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 1, 2026.

Transparency log

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.

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