Minigraf: Cơ sở dữ liệu đồ thị nhúng song thời gian viết bằng Rust

Minigraf là một cơ sở dữ liệu đồ thị nhúng (embedded graph database) tự chứa, được viết hoàn toàn bằng Rust, hỗ trợ truy vấn bằng Datalog cùng mô hình song thời gian (bi-temporal) cho phép truy vấn ngược về quá khứ. Dự án do một lập trình viên cá nhân phát triển, tự định vị là "SQLite của cơ sở dữ liệu đồ thị song thời gian" — đơn giản, nhẹ, nhúng được ở mọi nơi, nhưng vẫn có đầy đủ lịch sử dữ liệu.

Phiên bản minigraf trên crates.io

Minigraf là gì?

Minigraf là một cơ sở dữ liệu đồ thị đơn tệp (single-file) cho phép bạn lưu trữ và truy vấn dữ liệu liên kết với toàn bộ lịch sử thay đổi. Theo mô tả của tác giả, đây là phiên bản kế thừa của một dự án cơ sở dữ liệu đồ thị thời gian trước đó, nhưng đã loại bỏ sự phụ thuộc vào một cơ sở dữ liệu khác để cung cấp engine lưu trữ, giao dịch và truy vấn.

Điểm khác biệt cốt lõi: Minigraf tự chứa hoàn toàn, được đóng gói dưới dạng một crate thư viện, nhúng trực tiếp vào ứng dụng của bạn, và hỗ trợ đầy đủ tính song thời gian.

Các tính năng chính bao gồm:

• Truy vấn quan hệ bằng Datalog — hỗ trợ quy tắc đệ quy (recursive rules) và duyệt đồ thị tự nhiên
• Du hành thời gian qua lịch sử — truy vấn song thời gian kết hợp thời gian giao dịch (transaction time) và thời gian hợp lệ (valid time)
• Hàm cửa sổ (window functions) — sum/count/min/max/avg/rank/row-number với cú pháp :over (partition-by … :order-by …)
• Prepared statements — phân tích và lập kế hoạch một lần với token $slot, thực thi hàng nghìn lần
• Nhúng mọi nơi — native, WASM, di động, IoT — tất cả chỉ với một tệp .graph duy nhất
• Không cần cấu hình — chỉ cần Minigraf::open("data.graph") là xong

Vì sao lại chọn Datalog?

Tác giả lập luận rằng Datalog về bản chất phù hợp với đồ thị hơn các ngôn ngữ kiểu SQL:

• Đệ quy theo thiết kế — các truy vấn đa bước (multi-hop) trở nên tự nhiên, không phải là giải pháp gắn thêm
• Dễ triển khai hơn — đặc tả nhỏ hơn đồng nghĩa với độ tin cậy cao hơn, ra sản phẩm nhanh hơn
• Hoàn hảo cho dữ liệu thời gian — thời gian chỉ là một chiều bổ sung trong quan hệ
• Đã được chứng minh ở quy mô lớn — hơn 40 năm nghiên cứu, được dùng trong sản phẩm thực tế như Datomic và XTDB
• Bản địa đồ thị — các sự kiện dạng Entity-Attribute-Value thực chất chính là các cạnh
• Thân thiện với LLM — ngữ pháp nhỏ và đồng nhất [?e :attr ?v] giúp các trợ lý lập trình AI dễ dàng sinh mã chính xác chỉ từ vài ví dụ

Cài đặt và sử dụng

Minigraf yêu cầu Rust 1.89 trở lên. Bạn có thể thêm vào dự án qua Cargo:

[dependencies]
minigraf = "2.0.2"

Hoặc dùng lệnh:

cargo add minigraf

Một ví dụ khởi đầu nhanh:

use minigraf::{Minigraf, OpenOptions};

// Mở hoặc tạo cơ sở dữ liệu lưu trên tệp
let db = OpenOptions::new().path("myapp.graph").open()?;

// Thêm sự kiện
db.execute(r#"(transact [[:alice :person/name "Alice"]
[:alice :person/age 30]
[:alice :friend :bob]
[:bob :person/name "Bob"]])"#)?;

