# Your own search client

> Keep the access filter when you query the search engine with your own client, or feed your own index with Access::indexKeysOf() and Access::indexReaderKeys().

## Four ways

An application that queries the engine with its own client keeps the access filter in one of four ways:

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

<tbody>
  <tr>
    <td>
      A multi-search, a vector search or an option that Scout does not expose, on the index of a <code>
        ControlledSearchable
      </code>
      
       model
    </td>
    
    <td>
      A search callback: <code>
        Post::search('budget', fn ($client, $query, $options) => ...)->controlled()
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      A search that your server proxies for a front end
    </td>
    
    <td>
      <a href="/search/from-the-browser#through-a-route-of-the-application">
        <code>
          Access::guardSearch()
        </code>
      </a>
      
       in your route
    </td>
  </tr>
  
  <tr>
    <td>
      One index per model, written by your own client
    </td>
    
    <td>
      A Scout engine of your application: a subclass of Scout's Algolia, Meilisearch, Typesense or Turbopuffer engine, or an engine passed to <a href="/search/engines#trusting-another-engine">
        <code>
          Access::trustSearchEngine()
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      An index that is not the index of one Scout model
    </td>
    
    <td>
      <a href="#an-index-of-your-own">
        <code>
          Access::indexKeysOf()
        </code>
        
         and <code>
          Access::indexReaderKeys()
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

- The options that a search callback receives hold the access filter of the reader for the index of this model: pass them on to your client, never rebuild them, and never apply them to another index, where keys of the same name may have another meaning. In a multi-search, each model takes the filter of its own search.
- Never combine a filter of the package with yours by hand: `filter()` on a [browser token](/search/from-the-browser) is for logs and tests.
- With your own Scout engine, the documents, their freshness, `access:check` and `assertSearchAgrees()` follow as for any engine.

## An index of your own

An index that is not the index of one Scout model, such as a collection shared by several models, chunks of documents for a semantic search or an ingestion pipeline, takes its values from two read-only methods:

- `Access::indexKeysOf($rows)` gives the values to store on the documents of each row;
- `Access::indexReaderKeys($reader, $model)` gives the values that the search of a reader filters on.

A common use keeps the list in SQL with `controlledFor()` and asks the engine only for the rows that their content finds, filtered by the keys of the reader so that the documents the reader may not view do not take the top results:

```php
use Lomkit\Access\Access;

// Indexing: the rows of one model at a time
$posts = Post::query()->whereKey($ids)->get();

foreach (Access::indexKeysOf($posts) as $id => $keys) {
    foreach ($chunks[$id] as $chunk) {
        $index->upsert([...$chunk, '_access' => $keys['_access'], '_boundary' => $keys['_boundary']]);
    }
}

// Searching
$keys = Access::indexReaderKeys($request->user(), Post::class);

if ($keys->isClosed()) {
    return [];
}

$hits = $index->search($query, filters: [
    ['_access', 'in', $keys->values()['_access']],
    ['_boundary', 'in', $keys->values()['_boundary']],
]);
```

`$index` stands for the client of your engine. Declare `_access` and `_boundary` as arrays of strings that the engine filters on, compared as whole values.

### `indexKeysOf()`

- It takes the saved rows of one model, as a collection or any iterable, and returns, by the key of each row, `['_access' => [...], '_boundary' => [...]]`. A string key written as a decimal integer, such as `"123"`, comes back as the int `123`, as in any PHP array.
- It loads the `load` relations of the keys once for all the rows, and never loads lazily.
- It throws `InvalidIndexRowException` for rows of two models, a value that is not a model, an unsaved, deleted or soft-deleted row, and a key that is not an int or a string.

### `indexReaderKeys()`

- It returns a `Lomkit\Access\Search\IndexReaderKeys`, with `model()`, `isClosed()` and `values()`, the values of `_access` and `_boundary` as two lists of strings.
- The keys of the reader are the ones `controlledFor()` lists the rows with: for `view`, in the current [decision context](/essentials/readers#the-decision-context). It takes no ability: one given after the model throws `UnsearchableAbilityException`.
- A reader that `controlled()` would show an empty page (no reader, no perimeter that allows them, no key, or a `null` boundary value) is **closed**: `isClosed()` is `true`, and each field holds one value that no document carries, so a filter that ignores `isClosed()` still finds nothing. Skip the engine when it is `true`.

### Matching

A document matches a reader when it shares at least one value with the reader in `_access` **and** at least one in `_boundary`.

- Every open reader has values in both fields, and every document in `_access`, so a filter on both fields is always right: an unrestricted reader holds the value that every document of the model carries, and a model without a boundary gives the same `_boundary` value to its documents and its readers.
- The `_boundary` of a document is empty when its row has no boundary value: no reader finds it.
- The values are digests of 32 lowercase hexadecimal characters. The morph class of the model is part of each digest, so one collection holds several models without a field of its own: the values of one model never match another model's. A model whose morph class names another model, as a child model of single table inheritance does, throws `SharedMorphClassException`: give it a morph class of its own.
- The values never match the documents of a `ControlledSearchable` model, even of the same model: never store or filter one kind with the other.
- A change of the morph alias, or the rename of a class without one, changes every value: write the documents again.

### Requirements

The model needs a control, not `ControlledSearchable`. Both methods throw:

- `MissingControlException` without a control;
- `UnsearchableBoundaryException` when the boundary class has no `searchKeys()`;
- `PerimeterWithoutSearchKeysException` when a perimeter that is neither unrestricted nor a `ThroughParent` declares no search keys, in the control or in the control of a parent, since the rows it grants would be missing from the index;
- `UnsearchableThroughParentException` for a `ThroughParent` that delegates `view` to another ability of the parent, or whose parent has a boundary without a search form. The relation needs no `inverse` on a model that is not `ControlledSearchable`.

`access:check` does not check a model indexed only by your own pipeline: call both methods in a test, as [`assertIndexKeysAgree()`](/testing-and-tooling/testing#an-index-of-your-own) does.

### Freshness

The package reindexes nothing outside Scout. A document keeps the values it was written with, and a stale value can show a row to a reader who lost access until the document is written again. Compute the values again and rewrite the documents when what the keys read changes:

- the columns that the `row` callbacks and the boundary read, and the models they load through `load`;
- the models that a `reindexWhen()` watches, the parent of a `ThroughParent` and what changes its keys, and the pivots that a key reads;
- the rules themselves, after a deployment, and the writes that Eloquent does not see.

Delete the documents of a row when it is deleted or soft deleted, and write them again when it is restored; a parent deleted or restored changes the keys of its children. [Keeping the keys fresh](/search/keeping-the-keys-fresh) lists what the package does for a Scout model in each case: your pipeline does the same for its index. The reader side needs nothing, since `indexReaderKeys()` computes the keys at each call.
