はじめに | AkkaraDB Native

最初は高レベルの AkkaraDB / PackedTable API を選んでください。通常の C++ 構造体を BinPack で保存し、主キー、走査、インデックスを独自のバイトレイアウトなしで扱えます。

独自のキーレイアウトやバイトエンコードをアプリケーション側で管理する場合だけ、低レベルの AkkEngine API を選びます。

1. Native ライブラリをビルドする

AkkaraDB Native は LLVM Clang を必要とします。Windows では Visual Studio の開発者環境内の clang-cl、Linux/macOS では clang++ を使います。

cmake --preset release
cmake --build --preset release

Windows では最初に Visual Studio environment を初期化します。

cmd /c "call \"C:\Program Files\Microsoft Visual Studio\18\Community\VC\Auxiliary\Build\vcvars64.bat\" >nul && cmake --preset windows-clang-cl-release && cmake --build --preset windows-clang-cl-release"

インストール済みパッケージを使う場合は、アプリケーションの CMake から Native target をリンクします。

find_package(AkkaraDB REQUIRED)
target_link_libraries(my_app PRIVATE AkkaraDB::akkaradb)

2. 行を定義してデータベースを開く

保存し、型付きクエリヘルパーから使うフィールドをマクロで登録します。型名の次の引数が主キーです。

#include "akkaradb/AkkaraDB.hpp"

#include <cstdint>
#include <iostream>
#include <string>

struct User {
    uint64_t id;
    std::string email;
    std::string name;
    uint32_t age;
};

AKKARADB_ENTITY(User, id, email, name, age)

int main() {
    auto db = akkaradb::AkkaraDB::open("data/app", akkaradb::StartupMode::NORMAL);
    auto users = db->table<&User::id>("users");

NORMAL は組み込み用途の標準プロファイルです。同期 WAL と VersionLog が必要なら DURABLE、低オーバーヘッドなローカル用途なら FAST を選びます。プロファイルの詳細は AkkaraDB を参照してください。

3. 書き込み、読み取り、走査

put() は主キーにより行を insert または置換します。get() は std::optional<T> を返すため、存在しない場合を明示的に扱います。

    users.put(User{1, "alice@example.test", "Alice", 30});

    if (const auto alice = users.get(1)) {
        std::cout << alice->name << " is " << alice->age << "\n";
    }

    auto rows = users.scanAll();
    while (rows.hasNext()) {
        const auto row = rows.next();
        std::cout << row.value.email << "\n";
    }

テーブル名とエンティティのフィールド順序は、保存済みデータの互換性に含まれます。テーブル名の変更やフィールドの並べ替え・型変更は、移行として扱ってください。

4. インデックスを使う前に登録する

インデックスはテーブルを開いた直後、インデックス経由で見つけたい行を書き込む前に登録します。登録後の書き込みでは維持されますが、既存行は自動で再構築されません。

    users.indexed<&User::email>()
         .indexed<&User::age>();

    users.put(User{2, "bob@example.test", "Bob", 24});

    if (const auto bob = users.findBy<&User::email>("bob@example.test")) {
        std::cout << bob->name << "\n";
    }

文字列の接頭辞クエリを頻繁に行う場合は、prefixIndexed<&Field>() を別に使います。これは等価検索用の通常インデックスを置き換えません。

5. 明示的に閉じる

最後のテーブル操作後に close() すると、プロセス終了前に設定済みのフラッシュ / 同期方針が実行されます。

    db->close();
}

次に読むもの

更新、クエリ、参照、結合、スキーマフックは高レベル API の使い方。
型付き式とインデックス計画は Query。
バイト指向の保存制御が必要な場合は低レベル API。
別プロセスから HTTP、TCP、gRPC で使う場合は API サーバー。