# Batched decisions

> Decide the rows of a page in one query with withAbilities(), preload decisions with Access::preload(), or get the keys a reader may act on with reachableKeys().

A page that checks `@can('update', $post)` on each row runs one query per row and ability for the perimeters checked in SQL. Three tools decide many rows at once, and keep the answers for the request, so that `can()`, `@can`, `authorize()` and `Gate::inspect()` then answer without SQL.

<table>
<thead>
  <tr>
    <th>
      You have
    </th>
    
    <th>
      Use
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      A query that loads the page
    </td>
    
    <td>
      <code>
        withAbilities()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Rows already loaded
    </td>
    
    <td>
      <code>
        Access::preload()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Rows already loaded, and you need the keys
    </td>
    
    <td>
      <code>
        reachableKeys()
      </code>
    </td>
  </tr>
</tbody>
</table>

## `withAbilities()`

```php
$posts = Post::controlled()
    ->withAbilities(['view', 'update', 'delete'])
    ->paginate();
```

For each ability, the query selects one `CASE` that returns the verdict of the row: the boundary when it has no in-memory form, then the perimeters checked in SQL. The answers are kept under the reader chosen by `controlledFor()`, or the signed-in user for `controlled()`, and under the current decision context.

- It works with `get()`, `first()`, `paginate()`, `simplePaginate()`, `cursorPaginate()`, `chunk()`, `lazy()`, `cursor()` and the eager loads of a controlled relation:

```php
User::with(['posts' => fn ($posts) => $posts->controlled()->withAbilities(['update'])])->get();
```

- It comes after `controlled()` or `controlledFor()`, or throws `MissingControlledReaderException`.
- The abilities are names or `Ability` objects. A name goes through [`abilityFor()`](/digging-deeper/abilities#from-a-policy-method-to-an-ability), and one the control cannot map throws `InvalidAbilityException`.
- `controlled()` does not decide `view` by itself: Laravel only groups the conditions of the scope, so an `orWhere()` added after it could bring rows from outside the perimeters. List `view` when the page checks it.
- Select the columns with `select()`: the columns passed to `get()` are ignored once `withAbilities()` adds its own.
- The extra columns use reserved aliases and are removed from every model right after the query: they never show in `getAttributes()`, `toArray()` or the JSON.

To page through the rows a reader may act on, list them with `controlledFor($user, 'update')`, then decide the other abilities on the same rows:

```php
$editable = Post::controlledFor($user, 'update')
    ->withAbilities(['view', 'delete'])
    ->paginate();
```

## Preloading loaded rows

```php
use Lomkit\Access\Ability;
use Lomkit\Access\Access;

Access::preload($user, 'update', $posts);
Access::preload($user, Ability::delete(), $posts);
```

`Access::preload($reader, $ability, $rows)` runs one query per ability and per model, in chunks of 1,000 keys, and keeps the answers the same way.

- The rows can belong to several controlled models.
- Unsaved rows are skipped, since they are refused as `unsaved` without SQL.
- A reader without a key, or not saved, is never kept, so preloading for it runs no query.

The [laravel-rest-api extension](/integrations/laravel-rest-api#row-checks) preloads the row checks of each page this way.

## `reachableKeys()`

```php
use Lomkit\Access\Ability;
use Lomkit\Access\Access;

$editable = Access::controlFor(Post::class)->reachableKeys($user, Ability::update(), $posts);
```

`reachableKeys()` returns, in one query, the keys of the rows the reader may act on, in the order of `$rows`. Use it to filter rows that are already loaded, such as the results of a [search](/search/overview#searching), which always finds the rows the reader may view.

## What a batch holds

A batch holds only what the SQL decides, under the perimeters kept for the reader. The in-memory checks still run on every decision, on the row as stored: the in-memory form of the boundary, and the perimeters with a `should()` callback or an `includes()` hook. A perimeter checked in memory can grant a row that the batch answered `outside_rows`, so a batched answer is always the answer of the row-by-row decision. [`assertControlAgrees()`](/testing-and-tooling/testing#the-decisions) checks it on your test data.

With a boundary that has no in-memory form, `withAbilities(['view', ...])` or a preload of `view` also gives the `not_found` answers of the other abilities without a query.

A batch is worth its query only while nothing forgets the [kept decisions](/digging-deeper/decisions#what-forgets-them): a write for each row while the page renders, such as an access log, forgets them, and the next checks query again.
