Skip to main content

Cozo-NG Python bindings

PyPI

Native Python bindings for the independent Cozo-NG embedded graph and vector database.

Rust crate cozo-ng-python (0.13.0)
Python distribution cozo-ng
Python module cozo_embedded
Engine Cozo-NG 0.12.2
Python 3.9+ (stable ABI, abi3-py39)

See the crate changelog.

⚠️ Compatibility

cozo-ng and the upstream cozo_embedded package both provide the cozo_embedded module. Do not install both in the same environment.

Installation

python -m pip install cozo-ng

The distribution name (cozo-ng) differs from the module name (cozo_embedded). The published wheels are built with SQLite, RocksDB, graph algorithms and the engine's request utilities (compact + storage-rocksdb).

Quick start

from cozo_embedded import CozoDbPy

db = CozoDbPy("mem", "", "{}")
result = db.run_script("?[x] <- [[1], [2]]", {}, False)
print(result["headers"], result["rows"])

API overview

CozoDbPy(engine, path, options)

Method Description
run_script(query, params, immutable) Runs a script and returns {"headers", "rows", "next"}.
multi_transact(write) Opens a multi-statement transaction (CozoDbMulTx).
register_callback(rel, callback) Calls callback(op, new_rows, old_rows) on relation changes. Returns an id.
unregister_callback(id) Removes a callback. Returns False if closed or unknown.
register_fixed_rule(name, arity, callback) Registers a Python fixed rule: callback(inputs, options) -> rows.
unregister_fixed_rule(name) Removes a fixed rule.
export_relations(relations) / import_relations(data) Export or import relations as named rows.
backup(path) / restore(path) / import_from_backup(path, relations) Backup and restore.
close() Closes the database. Returns True if it was open.

Once closed, every method except unregister_callback and close raises an exception with the message database closed.

CozoDbMulTx

run_script(query, params), commit(), abort().

Module functions

  • eval_expressions(query, params, bindings): evaluates an expression.
  • variables(query, params): returns the set of variables used by a query.

Type mapping

Python Cozo
None Null
bool Bool
int Int (signed 64-bit)
float Float
str String
bytes, bytearray Bytes
list, tuple List
dict Json
  • Integers outside the signed 64-bit range raise ValueError.
  • Unsupported types raise TypeError.
  • On the way back, UUIDs and regexes are returned as str, validities as [timestamp, is_assert], and vectors as lists of floats.

Errors

Errors raised by a query are Exception instances whose first argument (e.args[0]) is the decoded JSON diagnostics. Other errors (closed database, I/O, backup) carry a plain text message.

Examples

Transactions

from cozo_embedded import CozoDbPy

db = CozoDbPy("mem", "", "{}")

tx = db.multi_transact(True)
tx.run_script(":create t {id: Int => v: String}", {})
tx.run_script("?[id, v] <- [[1, 'a']] :put t {id => v}", {})
tx.commit()

Callbacks

Callbacks run on a dedicated thread. An exception raised in a callback is printed with its traceback and does not stop the listener.

cb_id = db.register_callback("t", lambda op, new, old: print(op, new, old))
db.run_script("?[id, v] <- [[2, 'b']] :put t {id => v}", {}, False)
db.unregister_callback(cb_id)

Fixed rules

def double(inputs, options):
    return [[row[0] * 2] for row in inputs[0]]

db.register_fixed_rule("Double", 1, double)
db.run_script("?[y] <~ Double(*t[id, v])", {}, True)

Error handling

try:
    db.run_script("?[x] <- bad", {}, True)
except Exception as e:
    print(e.args[0])  # decoded JSON diagnostics

Building from source

Requirements: a Rust toolchain (1.85 or newer, edition 2024), the native build requirements for RocksDB, and maturin. From the repository root:

cd cozo-lib-python

# Local development (installs into the active virtualenv)
maturin develop --release -F compact -F storage-rocksdb

# Distributable wheel
maturin build --release -F compact -F storage-rocksdb

See the maturin documentation for development and building.

PyPI release workflow

The PyPI Release workflow runs on pushes to main or master, pushes of tags matching v*, and manual dispatch. Its Linux, Windows and macOS jobs use maturin to build wheels with compact and storage-rocksdb; Linux also produces a source distribution and macOS requests universal2 wheels. Each job uploads its output as a GitHub Actions artifact.

The PyPI upload job runs only for a tag ref, after all three build jobs succeed. It downloads their artifacts and uploads them with --skip-existing, using the repository secret PYPI_API_TOKEN. Configure that secret with a token authorized to publish the cozo-ng project before triggering a tag release. The workflow uses the version declared in the Rust crate; make sure it matches the intended release before tagging.

Upstream packages

Cozo-NG is an independent continuation of CozoDB. The upstream cozo_embedded distribution and PyCozo are separate projects, not Cozo-NG releases. This distribution keeps cozo_embedded as its module name.

Metadata

Release files for cozo-ng 0.13.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 cozo-ng 0.13.0
File Size Uploaded Provenance Actions
cozo_ng-0.13.0.tar.gz 5.4 MB Without provenance Details for cozo_ng-0.13.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cozo-ng 0.13.0
File Interpreter ABI Platform Actions
cozo_ng-0.13.0-cp39-abi3-manylinux_2_28_x86_64.whl CPython 3.9 abi3 Linux glibc 2.28+ x86-64 Details for cozo_ng-0.13.0-cp39-abi3-manylinux_2_28_x86_64.whl

Total release size: 18.9 MB

Release files / cozo_ng-0.13.0.tar.gz

Download URL cozo_ng-0.13.0.tar.gz
Size 5.4 MB
Tags Source
SHA-256 checksum
How to use checksums
f4474cbbcbd112d60def5e754ded7da7b2759f17a8896cc230e9e39aee351b29
BLAKE2b-256 checksum
How to use checksums
b55886707eea6660f2bccab850afa5d25deafd3da4183f1f6c620c2cf1f177d9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Release files / cozo_ng-0.13.0-cp39-abi3-manylinux_2_28_x86_64.whl

Download URL cozo_ng-0.13.0-cp39-abi3-manylinux_2_28_x86_64.whl
Size 13.5 MB
Tags CPython 3.9 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
ed1e3a11dcec938c9034ecc3d1387a7e2e77cadf9ab68020e3304e30c0558884
BLAKE2b-256 checksum
How to use checksums
54c862f5e58a6b38c8aaa6e7c1e07c2a9fb82e1a42cb23b3e6f3f5f6e4c92c6e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via maturin/1.16.0

Security for cozo-ng 0.13.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