// Truy vấn bằng Datalog
let results = db.execute(r#"
(query [:find ?friend-name
:where [:alice :friend ?friend]
[?friend :person/name ?friend-name]])
"#)?;

Điểm đáng chú ý là khả năng du hành thời gian — truy vấn trạng thái dữ liệu tại một thời điểm trong quá khứ:

db.execute("(query [:find ?age :as-of 1 :where [:alice :person/age ?age]])")?;

Song thời gian — điểm khác biệt cốt lõi

Song thời gian (bi-temporal) là trái tim của Minigraf. Mỗi sự kiện mang đồng thời hai mốc thời gian:

• Thời gian giao dịch (transaction time) — thời điểm sự kiện được ghi vào cơ sở dữ liệu
• Thời gian hợp lệ (valid time) — thời điểm sự kiện thực sự đúng trong thế giới thực

Nhờ vậy, bạn có thể tái dựng chính xác trạng thái tri thức tại bất kỳ thời điểm nào trong quá khứ, kể cả khi dữ liệu đã được sửa đổi sau đó. Đây là điểm mạnh đặc biệt với các hệ thống cần kiểm toán (audit) hoặc truy vết nguồn gốc dữ liệu.

Huy hiệu trạng thái build Rust

So sánh với các cơ sở dữ liệu khác

Theo bảng so sánh của dự án, Minigraf có sự kết hợp tính năng mà không cơ sở dữ liệu nào khác có đủ:

Tính năng	Minigraf	XTDB	Cozo	Neo4j	SQLite
Ngôn ngữ truy vấn	Datalog	Datalog	Datalog	Cypher	SQL
Đơn tệp	✅	❌	❌	❌	✅
Song thời gian	✅	✅	⚠️	❌	❌
Nhúng được	✅	✅	✅	❌	✅
Bản địa đồ thị	✅	✅	✅	✅	❌
Rust	✅	❌	✅	❌	❌
Tương thích WASM	✅	❌	⚠️	❌	✅

Điểm nổi bật so với SQLite: Neo4j có đồ thị nhưng không nhúng được; SQLite nhúng được nhưng không phải đồ thị; XTDB song thời gian nhưng viết bằng Clojure và không đơn tệp. Minigraf cố gắng lấp đầy khoảng trống đó.

Hỗ trợ đa nền tảng

Minigraf chia hỗ trợ thành hai cấp độ:

Cấp 1 (được kiểm thử đầy đủ, phát hành cùng mỗi bản phát hành lõi):

• Rust gốc — qua crates.io
• Python — qua PyPI

Cấp 2 (thử nghiệm, phát hành theo lịch best-effort):

• Trình duyệt WASM — gói @minigraf/browser trên npm (nền IndexedDB)
• WASI — @minigraf/wasi trên npm
• Node.js — trên npm
• Java/JVM — trên Maven Central
• Android — gói .aar trên Maven Central
• iOS/macOS — .xcframework qua Swift Package Manager
• C / FFI — header kèm tarball trên GitHub Releases

Với Android và iOS, dự án cung cấp binding Kotlin và Swift gốc thông qua UniFFI, nghĩa là lập trình viên di động không cần biết Rust vẫn dùng được:

// Android (Kotlin)
val db = MiniGrafDb.open(context.filesDir.absolutePath + "/myapp.graph")
db.execute("""(transact [[:alice :person/name "Alice"] [:alice :person/age 30]])""")
val json = db.execute("(query [:find ?name :where [?e :person/name ?name]])")

Huy hiệu bao phủ mã nguồn Codecov

Ứng dụng cho tác nhân AI

Đây có lẽ là điểm hấp dẫn nhất với xu hướng hiện nay. Minigraf được thiết kế để lưu trữ niềm tin của tác nhân AI: ghi lại điều agent tin, rút lại và sửa chữa mà không mất lịch sử, đồng thời phát lại trạng thái quá khứ để kiểm toán các quyết định.

Theo tác giả, Minigraf kết hợp rất tốt với vector store theo mô hình GraphRAG:

Vector store trả lời câu hỏi "cái gì tương tự?", còn Minigraf trả lời "các mối quan hệ là gì, ai ghi lại chúng, và tại thời điểm T chúng ta đã tin điều gì?"

Với các hệ thống RAG ngày càng phổ biến trong cộng đồng phát triển phần mềm tại Việt Nam, một giải pháp nhúng nhẹ như Minigraf có thể là lựa chọn đáng cân nhắc khi cần truy vết nguồn gốc tri thức của mô hình.

Hiệu năng và giới hạn

Dự án công bố một số chỉ số hiệu năng tại mốc 1 triệu sự kiện (facts):

Chỉ số	Kết quả
Truy vấn điểm (point query)	4,3–4,5 giây (tra cứu B+tree có chọn lọc; O(N) cho quét toàn bộ thuộc tính)
Thời gian mở cơ sở dữ liệu	1,31 giây (nhanh hơn 2,4× so với v5)
Đỉnh bộ nhớ heap	1,05 GB (giảm ~21% so với v5)

Tác giả nêu rõ Minigraf không nhắm tới các kịch bản sau (theo thiết kế):

• Phân tán — không clustering, sharding hay replication; mỗi agent sở hữu tệp .graph riêng
• Client-server — không có giao thức mạng trong lõi
• Quy mô hàng tỷ nút — tối ưu cho dưới 1 triệu nút, giống triết lý của SQLite
• Cơ sở dữ liệu chuỗi thời gian — Minigraf là cơ sở dữ liệu thời gian, không phải time-series

Mỗi tệp .graph giới hạn kích thước sự kiện ở 4.080 byte sau tuần tự hóa; cơ sở dữ liệu trong bộ nhớ thì không có giới hạn này. Về độ bền, mặc định mọi thao tác ghi đều được fsync ngay lập tức (SyncMode::Full), có thể đánh đổi lấy thông lượng trong các tác vụ nạp hàng loạt.

Một số vấn đề đã biết

Dự án có một issue ghim liệt kê các lỗi trong bản phát hành hiện tại. Đáng chú ý nhất trên phiên bản v2.x:

Hai giá trị của cùng một thuộc tính cho một thực thể, nếu được ghi trong cùng một lệnh transact (hoặc rút lại trong cùng một retract), có thể đọc lại chỉ còn một giá trị (issue #371). Cách xử lý tạm thời là ghi hoặc rút từng giá trị trong một lệnh riêng. Bản sửa lỗi sẽ thay đổi định dạng tệp và phát hành trong v3.0.0.

Nhánh v2.x vẫn sẽ nhận các bản vá bảo mật và toàn vẹn dữ liệu trong 12 tháng sau khi v3.0.0 ra mắt.

Giấy phép và đóng góp

Minigraf được phát hành theo giấy phép kép Apache 2.0 hoặc MIT, tùy chọn — giống nhiều dự án Rust khác trong hệ sinh thái. Dự án hiện do một cá nhân duy trì với tầm nhìn dài hạn, và tác giả khuyến khích đọc PHILOSOPHY.md cùng ROADMAP.md trước khi đề xuất tính năng mới.

Với các nhà phát triển Việt Nam đang tìm kiếm một giải pháp lưu trữ đồ thị nhẹ, nhúng được và có lịch sử đầy đủ cho ứng dụng AI hoặc di động, Minigraf là một dự án mã nguồn mở đáng để theo dõi.