# UUIDv7

Идентификатор каждой записи storh — это UUIDv7: 48-битная временная метка в миллисекундах, за которой следует случайная энтропия; формат — стандартный UUID из 36 символов. Поскольку временная метка стоит в начале, идентификаторы сортируются по времени создания, и это свойство лежит в основе большинства функций storh: пагинации по курсору (`after($id)`), чтения за период времени, пропуска сегментов в журнале и стабильной сортировки повсюду.

```php
$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 для временной метки в миллисекундах и сравнивает идентификаторы с этими границами:

```php
$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()` очищает состояние монотонной генерации на уровне процесса между тестовыми случаями.