# Päringud

`RecordQuery` on voogedastusega filter, mida kasutatakse koos `stream()`-ga. See katab lisamispõhised kasutusjuhtumid: jätkamine kursori järel, ajavahemiku lugemine, väljade võrdsuse järgi filtreerimine ja tulemuste arvu piiramine. Keerukamate tingimuste, järjestamise ja indeksipõhiste otsingute jaoks kasuta [päringukoostajat](https://storh.inline0.dev/et/docs/query-builder); kõige jaoks, mida saab teha tavalise voona töötava `foreach`-ga, on `RecordQuery` soodsam valik.

`RecordQuery` on muutumatu. Iga muutmismeetod tagastab kloonitud päringu:

```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()` ja `time_range_ms()` kasutavad järjestuseks UUID, seega ei vaja need kirjeandmetes ajatemplivälja. `SegmentedLog` puhul väldivad need ka tarbetut tööd: segmente, mille ID-vahemik jääb aknast välja, ei avatagi ning segmendipõhised hõredad indeksid liiguvad esimese sobiva kirje lähedale, selle asemel et alustada algusest skannimist.

`where_equal()` võrdleb andmete ülataseme välja väärtusega `===` ning aktsepteerib skalaarväärtusi või `null`. Filter `null` leiab kirjed, kus väli on olemas ja nullväärtusega; kirjed, milles väli puudub, ei sobi.

## Kursoriga lehekülgjaotus

ID-d järjestatakse loomise aja järgi, seega on ühe lehe viimane ID järgmise lehe kursor:

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

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

## Rikutud kirjete vahelejätmine

Vaikimisi peatub skannimine esimese loetamatu kirje juures veaga. Kasuta `continue_on_error()`, kui skannimine peaks selle vahele jätma ja veast teada andma:

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

Asukohaks on kirje ID `DocStore` ja `segment-file:byte-offset` puhul ning `SegmentedLog` puhul. Rikutud kirjete tegelikuks puhastamiseks kasuta tööriista `repair()`; vaata [CLI](https://storh.inline0.dev/et/docs/cli).