> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veloiq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Global Search in Your VeloIQ App

> Wire up VeloIQ's header search bar to query your application data by registering models and fields with the veloiq search commands.

VeloIQ's header search bar can search across your application's data as well as its navigation pages. Page navigation is wired automatically. To search your model data, you register which models and fields should be queried. The framework stores that configuration in `config/search.json`, serves it from `GET /config/search`, and the frontend reads it on startup to know which endpoints to query when a user types in the search bar.

## How it works

1. You run `veloiq search add-model` to register a model and the fields to match against.
2. The CLI writes (or updates) `config/search.json` in your backend directory.
3. The backend serves the configuration at `GET /config/search`.
4. On startup the frontend reads that endpoint and queries the registered model endpoints whenever a user types in the header search input.

## Register models and fields

<Steps>
  <Step title="Register each model and the fields to search">
    Run `veloiq search add-model` once per model, passing the model class name and a comma-separated list of field names:

    ```bash theme={null}
    veloiq search add-model TeamMember --fields name,email
    veloiq search add-model Project    --fields name,description
    veloiq search add-model Task       --fields title,description
    ```
  </Step>

  <Step title="Verify config/search.json">
    The commands above produce the following file:

    ```json theme={null}
    {
      "models": ["TeamMember", "Project", "Task"],
      "fields": ["name", "email", "description", "title"]
    }
    ```

    The `fields` array is the union of all fields across every registered model. Field matching is per-model at query time — see [Field matching rules](#field-matching-rules) below.
  </Step>

  <Step title="Restart the backend">
    Restart the backend process (or let uvicorn hot-reload) so the updated `config/search.json` is served from `GET /config/search`.
  </Step>

  <Step title="Use the search bar">
    Type in the header search bar. The frontend queries each registered model's list endpoint and returns matching records alongside any matching navigation pages.
  </Step>
</Steps>

## Field matching rules

For each model, only fields whose key **exactly matches** one of the listed field names, or **ends with `_<name>`**, are searched. For example, registering `title` as a field matches both `title` and `task_title` on a model that has that column.

## Manage the search configuration

Use these commands to inspect or update the configuration after the initial setup:

```bash theme={null}
veloiq search list                    # show current models and fields
veloiq search add-field role          # add a field to the existing config
veloiq search remove-model Project    # stop searching a model
```

<Note>
  `veloiq search add-field` adds the field to the global list. If only specific models have that field, those are the only ones where it will match — fields that do not exist on a model are silently skipped at query time.
</Note>