# Kyselyt

`RecordQuery` on virtaava suodatin, jota käytetään `stream()`-toiminnon kanssa. Se kattaa lisäyspainotteiset käyttötavat: jatkamisen kohdistimen jälkeen, aikavälin lukemisen, kentän yhtäsuuruuden perusteella suodattamisen ja tulosten rajaamisen. Monipuolisempia ehtoja, järjestämistä ja indekseihin perustuvia hakuja varten käytä [kyselyrakenninta](https://storh.inline0.dev/fi/docs/query-builder). Tavalliselle virralle tehtävään `foreach`-kyselyyn `RecordQuery` on kevyempi työkalu.

`RecordQuery` on muuttumaton. Jokainen muokkaus palauttaa kloonatun kyselyn:

```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()` käyttävät järjestystä UUID, joten tietueen dataan ei tarvita aikaleimakenttää. Kohteessa `SegmentedLog` ne myös välttävät turhaa työtä: segmenttejä, joiden tunnusalue on aikavälin ulkopuolella, ei avata lainkaan, ja harvat segmenttikohtaiset indeksit hakeutuvat lähelle ensimmäistä osuvaa tietuetta sen sijaan, että lukisivat alusta alkaen.

`where_equal()` vertaa ylimmän tason datakenttää arvoon `===` ja hyväksyy skalaariarvot tai arvon `null`. Suodatin `null` löytää tietueet, joissa kenttä on olemassa ja sen arvo on null; tietueet, joista kenttä puuttuu, eivät täsmää.

## Sivutus kohdistimella

Tunnukset lajitellaan luontiajan mukaan, joten yhden sivun viimeinen tunnus toimii seuraavan sivun kohdistimena:

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

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

## Vioittuneiden tietueiden ohittaminen

Läpikäynti keskeytyy oletuksena ensimmäiseen lukukelvottomaan tietueeseen. Käytä toimintoa `continue_on_error()`, jos läpikäynnin tulee ohittaa tietue ja ilmoittaa virheestä sen sijaan:

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

Sijainti on tietuetunnus kohteille `DocStore` ja `segment-file:byte-offset`, ja `SegmentedLog`-kohteille. `repair()` on työkalu vioittuneiden tietueiden varsinaiseen puhdistamiseen; katso [CLI](https://storh.inline0.dev/fi/docs/cli).