UUIDv7

Идентификатор каждой записи storh — это UUIDv7: 48-битная временная метка в миллисекундах, за которой следует случайная энтропия; формат — стандартный UUID из 36 символов. Поскольку временная метка стоит в начале, идентификаторы сортируются по времени создания, и это свойство лежит в основе большинства функций 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);

В пределах одного процесса генерация монотонна: идентификаторы, созданные в одну и ту же миллисекунду, увеличивают предыдущую случайную часть, а не генерируют ее заново. Поэтому даже при резком всплеске записей сохраняется порядок их создания.

Обращение по времени

Для временных интервалов storh вычисляет наименьшее и наибольшее возможные значения UUIDv7 для временной метки в миллисекундах и сравнивает идентификаторы с этими границами:

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

Именно поэтому для чтения за временной интервал не нужно хранить временную метку в данных записи: время создания уже содержится в идентификаторе.

Собственные идентификаторы

Все движки принимают явный идентификатор для каждой записи ($docs->put($data, $id)) и функцию id_generator в конструкторах. Идентификаторы из обоих источников проверяются как UUIDv7, поэтому собственные генераторы должны создавать идентификаторы в этом формате; детерминированные генераторы позволяют тестовому набору создавать воспроизводимые тестовые данные. UuidV7::reset_for_tests() очищает состояние монотонной генерации на уровне процесса между тестовыми случаями.