Crate cozo

Expand description

This crate provides the core functionalities of CozoDB. It may be used to embed CozoDB in your application.

This doc describes the Rust API. To learn how to use CozoDB to query (CozoScript), see:

The CozoDB documentation

Rust API usage:

use cozo::*;

let db = DbInstance::new("mem", "", Default::default()).unwrap();
let script = "?[a] := a in [1, 2, 3]";
let result = db.run_script(script, Default::default(), ScriptMutability::Immutable).unwrap();
println!("{:?}", result);

We created an in-memory database above. There are other persistent options: see DbInstance::new. It is perfectly fine to run multiple storage engines in the same process.

§Features

compact (enabled by default) — Enables the minimal, requests and graph-algo features.
compact-single-threaded — Enables the minimal, requests and graph-algo features in single threaded mode.
minimal (enabled by default) — Enables the storage-sqlite feature.
storage-sqlite (enabled by default) — Enables the Sqlite backend, also allows backup and restore with Sqlite data files. Sqlite is easy to compile, has very low resource requirements and reasonable performance, but does not support much concurrency.
storage-rocksdb — Enables the RocksDB backend. RocksDB is hard to compile on some platforms, uses more resources than SQLite, but is very performant and supports an extremely high level of concurrency. You can also fine-tune RocksDB options.
graph-algo (enabled by default) — Enables the graph algorithms.
requests (enabled by default) — Allows the utilities to make web requests to fetch data.
jemalloc — Uses jemalloc as the global allocator, can make a difference in performance.
io-uring — Enables io-uring option for the RocksDB storage
wasm — Polyfills for the WASM target

The following features are highly experimental:

storage-sled — Enables the Sled backend. Sled is slower than Sqlite for the usual workload of Cozo, can use quite a lot of disk space, and may not be stable enough. In general you should use RocksDB instead. The Sled engine does not support time travel.
storage-tikv — Enables the TiKV client backend. The only reason that you may want to use this is that your data does not fit in a single machine. This engine is orders of magnitude slower than every other engine for graph traversals, due to the significant network overhead. Simple point-lookup queries are fine, though. The TiKV engine does not support time travel.

§Recommendation for features to enable

Generally you will want the storage-sqlite and graph-algo features enabled, unless your environment makes compiling them difficult. The backup/restore functionalities are only available if storage-sqlite is on. Without graph-algo you cannot use any graph algorithms (utilities are still available), which could be OK if you only want to deal with pure Datalog.

The requests feature allows the database to make outgoing HTTP requests to fetch data into queries – only enable it if you need it.

The wasm feature simply patches some functions so that they can compile on WASM platform, which lacks some std implementations at the moment. (On WASM you must also enable nothread). This feature will not work on any other platform.

The jemalloc feature only makes sense for desktop and servers. It could improve performance, sometimes substantially, but you need to benchmark for your use case. It also tends to break builds on untested platforms. None of our prebuilt binaries have it enabled.

Enable storage-rocksdb if you expect high concurrency or want better performance than SQLite, but note that RocksDB is much more resource-hungry and takes long to compile.

The other storage options are just for experimentation. We do not recommend using them.

Structs§

Db: The database object of Cozo.
Error: Core Diagnostic wrapper type.
FixedRuleInputRelation: Represents an input relation during the execution of a fixed rule
FixedRulePayload: Passed into implementation of fixed rule, can be used to obtain relation inputs and options
JsonData: Wrapper for JsonValue
MemStorage: The non-persistent storage
MultiTransaction: A multi-transaction handle. You should use either the fields directly, or the associated functions.
NamedRows: Rows in a relation, together with headers for the fields.
Poison: Used for user-initiated termination of running queries
RegexWrapper: A Regex in the database. Used internally in functions.
RegularTempStore: A store holding temp data during evaluation of queries. The public interface is used in custom implementations of algorithms/utilities.
SimpleFixedRule: Simple wrapper for custom fixed rule. You have less control than implementing FixedRule directly, but implementation is simpler.
SourceSpan: Span of the element in the source script, with starting and ending positions.
SqliteStorage: The Sqlite storage engine
Symbol: Names with associated source span
UuidWrapper: UUID value in the database
Validity: Validity for time travel
ValidityTs: Timestamp part of validity

Enums§

CallbackOp: Represents the kind of operation that triggered the callback
DataValue: A Value in the database
DbInstance: A dispatcher for concrete storage implementations, wrapping Db. This is done so that client code does not have to deal with generic code constantly. You may prefer to use Db directly, especially if you provide a custom storage engine.
Expr: Expression can be evaluated to yield a DataValue
Num: Representing a number
ScriptMutability: Whether a script is mutable or immutable.
TransactionPayload: Commands to be sent to a multi-transaction
Vector: Vector of floating numbers

Traits§

FixedRule: Trait for an implementation of an algorithm or a utility
Storage: Swappable storage trait for Cozo’s storage engine
StoreTx: Trait for the associated transaction type of a storage engine. A transaction needs to guarantee MVCC semantics for all operations.

Functions§

decode_tuple_from_kv: Decode tuple from key-value pairs. Used for customizing storage in trait StoreTx.
evaluate_expressions: Evaluate a string expression in the context of a set of parameters and variables
format_error_as_json: Convert error raised by the database into friendly JSON format
get_variables: Get the variables referenced in a string expression
new_cozo_mem: Create a database backed by memory. This is the fastest storage, but non-persistent. Supports concurrent readers but only a single writer.
new_cozo_sqlite: Create a sqlite backed database. Supports concurrent readers but only a single writer.