Skip to main content

uni-db: Python Bindings for Uni Graph Database

PyPI License

Python bindings for the Uni embedded graph database.

Part of The Rustic Initiative by Dragonscale Industries Inc.

Installation

pip install uni-db

Quick Start

from uni_db import Uni

# Open or create a database (`Uni.in_memory()` for an ephemeral one)
db = Uni.open("./my_graph")

# Define schema
db.schema() \
    .label("Person") \
        .property("name", "string") \
        .property_nullable("age", "int64") \
        .index("name", "btree") \
    .apply()

# Write data. `Uni` is lifecycle and admin only: reads go through a Session,
# writes through a transaction on one.
session = db.session()
tx = session.tx()
tx.execute("CREATE (p:Person {name: 'Alice', age: 30})")
tx.execute("CREATE (p:Person {name: 'Bob', age: 25})")
tx.commit()

# Query (read-only)
results = session.query(
    "MATCH (p:Person) WHERE p.age > $min RETURN p.name",
    {"min": 28},
)
print(results)  # [{'p.name': 'Alice'}]

Schema Operations

# Labels, edge types, properties and indexes are all declared through the
# schema builder and committed together by a single `.apply()`.
db.schema() \
    .label("Person") \
        .property("name", "string") \
        .property_nullable("age", "int64") \
        .vector("embedding", 384) \
        .index("name", "btree") \
        .index("embedding", {"type": "vector", "metric": "cosine"}) \
        .done() \
    .edge_type("KNOWS", ["Person"], ["Person"]) \
        .property_nullable("since", "date") \
    .apply()

# Introspection
db.schema().current()        # dict view of the whole schema
db.schema().current_typed()  # typed `Schema` object

Transactions

tx = db.session().tx()
tx.execute("CREATE (p:Person {name: 'Charlie'})")
tx.commit()   # or tx.rollback()

Bulk Loading

The bulk writer is built from a transaction.

tx = db.session().tx()
writer = tx.bulk_writer().build()
vids = writer.insert_vertices("Person", [
    {"name": "Alice", "age": 30},
    {"name": "Bob",   "age": 25},
])
writer.insert_edges("KNOWS", [
    (vids[0], vids[1], {}),   # (src_vid, dst_vid, properties)
])
writer.commit()
tx.commit()
# Declare the vector column and its index
db.schema() \
    .label("Document") \
        .property("text", "string") \
        .vector("embedding", 128) \
        .index("embedding", {"type": "vector", "metric": "cosine"}) \
    .apply()

session = db.session()
tx = session.tx()
tx.execute("CREATE (d:Document {text: 'hello world', embedding: $v})", {"v": my_embedding})
tx.commit()
db.flush()

# K-NN search. `k` is required.
results = session.query('''
    CALL uni.vector.query('Document', 'embedding', $vec, 10)
    YIELD node, score
    RETURN node.text AS text, score
    ORDER BY score DESC
''', {"vec": my_embedding})

# K-NN with pre-filter (SQL WHERE expression)
results = session.query('''
    CALL uni.vector.query('Document', 'embedding', $vec, 10, 'category = "tech"')
    YIELD node, score
    RETURN node.text AS text, score
''', {"vec": my_embedding})

# K-NN with a similarity floor. `threshold` is a MINIMUM SIMILARITY on the
# same scale as `score` (larger is a better match), not a maximum distance.
results = session.query('''
    CALL uni.vector.query('Document', 'embedding', $vec, 10, NULL, 0.8)
    YIELD node, score
    RETURN node.text AS text, score
''', {"vec": my_embedding})

YIELD columns: node (the matched vertex), score (similarity, larger is better) and distance (the raw metric distance).

Async API

from uni_db import AsyncUni

db = await AsyncUni.open("./my_graph")
# or: db = await AsyncUni.temporary()

session = db.session()
tx = await session.tx()
await tx.execute("CREATE (p:Person {name: 'Alice', age: 30})")
await tx.commit()

results = await session.query("MATCH (p:Person) RETURN p.name")
await db.flush()

Forks

Named, durable, isolated branches of the graph. A fork lets a session reason about an alternate version of the database — what-if analysis, audit hold, scenario sandboxing — that survives across restarts.

import uni_db
from datetime import timedelta

db = uni_db.Uni.builder().build()
db.schema().label("Person").property("name", "string").apply()

primary = db.session()

# Open or create a fork (Phase 2: writable; Phase 3: nestable;
# Phase 4a: TTL + tags + budget).
fork = primary.fork("scenario_1").ttl(timedelta(hours=1)).build()
tx = fork.tx()
tx.execute("CREATE (:Person {name: 'fork-only'})")
tx.commit()

