# Multi-Variable Search

The Multi-Variable Search allows advanced searches using multiple conditions across different metadata fields.  Instead of running one search at a time and comparing results manually, all conditions are defined on one page and the search engine evaluates them together, narrowing the results progressively.

The Multi-Variable Search is opened from the **Advanced** menu in the navigation bar, or by typing `search` or `multi` into the **Name/Description** field in the [Command Palette](command-palette.md).

## Building a Search

### 1. Choose a Target

The **Documents** or **Files** radio buttons at the top determine the search target.  Switching the target clears all conditions because the available fields differ between documents and files.

### 2. Select a Form (Optional)

The **Form** dropdown selects which form governs the search.  The form determines which columns appear in the results.  When left blank the database uses its default form.

### 3. Select a Filter Group (Optional)

The **Filter Group** dropdown selects a filter group to apply to the search.  When a filter group is selected the search uses the filtered route family.  When left blank the unfiltered family is used if the user's roles permit.  Some conditions are only available to privileged users because only an unfiltered route exists for them.

### 4. Add Conditions

Each condition row contains a **Field** dropdown, an **Operator** dropdown and a **Value** input.

- Selecting a field updates the available operators to match the field type.
- Selecting an operator renders the value input in the appropriate format (text, number, date, dropdown, or a pair of inputs for range operators).
- Entering or selecting a value completes the condition, indicated by a green check.

The **has any value** operator requires no value input and matches any record that has data in the selected field.  It is available only to privileged users.

### 5. Use NOT to Exclude

The **NOT** checkbox on a condition excludes matching records rather than including them.  At least one condition in every group must remain positive (not negated), so the checkbox is disabled when checking it would leave no positive conditions in the group.

### 6. Organise into Groups

The **Add condition** button adds another condition within the current group.  The **Add group** button creates a new group with its own set of conditions.

The **Groups** dropdown determines how groups relate:

- **Match ANY group** — a record is included if it matches any one group.  Within each group all conditions must match (AND logic).  Groups are connected by **OR**.
- **Match ALL groups** — a record is included only if it matches every group.  Within each group any condition can match (OR logic).  Groups are connected by **AND**.

With a single group the mode has no effect.

### 7. Run the Search

Clicking **Search** or pressing **Ctrl+Enter** starts the evaluation.  The progress indicator shows each condition being evaluated: *"Evaluating condition 2 of 4 (156 results so far)…"*.  If a group produces zero results the remaining conditions in that group are skipped.

Results appear in a standard Elyse table with all the usual features: sorting, column resizing, context menus, row selection and export.

## Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| **Ctrl+Enter** | Run the search (works from any control) |
| **Enter** | Run the search (when focus is on a dropdown or button) |
| **Escape** | Clear all conditions and results |
| **Alt+A** | Add a condition to the last group |
| **Alt+G** | Add a new group |
| **Tab** | Move to the next control |

## Notes

- The search evaluates the most selective conditions first.  Equality on a lookup field (e.g. *Radio Button is X*) is called before a text search (e.g. *Title contains Y*), which minimises the number of records the later conditions need to process.
- The form can be changed at any time, even after adding conditions.  The field lists are not narrowed by the form — the form only affects which columns appear in the results.
- Lookup dropdowns (Radio Button, Multi-Select, Tag, etc.) are cached after first load, so switching between conditions that use the same list is fast.
- If the Field dropdown is empty, the browser console should be checked.  The most common cause is that `search-predicates.csv` failed validation or the field list routes returned no rows.
- If a condition fails, a dialog shows the outcome of every call made during the search.  Closing the dialog returns to the builder with the expression intact so the failing condition can be modified or removed.
