cozo_dart #

A Dart/Flutter package for CozoDB — an embedded transactional relational-graph-vector database with Datalog queries, 15+ graph algorithms, HNSW vector search, full-text search, LSH similarity, and time-travel.

Features #

• Embedded database — runs locally with zero network, no server needed
• Datalog queries — powerful recursive queries via CozoScript
• 15+ graph algorithms — PageRank, shortest paths, community detection, centrality, MST, topological sort, random walk
• HNSW vector search — approximate nearest neighbor on-device with hybrid Datalog filters
• Full-text search — BM25-ranked keyword search with tokenizers, stemming, and stopword filters
• LSH similarity — MinHash / Jaccard near-duplicate detection
• ACID transactions — full transactional guarantees
• Persistent storage — SQLite backend for durable on-device data
• Cross-platform — Android, iOS, macOS, Linux, Windows

Installation #

dependencies:
  cozo_dart: ^0.1.0

Prerequisites #

This package uses flutter_rust_bridge to bridge Dart and a Rust CozoDB engine. You need:

• Rust toolchain (rustup, cargo) — Install Rust
• For Android: install Android NDK and cargo-ndk

  cargo install cargo-ndk
  rustup target add aarch64-linux-android armv7-linux-androideabi x86_64-linux-android
  

• For iOS: rustup target add aarch64-apple-ios
• For macOS: rustup target add aarch64-apple-darwin x86_64-apple-darwin

Quick Start #

import 'package:cozo_dart/cozo_dart.dart';

// Initialize once at app startup
await CozoDatabase.init();

// Open an in-memory database
final db = await CozoDatabase.openMemory();

// Create a relation
await db.query(':create users {id: String => name: String, age: Int}');

// Insert data
await db.query(r'''
  ?[id, name, age] <- [["alice", "Alice", 30], ["bob", "Bob", 25]]
  :put users {id => name, age}
''');

// Query
final result = await db.query('?[name] := *users[_, name, age], age > 26');
print(result.toMaps()); // [{name: Alice}]

// Graph algorithms
final graph = CozoGraph(db);
final ranks = await graph.pageRank('follows');

// Vector search
final vec = CozoVectorSearch(db);
final neighbors = await vec.search('docs', 'doc_idx',
  queryVector: embedding, bindFields: ['id', 'content'], k: 10);

// Full-text search
final fts = CozoTextSearch(db);
final hits = await fts.search('articles', 'articles_fts',
  queryText: 'graph database', bindFields: ['id', 'title'], k: 10);

await db.close();

Storage Engines #

// In-memory (default)
final db = await CozoDatabase.openMemory();

// SQLite persistent
final db = await CozoDatabase.openSqlite('/path/to/database.db');

API Reference #

The SDK exports 7 modules from package:cozo_dart/cozo_dart.dart:

CozoDatabase #

Core database lifecycle, queries, system operations, and data I/O.

Initialization & Lifecycle

Query Execution

System Operations (12 methods)

Data Import/Export & Backup

CozoGraph #

High-level graph operations wrapping CozoDB's built-in Datalog graph algorithms. All methods accept relation name strings and return CozoResult.

CRUD

PageRank

Path & Traversal Algorithms (7 methods)

Centrality Algorithms (3 methods)

Community Detection (4 methods)

Clustering

Minimum Spanning Tree (2 methods)

Topological Sort

CozoVectorSearch #

HNSW (Hierarchical Navigable Small World) vector index and approximate nearest neighbor (ANN) search.

Enums

Methods

// Example: create index and search
await vecSearch.createIndex('documents', 'doc_idx',
  dim: 1536, fields: ['embedding'], distance: VectorDistance.cosine);

final results = await vecSearch.search('documents', 'doc_idx',
  queryVector: [0.1, 0.2, ...], bindFields: ['id', 'content'], k: 10);

CozoTextSearch #

Full-text search (FTS with BM25 ranking) and locality-sensitive hashing (LSH with MinHash / Jaccard similarity).

Tokenizers

Token Filters

Applied in order after tokenization:

FTS Methods

LSH Methods

// Example: FTS with stemming + stopwords
await textSearch.createIndex('articles', 'articles_fts',
  extractor: 'body',
  tokenizer: FtsTokenizer.simple,
  filters: [FtsLowercase(), FtsStemmer('english'), FtsStopwords('en')]);

final results = await textSearch.search('articles', 'articles_fts',
  queryText: 'graph database performance', bindFields: ['id', 'title'], k: 10);

// Example: LSH near-duplicate detection
await textSearch.createLSHIndex('articles', 'articles_lsh',
  extractor: 'body', targetThreshold: 0.5, nGram: 3);

final similar = await textSearch.similaritySearch('articles', 'articles_lsh',
  queryText: 'some document text...', bindFields: ['id', 'title'], k: 5);

CozoUtils #

Utility operations wrapping CozoDB's fixed-point algorithms for sorting, CSV reading, and JSON reading.

final utils = CozoUtils(db);

// Sort and paginate
final top10 = await utils.reorderSort('users',
  sortBy: ['score'], descending: true, take: 10);

// Read CSV
final csv = await utils.readCsv('file:///data.csv',
  types: ['String', 'Int', 'Float'], columns: ['name', 'age', 'score']);

// Read JSON
final json = await utils.readJson('https://api.example.com/users.json',
  fields: [('name', 'String'), ('age', 'Int')], nullIfAbsent: true);

CozoResult #

Structured result type returned by all query and algorithm methods.

final result = await db.query('?[name, age] := *users[_, name, age]');