# Fork sees primary state + its own writes; primary unchanged.
print(fork.query("MATCH (p:Person) RETURN count(p) AS n"))

# Pin a Lance tag for audit retention; the tag survives the drop.
db.tag_fork("scenario_1", "audit-2026-q1")
del fork
db.drop_fork("scenario_1")
print(db.list_fork_tags("scenario_1"))  # tag still resolvable

The async surface mirrors this exactly through AsyncUni / AsyncSession. See examples/fork_quickstart.py and examples/fork_audit.py for runnable demos, and the full Python API reference for every method, type, and error variant.

Query Utilities

# Parameterized queries
results = db.query(
    "MATCH (p:Person) WHERE p.name = $name RETURN p",
    {"name": "Alice"},
)

# Explain / profile
plan    = db.explain("MATCH (p:Person) RETURN p")
results, stats = db.profile("MATCH (p:Person) RETURN p")

Development

git clone https://github.com/rustic-ai/uni-db
cd uni-db/bindings/uni-db
uv sync --group dev
uv run maturin develop   # builds and installs the extension module
uv run pytest            # run tests

License

Apache 2.0

Metadata

Release files for uni-db 5.2.1

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

Source distribution (sdist)

Source distribution for uni-db 5.2.1
File Size Uploaded Provenance Actions
uni_db-5.2.1.tar.gz 8.4 MB Without provenance Details for uni_db-5.2.1.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for uni-db 5.2.1
File Actions
uni_db-5.2.1-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for uni_db-5.2.1-cp310-abi3-win_amd64.whl
uni_db-5.2.1-cp310-abi3-manylinux_2_28_x86_64.whl CPython 3.10 abi3 Linux glibc 2.28+ x86-64 Details for uni_db-5.2.1-cp310-abi3-manylinux_2_28_x86_64.whl
uni_db-5.2.1-cp310-abi3-manylinux_2_28_aarch64.whl CPython 3.10 abi3 Linux glibc 2.28+ ARM64 Details for uni_db-5.2.1-cp310-abi3-manylinux_2_28_aarch64.whl
uni_db-5.2.1-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for uni_db-5.2.1-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 408.8 MB

Release files / uni_db-5.2.1.tar.gz

Download URL uni_db-5.2.1.tar.gz
Size 8.4 MB
Tags Source
SHA-256 checksum
How to use checksums
979a32e8fca4b9d7d12742d33b6274da91b097822e5fa11aacef26f0722dd4b5
BLAKE2b-256 checksum
How to use checksums
906d85ddebb327221242ac30b997fb5edd5895afb1ac3ae88307346fe50b426c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / uni_db-5.2.1-cp310-abi3-win_amd64.whl

Download URL uni_db-5.2.1-cp310-abi3-win_amd64.whl
Size 107.3 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
a6a53f1f3177b55802504ce3b104e1ddbfcd1386f0c96d22c02816e16dda376b
BLAKE2b-256 checksum
How to use checksums
9a56e97e2de8dc93190283907189909715a4127ce1025402e7cb98d9284915ad
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / uni_db-5.2.1-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL uni_db-5.2.1-cp310-abi3-manylinux_2_28_x86_64.whl
Size 103.2 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
bc89b525551243a9c85040f54e2320cfbecf5d185bb35e1bc56ae6e31487a696
BLAKE2b-256 checksum
How to use checksums
2832b3c5d2e1a2fec68ac14562eeb73a18741e2ca58670fb7e8dbdd0cee17e31
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / uni_db-5.2.1-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL uni_db-5.2.1-cp310-abi3-manylinux_2_28_aarch64.whl
Size 99.1 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
ceb3f7b51e4b0fc325f021330c502564a02192b9bd3e5c592b0eb1b19c9de4d9
BLAKE2b-256 checksum
How to use checksums
540ef3e6d55e84da9ff3e8a3f0cca9c9333928344b0873931c54e2fbf9d1d97d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / uni_db-5.2.1-cp310-abi3-macosx_11_0_arm64.whl

Download URL uni_db-5.2.1-cp310-abi3-macosx_11_0_arm64.whl
Size 90.8 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c563d51d8c2bbabbddea8a03352cac44612b6d23c831daaebce9ae02968e7a73
BLAKE2b-256 checksum
How to use checksums
4578ce29f9b9e8708d1048de8d9169188c064b97f19ec4885adcebe4e5c70512
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for uni-db 5.2.1

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.

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