UUIDv7

Ogni id record storh è un UUIDv7: un timestamp in millisecondi a 48 bit seguito da entropia casuale, formattato come UUID standard di 36 caratteri. Poiché il timestamp è all'inizio, gli id si ordinano per orario di creazione; questa proprietà alimenta gran parte di storh: la paginazione tramite cursore (after($id)), le letture per intervallo temporale, il salto dei segmenti nel log e un ordinamento stabile ovunque.

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

La generazione è monotona all'interno di un processo: gli id creati nello stesso millisecondo incrementano l'entropia precedente invece di ricalcolarla, così anche le raffiche rapide di scritture mantengono l'ordine di creazione.

Riferimento temporale

Per gli intervalli temporali, storh ricava il valore minimo e massimo possibile di UUIDv7 per un timestamp in millisecondi e confronta gli id con questi limiti:

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

Ecco perché le letture per intervallo temporale non richiedono un campo timestamp nei dati del record: l'id contiene l'ora di creazione.

Fornire id personalizzati

Tutti i motori accettano un id esplicito per ogni scrittura ($docs->put($data, $id)) e una funzione id_generator nei rispettivi costruttori. Gli id generati da entrambi i metodi vengono convalidati come UUIDv7, quindi i generatori personalizzati devono produrli; i generatori deterministici permettono alla suite di test di creare fixture riproducibili. UuidV7::reset_for_tests() azzera lo stato di monotonicità a livello di processo tra un caso di test e l'altro.