print(result.length);         // 10000
print(result.headers);        // ['name', 'age']
print(result.took);           // 0.042
print(result.firstOrNull);    // {name: 'Alice Smith', age: 30}
print(result.column('name')); // ['Alice Smith', 'Bob Jones', ...]

for (final row in result.toMaps()) {
  print('${row['name']} is ${row['age']} years old');
}

CozoException #

Typed exception hierarchy for error handling.

try {
  await db.query('INVALID QUERY');
} on CozoQueryException catch (e) {
  print(e.message);      // Human-readable error
  print(e.rawResponse);  // Full JSON error from CozoDB engine
} on CozoDatabaseException catch (e) {
  print(e.message);
}

CozoScript #

CozoDB uses Datalog, not SQL or Cypher. See the CozoScript tutorial for full documentation.

Common Patterns #

// Create a relation
:create table_name {key_col: Type => value_col: Type}

// Insert data
?[col1, col2] <- [[val1, val2], [val3, val4]]
:put table_name {col1, col2}

// Query with pattern matching
?[name, age] := *users[_, name, age], age > 25

// Recursive queries
?[ancestor] := *parent["alice", ancestor]
?[ancestor] := *parent[p, ancestor], ?[p]

// Graph algorithms (fixed-point)
edges[from, to] := *follows[from, to]
?[node, rank] <~ PageRank(edges[])

// Vector search
?[id, content, distance] := ~docs:vec_idx{ id, content | query: vec($q), k: 10 }

// Full-text search
?[id, title, score] := ~articles:fts_idx{ id, title | query: $q, k: 10, bind_score: score }

Parameterized Queries #

Use $param_name in CozoScript and pass parameters as a map:

final result = await db.query(
  r'?[name] := *users[_, name, age], age > $min_age',
  params: {'min_age': 25},
);

Architecture #

┌──────────────────────────────────────────┐
│          Dart API Layer                  │
│  CozoDatabase · CozoGraph · CozoResult  │
│  CozoVectorSearch · CozoTextSearch       │
│  CozoUtils · CozoException              │
├──────────────────────────────────────────┤
│       flutter_rust_bridge (FFI)          │
├──────────────────────────────────────────┤
│          Rust Bridge Layer               │
├──────────────────────────────────────────┤
│       CozoDB Engine (cozo crate)         │
│  Datalog · Graph · HNSW · FTS · LSH     │
│  SQLite backend · In-memory backend      │
└──────────────────────────────────────────┘

Binary Size #

CozoDB with SQLite backend and graph algorithms compiles to ~5–10 MB per architecture. The release profile uses LTO and opt-level = "z" to minimize binary size.

Performance Benchmarks #

The benchmark suite exercises the full API surface — bulk writes, read queries, graph algorithms, export/import, concurrent reads, updates, and deletes — against an in-memory CozoDB instance with a large synthetic dataset.

Test Environment #

• Device: iOS Simulator (iPhone)
• Database: In-memory (CozoEngine.memory)
• Dataset: 75,000 total rows across 4 relations
  • 10,000 users (id, name, age, email, score)
  • 50,000 follow edges (directed graph)
  • 5,000 posts (author, title, body, likes, timestamp)
  • 10,000 tags (post_id, tag — from a pool of 20 tag values)
• Batch size: 2,000 rows per insert query

Benchmark Results (iOS Simulator) #

Write Performance

Read Query Performance

Graph Algorithm Performance (50,000 edges)

Export / Import Performance

Concurrent & Mutation Performance

Raw Benchmark Output #

═══  BENCHMARK SUITE  ═══

Schema creation (4 relations): 69ms
Insert 10000 users: 984ms (10163 rows/s)
Insert 50000 follow edges: 2070ms (24155 rows/s)
Insert 5000 posts: 40739ms (123 rows/s)
Insert 10000 tags: 538ms (18587 rows/s)

Total data: 75000 rows across 4 relations

─── READ QUERIES ───
Full scan 10000 users: 166ms → 10000 rows
Filtered users (age 50-59): 50ms → 1610 rows
Aggregation (count, mean, min, max): 86ms
Join posts×users (likes>80): 38ms → 920 rows
Multi-hop join (tags→posts→users, tag="dart"): 28ms → 501 rows

─── GRAPH ALGORITHMS (50000 edges) ───
PageRank (10 iter): 477ms → 10000 ranked nodes
Community detection (Louvain): 4668ms → 10000 communities
BFS from node 0 (condition: age>90, limit 10): 513ms → 0 results
Shortest path (0 → 5000): 349ms → 6 hops

─── EXPORT / IMPORT ───
Export 10000 users: 79ms
Import 10000 users into fresh db: 118ms

─── CONCURRENT READS ───
4 concurrent aggregation queries: 271ms

─── UPDATES ───
Update 1000 user rows: 25ms
Delete edges from last 500 users: 25ms

═══  BENCHMARKS COMPLETE  ═══

Testing #

The package includes two levels of tests:

Unit / Integration Tests (simple_test.dart) #

Validates core API correctness:

cd example && flutter test integration_test/simple_test.dart -d <device>

Performance / Stress Tests (performance_test.dart) #

Comprehensive benchmarks: bulk inserts, read queries, graph algorithms, concurrent reads, mutations, and export/import.

cd example && flutter test integration_test/performance_test.dart -d <device>

Running the Example App #

cd example && flutter run -d <device>

License #

This project is licensed under the Mozilla Public License 2.0 (MPL-2.0).

See LICENSE for the full license text.