Cozo-NG Python bindings
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.