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.0.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 uni-db 5.0.0
File Size Uploaded Provenance Actions
uni_db-5.0.0.tar.gz 8.2 MB Without provenance Details for uni_db-5.0.0.tar.gz

Built distributions (wheels)

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

Total release size: 432.9 MB

Release files / uni_db-5.0.0.tar.gz

Download URL uni_db-5.0.0.tar.gz
Size 8.2 MB
Tags Source
SHA-256 checksum
How to use checksums
69d19461a7b1d63b3dd52934d1766c498fffc0e8ea11b17d5977656f667c6fb3
BLAKE2b-256 checksum
How to use checksums
46f5245b78d466e7f5df04d056f37865357688da2d2bda6289b3be729d69e9f3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","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.0.0-cp310-abi3-win_amd64.whl

Download URL uni_db-5.0.0-cp310-abi3-win_amd64.whl
Size 113.3 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
ea9c6acf4924e9a679f548ee259d39b76b3e18354acca7ef9a01d0bd00996624
BLAKE2b-256 checksum
How to use checksums
ca684e8e6ebd79ca70701e2afdd10e5b93c22b598161170d1c3933ac01c834dd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","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.0.0-cp310-abi3-manylinux_2_28_x86_64.whl

Download URL uni_db-5.0.0-cp310-abi3-manylinux_2_28_x86_64.whl
Size 110.2 MB
Tags CPython 3.10 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
e8ade27342e74d0c87f1252cee497aaa180cc1f0cc034ebcc58863e77538a3e6
BLAKE2b-256 checksum
How to use checksums
96213b55d6a22de2b1ff87e8a7de0bd04edf46352746ca6e4365ceb86110cf47
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","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.0.0-cp310-abi3-manylinux_2_28_aarch64.whl

Download URL uni_db-5.0.0-cp310-abi3-manylinux_2_28_aarch64.whl
Size 105.5 MB
Tags CPython 3.10 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
41767131257cec4ec596a199eb1d99d7c79b8842b0352c9c920aa812a7b2444a
BLAKE2b-256 checksum
How to use checksums
c739101e5b8a4840bad3dd807b8d59440d250f694e70dd9281a99fd5b6ddc35d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","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.0.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL uni_db-5.0.0-cp310-abi3-macosx_11_0_arm64.whl
Size 95.7 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c9e7108e89cec988c8b92fcc7c2df7a474be9e76ac29a8be8ef03568fb85fe93
BLAKE2b-256 checksum
How to use checksums
6250e623a365d893760a9db903973e87a59bf1197a9f53d36018d325714e816b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","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.0.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.

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