UUIDv7

storhの各レコードIDはUUIDv7です。48ビットのミリ秒単位のタイムスタンプにランダムなエントロピーを続け、標準の36文字のUUID形式で表します。先頭にタイムスタンプがあるため、IDは作成時刻順に並びます。この特性がstorhの多くの機能を支えています。カーソルページネーション（after($id)）、時間範囲読み取り、ログ内のセグメントスキップ、あらゆる場所での安定した順序付けが可能です。

$id = Storh\UuidV7::generate();

Storh\UuidV7::is_valid($id);          // bool, accepts upper and lower case
Storh\UuidV7::assert_valid($id);      // throws StorageException instead
$timestampMs = Storh\UuidV7::timestamp_ms($id);

プロセス内では単調に増加します。同じミリ秒内に作成されるIDは、エントロピーを再生成する代わりに直前の値を増やすため、短時間に書き込みが集中しても作成順に並びます。

時刻による特定

時刻の範囲を指定すると、storhはミリ秒単位のタイムスタンプに対してUUIDv7が取り得る最小値と最大値を求め、IDをその範囲と比較します。

$query = Storh\RecordQuery::all()->time_range_ms(
    1_700_000_000_000,
    1_700_000_060_000,
);

$lower = Storh\UuidV7::min_for_timestamp_ms(1_700_000_000_000);
$upper = Storh\UuidV7::max_for_timestamp_ms(1_700_000_060_000);

このため、時間範囲の読み取りではレコードデータにタイムスタンプフィールドを含める必要がありません。ID自体に作成時刻が含まれています。

独自のIDを指定する

すべてのエンジンで、書き込みごとのID（$docs->put($data, $id)）を明示的に指定できます。また、コンストラクターでid_generatorの呼び出し可能オブジェクトを指定できます。どちらの方法でもIDはUUIDv7として検証されるため、独自ジェネレーターもUUIDv7を生成する必要があります。決定的なジェネレーターは、テストスイートで再現可能なフィクスチャを作るために使われます。UuidV7::reset_for_tests()はテストケース間でプロセスレベルの単調増加状態をリセットします。