# 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](https://storh.inline0.dev/pt/docs/query-builder); 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:

```php
$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:

```php
$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:

```php
$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](https://storh.inline0.dev/pt/docs/cli).