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

# Advanced Search

> Replace Filament's default search with powerful constraints, column selection, multi-group AND/OR queries, and keyboard shortcuts.

![Advanced Search](https://advancedtables.com/images/advanced-search.png)

Advanced Search replaces Filament's default table search with a powerful query builder. Your users can search using eight different constraints like "equals", "starts with", "ends with", and more. They can select which columns to search, build multi-group queries with AND/OR logic, and use keyboard syntax shortcuts to quickly change the search behavior directly from the search input. Selected options appear as interactive badges in the search field for easy management. Advanced Search is fully integrated with [Preset Views](/v5/features/preset-views), [User Views](/v5/features/user-views), and [Quick Filters](/v5/features/quick-filters).

## Enabling Advanced Search

Advanced Search is disabled by default. To enable, add `advancedSearchEnabled()` to your panel provider:

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
```

> Note: Advanced Search is automatically disabled on tables that use Filament's `->searchUsing()` callback.

After enabling, be sure to run `npm run build` and `php artisan filament:upgrade`.

Advanced Search options can also be configured in the `advanced_search` section of `config/advanced-tables.php`.

## Using Advanced Search

Once enabled, the search field includes an interactive dropdown for building search queries. Clicking the search input or pressing the down arrow key opens the dropdown, which is organized into the following sections:

* **Constraints** — Select a search constraint (e.g., Contains, Equals, Starts with)
* **Columns** — Select which columns to search (when [column selection](#column-selection) is enabled)
* **Database** — Select extra searchable columns from related models (when column selection is enabled)
* **Boolean** — Add AND/OR operators to create [search groups](#grouping) (when [grouping](#grouping) is enabled)

Selected options appear as **badges** in the search input:

* **Constraint badges** (gray) — Show the active search constraint
* **Column badges** (blue) — Show which columns are being searched
* **Operator badges** (yellow) — Show the AND/OR operator connecting search groups

An information icon displays a search reference with all available keyboard shortcuts and syntax options. The clear button (X icon) removes all search groups and resets the search.

### Keyboard navigation

| Key     | Action                                   |
| ------- | ---------------------------------------- |
| `↓`     | Open dropdown                            |
| `↑` `↓` | Navigate dropdown items                  |
| `↵`     | Select highlighted item or submit search |
| `⌫`     | Remove last badge from active group      |

## Search Constraints

Advanced Search includes eight search constraints. Users can select a constraint from the dropdown or type a syntax prefix directly in the search input:

| Constraint          | Syntax   | Description                                                 | SQL Operator       |
| ------------------- | -------- | ----------------------------------------------------------- | ------------------ |
| Contains            | *(none)* | Matches records containing the search term anywhere         | `LIKE %value%`     |
| Does not contain    | `-`      | Excludes records containing the search term                 | `NOT LIKE %value%` |
| Equals              | `=`      | Matches records where the value is exactly the search term  | `= value`          |
| Does not equal      | `-=`     | Excludes records where the value is exactly the search term | `!= value`         |
| Starts with         | `^`      | Matches records starting with the search term               | `LIKE value%`      |
| Does not start with | `-^`     | Excludes records starting with the search term              | `NOT LIKE value%`  |
| Ends with           | `$`      | Matches records ending with the search term                 | `LIKE %value`      |
| Does not end with   | `-$`     | Excludes records ending with the search term                | `NOT LIKE %value`  |

For example, typing `=order` will search for records that exactly equal "order", while typing `-^test` will exclude records that start with "test".

> Tip: The search reference (info icon) in the dropdown displays all available syntax shortcuts for quick reference.

## Word Splitting

By default, multi-word search terms are automatically split into individual words. Each word must match for a record to be included in the results. For example, searching for `John Doe` with the Contains constraint will only match records that contain both "John" and "Doe". This applies to all constraints except Equals and Does not equal.

The Equals and Does not equal constraints do **not** split words — the entire search term is treated as a single value for exact comparison.

To search for an exact multi-word phrase without splitting, wrap the search term in quotes. For example, `"John Doe"` will match the exact phrase "John Doe" rather than matching "John" and "Doe" separately.

## Column Selection

By default, Advanced Search searches all globally searchable columns. You can enable column selection to let users choose which specific columns to search:

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
    ->advancedSearchColumnsEnabled()
```

When enabled, the dropdown displays two column sections:

* **Columns** — Table columns that are visible and globally searchable
* **Database** — Extra searchable columns from related models (configured via `$table->getExtraSearchableColumns()`)

Selected columns appear as blue badges in the search input. Each [search group](#grouping) can target different columns. When no columns are selected, all searchable columns are searched.

## Grouping

Grouping allows users to build complex multi-group search queries with AND/OR logic. To enable:

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
    ->advancedSearchGroupingEnabled()
```

When enabled, the dropdown includes a **Boolean** section with AND and OR operators. Selecting an operator creates a new search group. The first group has no operator; subsequent groups are prefixed with an AND or OR badge.

Users can click an operator badge to toggle between AND and OR.

### How groups combine

Groups connected by **AND** narrow results — all conditions must match. Groups connected by **OR** broaden results — any condition can match.

Under the hood, groups connected by AND stay in the same `WHERE` clause, while groups connected by OR create separate `WHERE` clauses joined with `orWhere()`. For example:

```
(name contains "John" AND email contains "gmail") OR (status equals "active")
```

Translates to:

```sql theme={null}
WHERE (name LIKE '%John%' AND email LIKE '%gmail%') OR (status = 'active')
```

### Maximum groups

You can limit the maximum number of search groups (default is 5):

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
    ->advancedSearchGroupingEnabled()
    ->advancedSearchMaxGroups(3)
```

### Boolean Syntax

In addition to using the dropdown, users can type `&` for AND or `|` for OR directly in the search input to create new groups. This feature is disabled by default:

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
    ->advancedSearchGroupingEnabled()
    ->advancedSearchBooleanSyntaxEnabled()
```

> Note: Boolean syntax is disabled by default because `&` and `|` symbols may appear in legitimate search terms. Only enable this after educating your users about the syntax. If a user needs to search for a term containing `&` or `|`, they can wrap the search term in quotes to prevent it from being interpreted as a boolean operator. Advanced Search is smart enough to not interpret these symbols as operators while the user is actively typing — they are only parsed when the search is submitted.

## Using with Preset Views

You can apply default search settings to your [Preset Views](/v5/features/preset-views) using the `defaultSearch()` method. Each search group is an array with `columns`, `constraint`, `value`, and `operator` keys:

```php theme={null}
'active_orders' => PresetView::make('Active Orders')
    ->defaultSearch([
        [
            'columns' => [],
            'constraint' => 'contains',
            'value' => 'pending',
            'operator' => null,
        ],
    ])
```

You may create multi-group searches with AND/OR operators:

```php theme={null}
'active_orders' => PresetView::make('Active Orders')
    ->defaultSearch([
        [
            'columns' => ['status'],
            'constraint' => 'equals',
            'value' => 'active',
            'operator' => null,
        ],
        [
            'columns' => ['name'],
            'constraint' => 'contains',
            'value' => 'John',
            'operator' => 'or',
        ],
    ])
```

The `defaultSearch()` method accepts the following parameter:

| Parameter | Type                         | Description                                                                            |
| --------- | ---------------------------- | -------------------------------------------------------------------------------------- |
| `$search` | `string \| array \| Closure` | A string for a simple search term, or an array of search group arrays for full control |

> Tip: You can also pass a simple string like `->defaultSearch('pending')` which will be used as a search term with the "contains" constraint. See [Applying a default search](/v5/features/preset-views#applying-a-default-search) in the Preset Views documentation for more on the string format.

Each search group array has the following keys:

| Key          | Type             | Description                                                             |
| ------------ | ---------------- | ----------------------------------------------------------------------- |
| `columns`    | `string[]`       | Column names to search. Empty array searches all columns.               |
| `constraint` | `string`         | The search constraint (e.g., `'contains'`, `'equals'`, `'starts_with'`) |
| `value`      | `string`         | The search term                                                         |
| `operator`   | `string \| null` | `'and'`, `'or'`, or `null` for the first group                          |

## Using with User Views

Advanced Search settings are automatically saved and restored with [User Views](/v5/features/user-views). When a user saves a User View, all search groups including their constraints, selected columns, values, and operators are included. When the User View is loaded, all search settings are restored.

## Advanced Search Configurations

Advanced Tables offers multiple ways to customize Advanced Search. Unless specified otherwise, these options can be configured directly on the `AdvancedTablesPlugin` object inside your `PanelProvider`.

### Dropdown column order

By default, constraints are shown first in the dropdown. To show columns first instead:

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
    ->advancedSearchDropdownColumnsFirst()
```

### Opening dropdown on focus

By default, the dropdown opens when the user presses the down arrow key. To open the dropdown automatically when the search input receives focus:

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
    ->advancedSearchDropdownOpenOnFocus()
```

### Keybindings

You can configure keyboard shortcuts to focus the search input:

```php theme={null}
AdvancedTablesPlugin::make()
    ->advancedSearchEnabled()
    ->advancedSearchKeybindings(['command+k', 'ctrl+k'])
```

### Customizing the trigger action

You can customize the Advanced Search trigger button using `advancedSearchTriggerAction()`, following the same pattern as Filament's [trigger action customization](https://filamentphp.com/docs/5.x/tables/filters/overview#customizing-the-filters-trigger-action):

```php theme={null}
use Filament\Actions\Action;

AdvancedTablesPlugin::make()
    ->advancedSearchTriggerAction(function (Action $action) {
        return $action
            ->icon('heroicon-s-magnifying-glass')
            ->tooltip('Search options')
            ->color('primary');
    })
```

### Customizing labels

You may customize Advanced Search labels in the language file. Publish the language files and update the `advanced_search` section in the `advanced-tables.php` language file.