Show HN: VennDB: ビットフラグを使用してクエリされる行のための、Rust製の追記専用インメモリDB
Show HN: VennDB: append-only in-memory Rust DB for rows queried using bit flags (github.com)
要約
VennDBは、Rustで書かれた追記専用のインメモリデータベースで、ビットフラグ(列)を使用して行をクエリします。主に静的なデータをロードし、単純なフィルターで頻繁にクエリする必要があるユースケース向けに設計されており、従来の選択肢よりも高速かつコンパクトです。
全文翻訳
VennDB
Rust製の追記専用インメモリデータベースで、ビット(フラグ)列を使用してクエリされる行を扱います。このデータベースは、主に静的なデータを起動時にロードし、非常に単純なフィルターで常にクエリする必要があるという非常に特定のユースケースのために設計されています。このようなデータセットは大きくなる可能性があり、高速かつコンパクトである必要があります。
venndbが適用できる限定的なユースケースでは、依存関係はほとんどなく、単純な実装や、Sqliteのようなより重い依存関係よりも高速です。
詳細についてはベンチマークを参照してください。
このプロジェクトは元々ramaの機能として開発されました。例えば、インメモリ(アップストリーム)プロキシデータベースを提供するために使用されているのを見ることができます。もしあなたのプロジェクトでも使用している場合は、お知らせください。ショーケースリストをまとめることができます。
[画像: Crates.io] [画像: Docs.rs] [画像: MIT License] [画像: Apache 2.0 License] [画像: rust version] [画像: Build Status]
[画像: Discord] [画像: Buy Me A Coffee] [画像: GitHub Sponsors]
💬 #venndb公開チャンネルでDiscordにご参加ください。質問、アイデアの議論、venndbがどのように役立つかについてお尋ねください。
Index
venndbマニュアル:
- Usage:
venndbの使用方法に関する簡単な紹介。 - Benchmarks:
venndbが目的とするユースケース(一度書き込み、常に読み込み、主にバイナリフィルターを使用)でどのようにパフォーマンスを発揮するかを大まかに把握するためのベンチマーク結果。 - Q&A: よくある質問(FAQ)。
- Example: 完全な例(Usageの拡張バージョン)、テスト済みで文書化されています。
- Generated Code Summary:
#[derive(VennDB)]を名前付きフィールド構造体に使用したときにvenndbが生成するAPIの文書化された概要。
技術情報:
- Safety
- Compatibility
- MSRV(古いバージョンも動作する可能性がありますが、保証はありません)。
- Roadmap
- License: MITライセンスおよびApache 2.0ライセンス
その他:
Usage
venndbを依存関係として追加します:
cargo add venndb
そして、使用したいモジュールでderiveマクロをインポートします:
use venndb::{Any, VennDB};
#[derive(Debug, VennDB)]
pub struct Employee {
#[venndb(key)]
id: u32,
name: String,
is_manager: Option<bool>,
is_admin: bool,
#[venndb(skip)]
foo: bool,
#[venndb(filter, any)]
department: Department,
#[venndb(filter)]
country: Option<String>,
}
fn main() {
let db = EmployeeDB::from_iter(employees()).expect("unique ids");
let mut query = db.query();
let employee = query
.is_admin(true)
.is_manager(false)
.department(Department::Engineering)
.execute()
.expect("to have found at least one")
.any();
println!("non-manager admin engineer: {:?}", employee);
}
完全な例、例(このドキュメントのコードはこれらから取られています)、または「Generated Code Summary」チャプターを参照して、VennDBとその生成されたコードの使用方法を学んでください。
Benchmarks
ここに表示されているベンチマークは、以下の仕様の開発マシンで取得されたものです:
Macbook Pro — 16 inch (2024), OS: Tahoe 26.5
Chip: Apple M4 Max, Memory: 64 GB
ベンチマークは、ramaのプロキシデータベースのような構造を持つ4つの異なる実装をテストします。7つのboolプロパティと5つのフィルターマップがあり、そのうち状態、都市、ASNはそれぞれ最大1,000、10,000、5,000の異なる値を持つことができます。
venn:venndbバージョン(以下の例と非常によく似ています)。roaring:roaringビットマップのインデックス(バージョン:0.12.0)、手書き。sqlite: 各フィルターマップのインデックスを持つインメモリテーブル(sqliteクレート(バージョン:0.37.4)を使用)。naive: 単純なVec<Proxy>を反復処理するだけ。
最初の2つを除き、各行はクエリです。リストされたフィルターはdb.query()に設定され、その後にany()が続いて一致するプロキシの中からランダムなものを選択します。boolフィルターはtrueを要求し、フィルターマップ(pool、country、city)は1つの値を要求します(複数指定されない限り)。行の1%が任意の値に一致します。数値は中央値時間です。ベンチマークは、just bench-full | python3 scripts/bench_tables.pyを実行して作成されます。
100_000レコードのデータベース:
| venn | roaring | sqlite | naive | |
|---|---|---|---|---|
データベースの作成 (from_rows) | 12.3 ms | 26.52 ms | 344 ms | - |
キーによる検索 (get_by_id) | 10.52 ns | 11.74 ns | 1.347 µs | 7.041 µs |
3つのboolフィルター:tcp + socks5 + datacenter | 246.7 ns | 1.568 µs | 4.135 ms | 653.7 µs |
1つのboolフィルター、1つのフィルターマップ:tcp + country | 1.448 µs | 2.023 µs | 358.4 µs | 862 µs |
2つのboolフィルター、2つのフィルターマップ:tcp + datacenter + country + city | 2.324 µs | 3.898 µs | 153.9 µs | 749.6 µs |
1つのboolフィルター、2つのフィルターマップ:mobile + pool + 3 countries | 2.862 µs | 12.44 µs | 1.366 ms | 343.6 µs |
1つのboolフィルター、1つのフィルターマップ:tcp + 5 cities | 2.112 µs | 6.395 µs | 390.1 µs | 1.013 ms |
3つのboolフィルターと述語:tcp + socks5 + datacenter | 197.2 ns | 134.5 µs | - | 670.1 µs |
3つのboolフィルターとランタイム列:tcp + socks5 + datacenter | 207.3 ns | - | - | - |
| インデックスのメモリ使用量(ピーク時) | 6.483 MB | 7.476 MB | - | - |
1_000_000レコードのデータベース:
| venn | roaring | sqlite | naive | |
|---|---|---|---|---|
データベースの作成 (from_rows) | 121.3 ms | 390.9 ms | 3.838 s | - |
キーによる検索 (get_by_id) | 16.46 ns | 19.88 ns | 1.18 µs | 7.062 µs |
3つのboolフィルター:tcp + socks5 + datacenter | 192 ns | 13.79 µs | 42.23 ms | 6.984 ms |
1つのboolフィルター、1つのフィルターマップ:tcp + country | 2.184 µs | 16.69 µs | 6.929 ms | 8.347 ms |
2つのboolフィルター、2つのフィルターマップ:tcp + datacenter + country + city | 24.57 µs | 30.38 µs | 2.295 ms | 8.565 ms |
1つのboolフィルター、2つのフィルターマップ:mobile + pool + 3 countries | 28.55 µs | 97.05 µs | 12.5 ms | 5.92 ms |
1つのboolフィルター、1つのフィルターマップ:tcp + 5 cities | 3.264 µs | 49.17 µs | 7.098 ms | 10.18 ms |
3つのboolフィルターと述語:tcp + socks5 + datacenter | 216.7 ns | 3.469 ms | - | 7.244 ms |
3つのboolフィルターとランタイム列:tcp + socks5 + datacenter | 222.9 ns | - | - | - |
| インデックスのメモリ使用量(ピーク時) | 61.79 MB | 59.49 MB | - | - |
私たちはデータベースやハードウェアの専門家ではありません。これらのベンチマークが間違っていると思われる場合、または関連する改善が可能であると思われる場合は、イシューを開いてお知らせください。プルリクエストによる貢献も歓迎します。貢献ガイドラインを参照してください。
Q&A
❓ Database Xよりもこれを使うのはなぜですか?
venndbはデータベースではありませんが、特定の目的には十分近いです。多数のバイナリプロパティでフィルターをかけ、ランダムな一致結果を取得する必要がある、長期間読み取り専用のユースケースで真価を発揮します。
通常のデータベースのニーズをこれで置き換えようとしないでください。
❓ 新機能Xやその他の改善を提案できるのはどこですか?
イシューを開いてください。また、貢献ガイドラインも読んでください。皆様からのフィードバックをお待ちしております。
または、Discordに参加して、#venndb公開チャンネルで会話/議論を開始することもできます。
❓
#[venndb(filter)]プロパティには任意の型を使用できますか?
はい、Eq + Hash + Cloneを実装している限り可能です。とはいえ、enum値やその他の高度に制限された形式を使用することを推奨します。
例えば、Stringを直接使用するのは悪い考えです。なぜなら、bE != Be != BE != Belgium != Belgique != Belgiëとなるからです。これらはすべて実際には同じ国を指していますが。そのような場合、ラッパー型(例:struct Country(String))を作成して、値を作成する際にサニタイズ/検証を強制し、概念的に同じ値に対してハッシュが同じであることを保証するのがはるかに良い考えです。
❓ フィルターをオプションにするにはどうすればよいですか?
フィルター(boolプロパティ)とフィルターマップ(#[venndb(filter)]属性を持つT != boolプロパティ)の両方をOptionでラップすることでオプションにできます。これにより、Option<bool>とOption<T>になります。
このようなオプションの列でOption::None値を持つ行は、そのプロパティでフィルターをかけることができませんが、それ以外の結果はありません。
❓ キーは一意でなければならず、オプションであってはならないのはなぜですか?
venndb内では、キーは以前にフィルターを通じて受け取った行を検索できるようにすることを目的としています。
そのため、そのようなキーが次のようになるのは意味がありません:
- 重複:複数の行または間違った行が返される可能性があるため。
- オプション:キーが定義されていない場合にその行を検索できないことを意味するため。
❓ 特定の(フィルター)列の値に対して、一部の行が一致するようにするにはどうすればよいですか?
フィルターマップは、値が他のすべての値に一致することを許可できます。フィルターをそのように宣言し、その型に対してすべてを支配する1つの値を定義するのはあなた次第です。
使用法:
use venndb::{Any, VennDB};
#[derive(Debug, PartialEq, Eq, Clone, Hash, Any)]
pub enum Department {
#[any]
Any,
Hr,
Engineering,
}
#[derive(Debug, VennDB)]
pub struct Employee {
name: String,
#[venndb(filter, any)]
department: Department,
}
let db = EmployeeDB::from_iter([
Employee { name: "Jack".to_owned(), department: Department::Any },
Employee { name: "Derby".to_owned(), department: Department::Hr },
]);
let mut query = db.query();
// JackとDerbyの両方に一致します。JackはAnyとしてマークされているため、任意の値を処理できます。
let hr_employees: Vec<_> = query.department(Department::Hr).execute().unwrap().iter().collect();
assert_eq!(hr_employees.len(), 2);
enumではない型の場合は、venndb::Anyを自分で実装します。そして、あなたのものではない型の場合は、関数を指すことができます:#[venndb(filter, any = is_any)]。
❓ プロパティが複数の値を持つことができるのはどうすればよいですか?
フィルターをsetとしてマークします。行は、その中の各値に一致します:
#[derive(Debug, VennDB)]
pub struct Employee {
name: String,
#[venndb(filter, set)]
skills: HashSet<Skill>,
}
// このスキルを持つすべてのユーザー、または述語がtrueを返すスキルを持つすべてのユーザー(各スキルごとに一度、行ごとではなく呼び出される)。
query.skills(Skill::Rust);
query.skills_where(|skill| matches!(skill, Skill::Language { native: true, .. }));
HashSet、BTreeSet、およびvenndb::FilterSetを実装する任意の型で機能します。Vecのようなリストでは機能しません。あなたのものではない型の場合は、#[venndb(filter, members = path)]を使用します。ここでpathは値のイテレータを返す関数であり、それらの型の型がプロパティからわからない場合はitem = "Type"を使用します。各「フィルターマップ」プロパティには<property>_whereメソッドがあり、any値を持つ行は常にそれに一致します。
❓ プロパティではないもの、または変更されるものに対してフィルターをかけるにはどうすればよいですか?
それに対して列を作成し、クエリに追加します:
// 一度だけ計算される、行のプロパティではない事実に関するもの
let seniors = db.column(|employee| employee.years > 10);
// いつでも、どのスレッドからでも、ロックなしで設定および解除可能
let on_leave = RuntimeColumn::new();
on_leave.set(db.index_by_id(&35).unwrap(), true);
query.is_manager(true).and(Filter::Is(&seniors)).and(Filter::Runtime(&on_leave, false));
最初のものは、データベースが作成されたときの行しか知りませんが、後者の場合は、いつでも行を設定できます。ランタイムの例を参照してください(the runtime example)、データベースが置き換えられた場合の対処法も同様です。どの列にも当てはまらない条件については、EmployeeDBQueryResult::any_where(predicate)があります。
❓ 追加される前にカスタム検証を提供するにはどうすればよいですか?
1つ以上のプロパティに基づいて行を検証することは可能ですか?複数のプロパティ間の関係に関して検証することは可能ですか?カスタム検証ルールに準拠しない行の追加を防ぐためにカスタム検証を提供することは可能ですか?
すべて可能です。
例:
#[derive(Debug, VennDB)]
#[venndb(validator = my_validator_fn)]
pub struct Value {
pub foo: String,
pub bar: u32,
}
fn my_validator_fn(value: &Value) -> bool {
!value.foo.is_empty() && value.bar > 0
}
let mut db = ValueDB::default();
assert!(db.append(Value { foo: "".to_owned(), bar: 42 }).is_err()); // foo == empty のため失敗
❓
anyフィルター値は、そのプロパティにany値を持つ行にのみ一致するのはなぜですか?
たとえば、次のstructがあるとします:
#[derive(Debug, VennDB)]
pub struct Value {
#[venndb(filter, any = is_any)]
pub foo: String,
pub bar: u32,
}
fn is_any(value: &String) -> bool {
value == "*"
}
let db = ValueDB::from_iter([
Value { foo: "foo".to_owned(), bar: 8 },
Value { foo: "*".to_owned(), bar: 16 },
]);
let mut query = db.query();
query.foo("*".to_owned());
let value = query.execute().unwrap().any();
// bar == 8 の行には決して一致しません。foo != any 値のため。
assert_eq!(value.bar, 16);
これはなぜ真実なのですか?それは正しいからです。
foo値がany値にも一致することを許可すると、fooがany値よりも選択される機会が不当に多く与えられます。これは大きな違いではないように見えるかもしれませんが、そうではありません。もし_any値を持つValueに対してランダムな文字列を生成したらどうなるでしょうか?すべての行が一致することを許可すると、そのロジックは台無しになり、fooの値が他の文字列よりも可能性が高くなります。
したがって、any値をフィルターする場合の唯一の正しい答えは、any値を持つ行を返すことです。
❓ 「フィルターマップ」プロパティの複数のバリアントに対してクエリするにはどうすればよいですか?
クエリメソッドを複数回呼び出すだけです。これにより、これらの値のいずれかを持つ行に一致させることができます。
例
#[derive(Debug, VennDB)]
pub struct Value {
#[venndb(filter)]
pub foo: String,
pub bar: u32,
}
let db = ValueDB::from_iter([
Value { foo: "a".to_owned(), bar: 8 },
Value { foo: "b".to_owned(), bar: 12 },
Value { foo: "c".to_owned(), bar: 16 },
]).unwrap();
let mut query = db.query();
query.foo("a".to_owned());
query.foo("c".to_owned());
let values: Vec<_> = query.execute().unwrap().iter().collect();
assert_eq!(values.len(), 2);
assert_eq!(values[0].bar, 8);
assert_eq!(values[1].bar, 16);
Example
ここでは、VennDBのすべての機能を示す例を示します。
生成された内容の概要を好む場合、または以下の例で理解できない点がある場合は、「Generated Code Summary」チャプターを読むこともできます。
use itertools::Itertools;
use venndb::VennDB;
#[derive(Debug, VennDB)]
// これらの属性はオプションです。
// 例:デフォルトでは、データベースは`EmployeeDB`(名前 + 'DB')と呼ばれるでしょう。
#[venndb(name = "EmployeeInMemDB", validator = employee_validator)]
pub struct Employee {
// `key`引数を使用して、このキーで`Employee`インスタンスを直接取得できます。
// これは、キーからデータベース内のそのEmployeeへの参照へのマッピングを効果的に確立します。
// そのため、キーは一意である必要があります。
// そうでない場合は、追加またはDB作成中にエラーが発生します。
//
// 注意:キーは一意であるだけでなく、`Clone`を実装している必要があります!!
//
// プロパティはフィルターとキーを同時に行うことはできません。
// そうしようとすると、コンパイルエラーが発生します。
#[venndb(key)]
id: u32,
name: String,
is_manager: bool,
is_admin: bool,
// boolフィルターはオプションにできます。
// これは、行が`None`値を持っている場合に、その列でフィルター(検索)できないことを意味します。
is_active: Option<bool>,
// boolは自動的に(クエリ)フィルターに変換されます。
// これを停止するには`skip`引数を使用します。そのため、boolプロパティにのみ本当に必要です。
#[venndb(skip)]
foo: bool,
// bool以外の値もフィルターに変換でき、2Dフィルターになります。
// 挿入される各一意のDepartmentバリアントについて、
// 新しいフィルターが追跡されます。これにより、部署に基づく(クエリ)フィルターを適用できます。
// これは非常に便利な機能です。
//
// 注意:これは、そのようなフィルターマップ型も次の条件を満たす必要があることを意味します:
// `PartialEq + Eq + Hash + Clone`!!
//
// プロパティはフィルターとキーを同時に行うことはできません。
// そうしようとすると、コンパイルエラーが発生します。
#[venndb(filter)]
department: Department,
// 通常のboolフィルターと同様に、
// フィルターマップもオプションにできます。
// オプションのフィルターマップで、行のプロパティがNoneの場合、
// それは登録されず、そのプロパティでフィルター(検索)できなくなります。
#[venndb(filter)]
country: Option<String>,
}
fn employee_validator(employee: &Employee) -> bool {
employee.id > 0
}
fn main() {
let db = EmployeeInMemDB::from_iter([
RawCsvRow("1,John Doe,true,false,true,false,Engineering,USA"),
RawCsvRow("2,Jane Doe,false,true,true,true,Sales,"),
RawCsvRow("3,John Smith,false,false,,false,Marketing,"),
RawCsvRow("4,Jane Smith,true,true,false,true,HR,"),
RawCsvRow("5,John Johnson,true,true,true,true,Engineering,"),
RawCsvRow("6,Jane Johnson,false,false,,false,Sales,BE"),
RawCsvRow("7,John Brown,true,false,true,false,Marketing,BE"),
RawCsvRow("8,Jane Brown,false,true,true,true,HR,BR"),
])
.expect("MemDB created without errors (e.g. no duplicate keys)");
println!(">>> Printing all employees...");
let all_employees: Vec<_> = db.iter().collect();
assert_eq!(all_employees.len(), 8);
println!("All employees: {:#?}", all_employees);
println!(">>> You can lookup an employee by any registered key...");
let employee = db
.get_by_id(&2)
.expect("to have found an employee with ID 2");
assert_eq!(employee.name, "Jane Doe");
println!(">>> Querying for all managers...");
let mut query = db.query();
query.is_manager(true);
let managers: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(managers.len(), 4);
assert_eq!(
managers.iter().map(|e| e.id).sorted().collect::<Vec<_>>(),
[1, 4, 5, 7]
);
println!(">>> Querying for all managers with a last name of 'Johnson'...");
let managers_result = query
.execute()
.expect("to have found at least one")
.filter(|e| e.name.ends_with("Johnson"))
.expect("to have found a manager with a last name of Johnson");
let managers = managers_result.iter().collect::<Vec<_>>();
assert_eq!(managers.len(), 1);
assert_eq!(managers.iter().map(|e| e.id).collect::<Vec<_>>(), [5]);
println!(">>> You can also just get the first result if that is all you care about...");
let manager = managers_result.first();
assert_eq!(manager.id, 5);
println!(">>> Querying for a random active manager in the Engineering department...");
let manager = query
.reset()
.is_active(true)
.is_manager(true)
.department(Department::Engineering)
.execute()
.expect("to have found at least one")
.any();
assert!(manager.id == 1 || manager.id == 5);
println!(">>> Optional bool filters have three possible values, where None != false. An important distinction to make...");
let mut query = db.query();
query.is_active(false);
let inactive_employees: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(inactive_employees.len(), 1);
assert_eq!(inactive_employees[0].id, 4);
println!(">>> If you want you can also get the Employees back as a Vec, dropping the DB data all together...");
let employees = db.into_rows();
assert_eq!(employees.len(), 8);
assert!(employees[1].foo);
println!("All employees: {:?}", employees);
println!(">>> You can also get the DB back from the Vec, if you want start to query again...");
// of course better to just keep it as a DB to begin with, but let's pretend this is ok in this example
let mut db = EmployeeInMemDB::from_rows(employees).expect("DB created without errors");
assert_eq!(db.iter().count(), 8);
println!(">>> Querying for all active employees in the Sales department...");
let mut query = db.query();
query.is_active(true);
query.department(Department::Sales);
let sales_employees: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(sales_employees.len(), 1);
assert_eq!(sales_employees[0].name, "Jane Doe");
println!(">>> Filter maps that are optional work as well, e.g. you can query for all employees from USA...");
query.reset().country("USA".to_owned());
let usa_employees: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(usa_employees.len(), 1);
assert_eq!(usa_employees[0].id, 1);
println!(">>> At any time you can also append new employees to the DB...");
assert_eq!(EmployeeInMemDBErrorKind::DuplicateKey, db
.append(RawCsvRow("8,John Doe,true,false,true,false,Engineering,"))
.unwrap_err().kind());
println!(">>> This will fail however if a property is not correct (e.g. ID (key) is not unique in this case), let's try this again...");
assert!(db
.append(RawCsvRow("9,John Doe,false,true,true,false,Engineering,"))
.is_ok());
assert_eq!(db.len(), 9);
println!(">>> Rows are also validated prior to appending in case a validator is defined...");
println!(" The next insertion will fail due to the id being zero, a condition defined in the custom validator...");
assert_eq!(EmployeeInMemDBErrorKind::InvalidRow, db
.append(RawCsvRow("0,John Doe,true,false,true,false,Engineering,"))
.unwrap_err().kind());
println!(">>> This new employee can now also be queried for...");
let mut query = db.query();
query.department(Department::Engineering).is_manager(false);
let new_employee: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(new_employee.len(), 1);
assert_eq!(new_employee[0].id, 9);
println!(">>> You can also extend it using an IntoIterator...");
db.extend([
RawCsvRow("10,Glenn Doe,false,true,true,true,Engineering,"),
RawCsvRow("11,Peter Miss,true,true,true,true,HR,USA"),
])
.unwrap();
let mut query = db.query();
query
.department(Department::HR)
.is_manager(true)
.is_active(true)
.is_admin(true);
let employees: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(employees.len(), 1);
assert_eq!(employees[0].id, 11);
println!(">>> There are now 2 employees from USA...");
query.reset().country("USA".to_owned());
let employees: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(employees.len(), 2);
assert_eq!(
employees.iter().map(|e| e.id).sorted().collect::<Vec<_>>(),
[1, 11]
);
println!(">>> All previously data is still there as well of course...");
query
.reset()
.is_active(true)
.is_manager(true)
.department(Department::Engineering);
let managers: Vec<_> = query
.execute()
.expect("to have found at least one")
.iter()
.collect();
assert_eq!(managers.len(), 2);
assert_eq!(
managers.iter().map(|e| e.id).sorted().collect::<Vec<_>>(),
[1, 5]
);
}
#[derive(Debug)]
struct RawCsvRow<S>(S);
impl<S>
From<RawCsvRow<S>>
for Employee
where
S: AsRef<str>,
{
fn from(RawCsvRow(s): RawCsvRow<S>) -> Employee {
let mut parts = s.as_ref().split(',');
let id = parts.next().unwrap().parse().unwrap();
let name = parts.next().unwrap().to_string();
let is_manager = parts.next().unwrap().parse().unwrap();
let is_admin = parts.next().unwrap().parse().unwrap();
let is_active = match parts.next().unwrap() {
"" => None,
s => Some(s.parse().unwrap()),
};
let foo = parts.next().unwrap().parse().unwrap();
let department = parts.next().unwrap().parse().unwrap();
let country = match parts.next().unwrap() {
"" => None,
s => Some(s.to_string()),
};
Employee {
id,
name,
is_manager,
is_admin,
is_active,
foo,
department,
country,
}
}
}
#[derive(Debug, PartialEq, Eq, Hash, Clone)]
pub enum Department {
Engineering,
Sales,
Marketing,
HR,
}
impl std::str::FromStr for Department {
type Err = ();
fn from_str(s: &str) -> Result<Self, Self::Err> {
match s {
"Engineering" => Ok(Department::Engineering),
"Sales" => Ok(Department::Sales),
"Marketing" => Ok(Department::Marketing),
"HR" => Ok(Department::HR),
_ => Err(()),
}
}
}
Generated Code Summary
このチャプターでは、上記の例コードのためにVennDBによって生成されるAPIをリストします:
#[derive(Debug, VennDB)]
#[venndb(name = "EmployeeInMemDB", validator = employee_validator)]
pub struct Employee {
#[venndb(key)]
id: u32,
name: String,
is_manager: bool,
is_admin: bool,
is_active: Option<bool>,
#[venndb(skip)]
foo: bool,
#[venndb(filter)]
department: Department,
country: Option<String>,
}
以下の公開APIデータ構造体が生成されます:
struct EmployeeInMemDB: データベース。フィルターによるクエリ(フィルター)またはデータ(キー)による検索に使用できます。enum EmployeeInMemDBError: データベースを変更する際に、挿入される行のプロパティでエラーが発生した場合に返されるエラータイプ。enum EmployeeInMemDBErrorKind:EmployeeInMemDBErrorで説明されているエラーの種類。struct EmployeeInMemDBQuery: フィルターを使用してデータベースをクエリするクエリを実行するために使用されるクエリビルダー。デフォルトのビルダーはすべての行に一致します。struct EmployeeInMemDBQueryResult:EmployeeInMemDBQueryを使用してクエリした結果。少なくとも1行が見つかった場合に返されます。
これらのデータ構造体の視覚的な指定子は、VennDBマクロが適用されるstructと同じになります。例:この例ではEmployeeはpubの指定子を持っているため、上記のデータ構造体とその公開APIメソッドもpubになります。
これらは、venndb自体にあるRowSet、ValueColumn、Planなどの型から構築されており、マクロなしで(default-features = false)直接使用することもできます。生成された構造体を外部に公開したくない場合は、structを独自のmod(モジュール)でラップできます。
Generated Code Summary: Method API
データベース(例:EmployeeInMemDB):
| fn signature | description |
|---|---|
EmployeeInMemDB::new() -> EmployeeInMemDB | 容量ゼロの新しいデータベースを作成します |
EmployeeInMemDB::default() -> EmployeeInMemDB | EmployeeInMemDB::new() -> EmployeeInMemDBと同じです |
EmployeeInMemDB::with_capacity(capacity: usize) -> EmployeeInMemDB | 指定された容量で新しいデータベースを作成しますが、行はまだ挿入されていません |
EmployeeInMemDB::from_rows(rows: ::std::vec::Vec<Employee>) -> EmployeeInMemDB または EmployeeInMemDB::from_rows(rows: ::std::vec::Vec<Employee>) -> Result<EmployeeInMemDB, EmployeeInMemDBError<::std::vec::Vec<Employee>>> | ヒープ割り当てされたデータインスタンスのリストから直接データベースを作成するためのコンストラクタ。2番目のバージョンは、少なくとも1つの#[venndb(key)]プロパティまたはvalidatorが定義されている場合に使用され、それ以外の場合は最初のバージョン(Resultなし)です。 |
EmployeeInMemDB::from_iter(iter: impl ::std::iter::IntoIterator<Item = impl ::std::convert::Into<Employee>>) -> EmployeeInMemDB または EmployeeInMemDB::from_rows(iter: impl ::std::iter::IntoIterator<Item = impl ::std::convert::Into<Employee>>) -> Result<EmployeeInMemDB, EmployeeInMemDBError<::std::vec::Vec<Employee>>> | from_rowsと同じですが、イテレータを使用します。アイテムはEmployeeである必要はなく、Employeeに変換できるものであれば何でも構いません。例:上記の例では、RawCsvRowという構造体を定義し、それをオンザフライでEmployeeに変換しました。これはデータベース挿入前にすべて一度に行われるため、結果を返すバージョンはイテレータではなくVecを返します。 |
EmployeeInMemDB::append(&mut self, data: impl ::std::convert::Into<Employee>) または EmployeeInMemDB::append(&mut self, data: impl ::std::convert::Into<Employee>) -> Result<(), EmployeeInMemDBError<Employee>> | データベースに1行を追加します。#[venndb(key)]プロパティが定義されているかどうかに応じて、Resultバージョンが生成されるかどうかが決まります。from_rowsおよびfrom_iterと同様です。 |
EmployeeInMemDB::extend<I, Item>(&mut self, iter: I) where I: ::std::iter::IntoIterator<Item = Item>, Item: ::std::convert::Into<Employee> または EmployeeInMemDB::extend<I, Item>(&mut self, iter: I) -> Result<(), EmployeeInMemDBError<(Employee, I::IntoIter)>> where I: ::std::iter::IntoIterator<Item = Item>, Item: ::std::convert::Into<Employee> | 指定されたイテレータでデータベースを拡張します。挿入が失敗する可能性がある場合(例:キーが使用されている(重複)またはバリデーターが定義されている場合に無効な行)、結果を返します。それ以外の場合は、この関数は何も返しません。 |
EmployeeInMemDB::get_by_id<Q>(&self, data: impl ::std::convert::Into<Employee>) -> Option<&Employee> where Employee ::std::borrow::Borrow<Q>, Q: ::std::hash::Hash + ::std::cmp::Eq + ?::std::marker::Sized | idキープロパティで1行を検索します。このメソッドは、#[venndb(key)]でマークされた各プロパティに対して生成されます。例:foo: MyTypeというキープロパティがある場合、get_by_foo(&self, ...)メソッドも生成されます。 |
EmployeeInMemDB::index_by_id<Q>(&self, key: &Q) -> Option<usize> および EmployeeInMemDB::get(&self, index: usize) -> Option<&Employee> | 列で使用されるキーの行インデックス、およびインデックスの行。 |
EmployeeInMemDB::column(&self, predicate: impl FnMut(&Employee) -> bool) -> venndb::RowSet | Filter::IsまたはFilter::Notでクエリに追加する述語に一致する行。 |
EmployeeInMemDB::shrink_to_fit(&mut self) | 必要のないメモリを解放します。from_rowsおよびfrom_iterによって自動的に行われます。 |
EmployeeInMemDB::query(&self) -> EmployeeInMemDBQuery | データベースをクエリするためのフィルター構成を構築するEmployeeInMemDBQueryビルダーを作成します。デフォルトのビルダーはすべての行に一致します。詳細については、EmployeeInMemDBQueryのメソッドAPIを参照してください。 |
クエリ(例:EmployeeInMemDBQuery)
| fn signature | description |
|---|---|
EmployeeInMemDBQuery::reset(&mut self) -> &mut Self | クエリをリセットし、作成時のクリーンな状態に戻します。 |
EmployeeInMemDBQuery::execute(&self) -> Option<EmployeeInMemDBQueryResult<'a>> | 設定されたフィルターを使用してクエリの結果を返します。一致する行がない場合はNoneになります。言い換えれば、Some(_)が返された場合、結果には少なくとも1行が含まれます。 |
EmployeeInMemDBQuery::is_manager(&mut self, value: bool) -> &mut Self | boolフィルターの設定メソッド。skipされていない各boolフィルターに対して1つのメソッドが利用可能になります。例:fooフィルターがある場合、EmployeeInMemDBQuery:fooメソッドが存在します。オプションのboolフィルター(Option<bool>)の場合も、このメソッドは同じように生成されます。 |
EmployeeInMemDBQuery::department(&mut self, value: impl ::std::convert::Into<Department>) -> &mut Self | bool以外のフィルターの設定メソッド。各非boolフィルターに対して1つのメソッドが利用可能になります。これらをskipすることもできますが、それは少し無意味です。型は実際のフィールド型と同じになります。そして、名前は元のフィールド名と同じになります。Option<T>型を持つフィルターマップもまったく同じシグネチャを持ちます。クエリ中に、複数のバリアントを許可したい場合は、このメソッドを複数回呼び出すことができます。 |
| EmployeeInMemDBQuery::department_ref<Q>(&mut self, value: &Q) -> &mut Self | 同様ですが、借用された値(例:Stringフィルターに対する&str)用です。 | | EmployeeInMemDBQuery::department_where(&mut self, predicate: impl FnMut(&Department) -> bool) -> &mut Self | 述語がtrueを返す値に対するフィルター。各一意の値に対して1回呼び出され、行ごとではありません。各非boolフィルターに対して1つのメソッドがあります。 | | EmployeeInMemDBQuery::and(&mut self, filter: venndb::Filter<'a>) -> &mut Self | columnで作成された列、またはいつでも行を設定できるvenndb::RuntimeColumnに対するフィルターを追加します。 | | EmployeeInMemDBQuery::any(&self) -> Option<&Employee> および EmployeeInMemDBQuery::any_where(&self, predicate: impl FnMut(&Employee) -> bool) -> Option<&Employee> | フィルターに一致するランダムに選択された従業員を返します。多くの行が一致するフィルターの場合、これはexecuteの後にanyを実行するよりもはるかに高速です。なぜなら、すべてのマッチを処理するのではなく、ランダムな行を試すからです。 |
クエリ結果(例:EmployeeInMemDBQueryResult)
| fn signature | description |
|---|---|
EmployeeInMemDBQueryResult::first(&self) -> &Employee | 最初に見つかった一致する従業員への参照を返します。実装上の詳細として、これは最初に追加された一致する行になりますが、互換性の理由から、可能であればこれに依存しない方が良いでしょう。 |
EmployeeInMemDBQueryResult::any(&self) -> &Employee | 一致するランダムに選択された従業員への参照を返します。ランダム性は公平であることが保証されています。 |
EmployeeInMemDBQueryResult::len(&self) -> usize | 一致した従業員の数。ゼロになることはありません。 |
EmployeeInMemDBQueryResult::any_where(&self, predicate: impl FnMut(&Employee) -> bool) -> Option<&Employee> | 述語がtrueを返す一致するランダムに選択された従業員を返します。すべてをテストする前に、いくつかのランダムなものを試します。 |
EmployeeInMemDBQueryResult::iter(&self) -> impl Iterator<Item = &Employee> | クエリ結果のイテレータを返します。これにより、すべての結果を反復処理し、必要に応じて所有データ構造に収集することもできます。 |
EmployeeInMemDBQueryResult::filter(&self, predicate: impl FnMut(&Employee) -> bool) -> Option<EmployeeInMemDBQueryResult> | 与えられたFn述語に従って一致するインデックスのみを含む(そして所有する)同じ参照データを持つSome(_) EmployeeInMemDBQueryResultを返します。 |
⛨ | Safety
このクレートは、すべてが100%安全なRustで実装されていることを保証するために#![forbid(unsafe_code)]を使用しています。
🦀 | Compatibility
venndbは主にMacOS Mシリーズマシンで開発され、さまざまなLinuxシステムで本番稼働しています。Windowsのサポートは公式には保証されていませんが、Github Actionsでテスト済みで成功しています。
| platform | tested | test platform |
|---|---|---|
| MacOS | ✅ | M4 Max (developer laptop) and macOS 26 arm64 (GitHub Action) |
| Windows | ✅ | Windows Server 2025 (GitHub Action) |
| Linux | ✅ | Ubuntu 24.04 (GitHub Action) |
お使いのセットアップ/プラットフォームとの互換性の問題が発生した場合は、チケットを開いてください。私たちの目標は、世界のすべてのプラットフォームをサポートすることではありませんが、合理的にサポートできる限り多くのプラットフォームをサポートしたいと考えています。
Minimum supported Rust version
venndbのMSRVは1.96です。
GitHub Actionsを使用して、venndbがそのバージョンでrustの安定版およびベータ版でも引き続き機能するかどうかをテストしています。
🧭 | Roadmap
ロードマップについては、https://github.com/plabayo/venndb/milestonesを参照してください。次のバージョンにロードマップにないが、本当に欲しいものはありますか?機能リクエストを作成してリクエストし、可能であればスポンサーになることも検討してください。
💼 | License
このプロジェクトは、MITライセンスとApache 2.0ライセンスの両方でデュアルライセンスされています。
👋 | Contributing
🎈 プロジェクトの改善にご協力いただきありがとうございます!皆様のおかげで、私たちは非常に幸せです!貢献ガイドを用意しており、皆様の参加を支援します。
貢献は、多くの場合、バグの修正や欠けている機能など、すでに望むものを知っている人々から寄せられます。常に、まだ存在しない場合はチケットを作成してください。
しかし、具体的に何を貢献すべきかわからないが、それでも助けたいと思うかもしれません。その場合は感謝いたします。オープンなイシュー、特に次のものを確認できます。
good first issue:venndbのコードベースに新しい方向けのイシュー。easy: 簡単と見なされるイシュー。
|mentor available: メンターシップを提供するイシュー。
|low prio: すぐに完了する必要のない低優先度のイシュー。限られた時間しか割けない場合に役立ちます。
一般的に、まだ割り当てられていないイシューは誰でも自由にピックアップできます。同じイシューに複数の人が取り組むのを避けるために、ピックアップする予定がある場合は、必ずチケットでコミュニケーションを取ってください。
このプロジェクトに貢献したいが、まだRustでプログラミングする方法がわからない場合は、「the Rust 101 Learning Guide」を学習コンパニオンとして使用して、できるだけ早くvenndbに貢献することを目標にRustを学び始めることができます。Glenはメンターまたは教師として雇われ、有料の1対1レッスンやその他の同様のコンサルティングサービスを提供することもできます。彼の連絡先はhttps://www.glendc.com/にあります。
Contribution
明示的に述べない限り、あなたが意図的にvenndbへの含めるために提出した貢献は、追加の条件なしに、MITおよびApache 2.0の両方のライセンスで提供されます。
Acknowledgements
Rustプログラミング言語の開発、保守、サポートに関わったすべての人々に特別な感謝を捧げます。また、Sam Van Overmeire著「Write Powerful Rust Macros」にも大きな shoutout を送ります。この本は、このクレートを開発する勇気を与えてくれました。
一部のコードはgoogle/arghからコピー/フォークされており、それにも感謝します。私たちはそのクレートの大ファンです。CLIアプリを作成したい場合は、それを使用してください。
💖 | Sponsors
venndbは完全に無料のオープンソースソフトウェアであり、開発と保守には多くの労力と時間が必要です。
スポンサーになることで、このプロジェクトをサポートしてください。一度限りの支払いもGitHubおよび「Buy me a Coffee」(https://www.buymeacoffee.com/plabayo)で受け付けています。
スポンサーは、私たちがvenndbやその他のフリーおよびオープンソース(FOSS)テクノロジーのメンテナンスと改善を継続するのに役立ちます。また、https://github.com/plabayo/learn-rust-101のような教育コンテンツや、https://github.com/plabayo/ramaのような他のオープンソースフレームワークの作成にも役立ちます。
スポンサーは特典を受けられ、定期的な貢献度によってはサポートやコンサルティングを私たちに依存することもできます。
最後に、Plabayo <3 VennDBのマーチャンダイズ🛍️をhttps://plabayo.threadless.com/で購入することでもサポートできます。