UUIDv7

Każdy identyfikator rekordu storh jest wartością UUIDv7: zawiera 48-bitowy znacznik czasu w milisekundach, po którym następują losowe dane, a jego format to standardowe UUID o długości 36 znaków. Ponieważ znacznik czasu znajduje się na początku, identyfikatory są sortowane według czasu utworzenia — ta właściwość umożliwia większość funkcji storh: stronicowanie kursorem (after($id)), odczyty zakresów czasu, pomijanie segmentów dziennika i stabilne sortowanie w całym systemie.

$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);

Generowanie w obrębie procesu jest monotoniczne: identyfikatory utworzone w tej samej milisekundzie zwiększają poprzednie losowe dane zamiast losować je ponownie, dzięki czemu nawet szybkie serie zapisów zachowują kolejność utworzenia.

Dostęp według czasu

Dla zakresów czasu storh wyznacza najmniejsze i największe możliwe wartości UUIDv7 dla znacznika czasu w milisekundach i porównuje identyfikatory z tymi granicami:

$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);

Dlatego odczyty zakresów czasu nie wymagają pola znacznika czasu w danych rekordu: identyfikator zawiera czas utworzenia.

Własne identyfikatory

Wszystkie silniki akceptują jawny identyfikator przy każdym zapisie ($docs->put($data, $id)) oraz funkcję id_generator przekazywaną do konstruktorów. Identyfikatory z obu źródeł są weryfikowane jako UUIDv7, więc własne generatory muszą je tworzyć; testy używają generatorów deterministycznych, aby tworzyć powtarzalne zestawy danych. UuidV7::reset_for_tests() czyści monotoniczny stan procesu między przypadkami testowymi.