Requêtes

RecordQuery est le filtre en continu utilisé avec stream(). Il couvre les modes d’accès axés sur les ajouts : reprendre après un curseur, lire une fenêtre temporelle, filtrer par égalité sur un champ et s’arrêter à une limite. Pour des prédicats plus riches, le tri et les recherches avec index, utilisez le constructeur de requêtes ; pour tout ce qu’un foreach classique peut faire sur un flux, RecordQuery est l’outil le plus léger.

RecordQuery est immuable. Chaque modificateur renvoie une requête clonée :

$query = Storh\RecordQuery::all()
    ->after($lastSeenId)
    ->time_range_ms($fromMs, $untilMs)
    ->where_equal('kind', 'page')
    ->limit(100);

foreach ($store->stream($query) as $record) {
    // Records are yielded lazily.
}

after() et time_range_ms() utilisent l’ordre UUID ; aucun champ d’horodatage n’est donc nécessaire dans les données de l’enregistrement. Sur SegmentedLog, ils évitent aussi du travail : les segments dont la plage d’identifiants est hors fenêtre ne sont jamais ouverts, et les index clairsemés par segment permettent d’accéder près du premier enregistrement correspondant au lieu de parcourir les données depuis le début.

where_equal() compare un champ de données de premier niveau à === et accepte des valeurs scalaires ou null. Un filtre null correspond aux enregistrements où le champ est présent et vaut null ; les enregistrements sans ce champ ne correspondent pas.

Pagination par curseur

Les identifiants sont triés par heure de création ; le dernier identifiant d’une page sert donc de curseur pour la suivante :

$page = iterator_to_array($store->stream(
    Storh\RecordQuery::all()->after($lastSeenId)->limit(100)
), false);

$lastSeenId = [] === $page ? $lastSeenId : end($page)->id();

Conserver les enregistrements corrompus

Par défaut, un parcours s’interrompt à la première lecture d’un enregistrement illisible. Utilisez continue_on_error() si le parcours doit l’ignorer et signaler l’échec à la place :

$query = Storh\RecordQuery::all()->continue_on_error(
    static function (string $location, Throwable $error): void {
        error_log($location . ': ' . $error->getMessage());
    },
);

L’emplacement correspond à l’ID d’enregistrement de DocStore et segment-file:byte-offset pour SegmentedLog. repair() est l’outil qui permet de nettoyer les enregistrements corrompus ; voir CLI.