Consultas

RecordQuery é o filtro em fluxo usado com stream(). Ele cobre os padrões de acesso com inserção de registros: continuar após um cursor, ler uma janela de tempo, filtrar por igualdade de campo e parar ao atingir um limite. Para predicados mais elaborados, ordenação e buscas com índices, use o construtor de consultas; para tudo o que um foreach comum em um fluxo pode fazer, RecordQuery é a opção mais econômica.

RecordQuery é imutável. Cada modificador retorna uma consulta clonada:

$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() e time_range_ms() usam a ordem de UUID, então não precisam de um campo de data e hora nos dados do registro. Em SegmentedLog, também evitam trabalho: segmentos cujo intervalo de IDs fica fora da janela nunca são abertos, e índices esparsos por segmento buscam perto do primeiro registro correspondente, em vez de examinar os registros desde o início.

where_equal() compara um campo de dados de nível superior com === e aceita valores escalares ou null. Um filtro null corresponde a registros em que o campo está presente e é nulo; registros sem o campo não correspondem.

Paginação por cursor

Os IDs são ordenados por data de criação, então o último ID de uma página serve de cursor para a próxima:

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

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

Como lidar com registros corrompidos

Por padrão, uma varredura gera um erro ao encontrar o primeiro registro ilegível. Use continue_on_error() quando a varredura deve ignorá-lo e informar a falha em vez disso:

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

A localização é o ID do registro para DocStore e segment-file:byte-offset para SegmentedLog. repair() é a ferramenta para limpar registros corrompidos; consulte CLI.