# GetAdvancedSearchFilters - Advanced Documentation

## When to Use

Call this before passing any parameter to `GetAdvancedSearchResults`, before changing any filter value, and as the schema reference when assembling an ad-hoc search. Read-only - it cannot modify the saved search.

## Overview

Returns the saved filter criteria for an advanced search as a `FilterGroupInfo` tree: each group carries a `Condition`, a `NotIn` flag, nested `Children` groups, and a `FieldList` of `SearchFieldFilter` entries.

## Shape of a Filter

Each `SearchFieldFilter` carries:

- **ParameterName** - the name used to target this filter from `ParametersJson`. Only parameterized filters have one.
- **Operator** - the comparison the filter performs.
- **Field identity** - `FieldName`, `FieldSource`, `DataType`, and `NextEntityName` for chained entity paths.
- **Value slots** - `ValueString`, `ValueNumber`, `ValueDate`, `ValueDateTime`, `ValueIDNamePair`, `ValueRole`, the `BetweenValue*` pair slots, and the `ListValue*` multi-select slots.

**Whichever value slot is populated is the live value - and your worked example.** To supply a different value, replace the populated slot and leave everything else exactly as it arrived. `Operator` confirms the choice: between operators use the `BetweenValue*` slots, list operators use `ListValue*`, simple comparisons use the single `Value*` slots. Do not pick a slot from `DataType` alone.

## Three Uses

1. **Building `ParametersJson`** for `GetAdvancedSearchResults`. That payload is a flat `SearchFieldFilter[]`, not this tree - copy the filter you found by `ParameterName`, replace its populated value slot, and pass the flat array.
2. **Changing a value that is not parameterized** - a date range, a staff ID, a value range the search's author never exposed. Change the value in place in this tree and execute the modified definition with `ExecuteAdvancedSearch`. The saved search is untouched.
3. **Schema reference for ad-hoc searches.** Real filters from real searches are the worked examples of valid field chains and value shapes. See `ExecuteAdvancedSearch` documentation for the full workflow.