Skip to content

docs: complete the searchControls parameter table #21

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chuckmeyer merged 1 commit into from
Aug 27, 2026
Merged

docs: complete the searchControls parameter table #21

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 26 additions & 11 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -209,17 +209,32 @@ and the instructions file in a single pass — missing vars are reported togethe
}
```

`searchControls` constrains what the LLM can do at query time. It is applied to every index (primary + replicas). Supported fields:

| Field | What it does |
|---|---|
| `hitsPerPage` | Limit result count. Set `constraint.max` to cap it. |
| `page` | Limit pagination depth. Set `constraint.max` to cap it. |
| `attributesToRetrieve` | Restrict which attributes are returned in each hit. Useful for limiting the LLM payload to only the fields it needs. |
| `facets` | Control which facet attributes are returned in the response. |
| `responseFields` | Restrict which top-level response fields are returned. |

Set `exposed: true` to let the LLM vary the value within the constraint; `exposed: false` to fix it.
`searchControls` constrains what the LLM can do at query time. In this friendly format
one block is applied to **every** index (primary + replicas); the service itself stores
them per index, so a native config from `snapshot` can differ index by index.

Set `exposed: true` to let the LLM vary the value within its constraint; `exposed: false`
to fix it.
Comment on lines +216 to +217

The parameters do **not** share one shape — `constraint` appears only on the numeric
ones, `merge` only on the list-valued ones:
Comment on lines +219 to +220

| Parameter | Sub-fields | What it does |
|---|---|---|
| `hitsPerPage` | `exposed`, `default`, `constraint: {min, max}` | Limit result count. Set `constraint.max` to cap it. |
| `page` | `exposed`, `default`, `constraint: {min, max}` | Limit pagination depth. |
| `attributesToRetrieve` | `exposed`, `default: []`, `constraint`, `merge` | Restrict which attributes each hit returns — useful for trimming the LLM payload. |
| `responseFields` | `exposed`, `default: []`, `constraint`, `merge` | Restrict which top-level response fields are returned. |
| `distinct` | `exposed`, `default` (boolean) | De-duplicate results. No `constraint`. |
| `facets` | `exposed`, `default: []` | Control which facet attributes the response returns. No `constraint`. |
| `query` | — | Present in the API's representation but not observed carrying a value. |
| `custom` | — | Present in the API's representation but not observed carrying a value. |

This table was derived by inspecting live agents rather than from a published schema, so
treat `query`, `custom` and the semantics of `merge` as unconfirmed. The service returns
all eight keys with `null` for anything unset, and it expands the ones you do send with
its own defaults — which is why `--dry-run` compares only the keys your config actually
specifies.

```bash
algolia-agent create \
Expand Down
Loading