> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: About Search Builder Utilities

## Article: About Search Builder Utilities

## Article Link: https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-builder-utilities.md

## Article Content:

# About Search Builder Utilities

The Wix JavaScript SDK provides search builder utility methods that let you construct search requests using a chainable syntax. You can pass the resulting search object directly to any SDK search method.

## Why use search builder utilities

SDK search methods accept a search request object that specifies a full-text expression, filter conditions, sort order, and paging. While you can write these objects directly, building them can be difficult, especially when conditions depend on runtime logic.

Search builder utilities offer the following benefits:

- **Chainable syntax.** Construct search requests by chaining method calls such as `.withSearchClause()` and `.withFilter()`, rather than writing JSON objects by hand.
- **Programmatic composition.** Build search expressions, filter, and sort dynamically based on runtime logic, then combine them into a single request.
- **Type safety.** The utility methods are fully typed, providing autocompletion and compile-time checks in TypeScript projects.

## Available utilities

Each SDK API exports the following utilities alongside its search methods:

| Utility | Purpose |
|---------|---------|
| `SearchParams(expression)` | Creates a search clause for a full-text expression. Supports `.fuzzy()` for approximate matching, `.mode()` to control whether all or any terms must match, and `.fields()` to restrict the search to specific fields. |
| `SearchBuilder()` | Combines a search clause, filters, sorts, and paging into a complete search request object. Supports `.withSearchClause()`, `.withFilter()`, `.withSorting()`, `.withPaging()`, and `.build()`. |
| `Filter(fieldName)` | Creates a filter condition for a specified field. Supports operators like `.eq()`, `.ne()`, `.gt()`, `.gte()`, `.lt()`, `.lte()`, `.in()`, `.nin()`, `.exists()`, `.startsWith()`, `.isEmpty()`, `.hasAll()`, and `.hasSome()`. Same utility used with `QueryBuilder`. |
| `Sort(fieldName)` | Creates a sort condition for a specified field. Supports `.asc()` for ascending and `.desc()` for descending order. Same utility used with `QueryBuilder`. |

## Code examples

The following examples search for products matching `"running shoes"`, filter to active items, and sort by price.

### With search builder utilities

```javascript
import { productsV3 } from '@wix/stores';

const { SearchBuilder, SearchParams, Filter, Sort } = productsV3.utils.search;

const request = SearchBuilder()
  .withSearchClause(SearchParams('running shoes')).fuzzy(true)
  .withFilter(Filter('inventory.availabilityStatus').eq('IN_STOCK'))
  .withSorting(Sort('updatedDate').asc())
  .withPaging({ limit: 10, offset: 0 })
  .build();

const response = await productsV3.searchProducts(request);
```

### With a direct search request object

```javascript
import { productsV3 } from '@wix/stores';

const response = await productsV3.searchProducts({
  search: {
    expression: 'running shoes'
  },
  filter: {
    'inventory.availabilityStatus': {
      $eq: 'IN_STOCK'
    }
  },
  sort: [
    {
      fieldName: 'updatedDate',
      order: 'ASC'
    }
  ],
  paging: {
      limit: 10,
      offset: 0
  }  
});
```

## Building dynamic searches

Search builder utilities are particularly useful when you need to construct search requests based on conditions that aren't known until runtime. Instead of manually assembling a JSON object, you can compose search parameters programmatically.

For example, the following helper method builds a search request where the filter, sort, and fuzzy matching are optional and determined by the caller:

```javascript
import { productsV3 } from '@wix/stores';

const { SearchBuilder, SearchParams, Filter, Sort } = productsV3.utils.search;

function buildSearchRequest(query, options) {
  let builder = SearchBuilder().withSearchClause(
    SearchParams(query).fuzzy(options.fuzzy ?? false)
  );

  if (options.status) {
    builder = builder.withFilter(Filter('inventory.availabilityStatus').eq(options.status));
  }

  if (options.sortField) {
    const direction = options.sortDirection === 'DESC'
      ? Sort(options.sortField).desc()
      : Sort(options.sortField).asc();
    builder = builder.withSorting(direction);
  }

  return builder.withPaging({ limit: options.limit ?? 10 }).build();
}

const request = buildSearchRequest('running shoes', {
  fuzzy: true,
  status: 'IN_STOCK',
  sortField: 'updatedDate',
  sortDirection: 'ASC',
  limit: 20
});

const response = await productsV3.searchProducts(request);
```

## See also

- [About Search, Query, and List Methods](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-search-query-and-list-methods.md)
- [About Query Builder Utilities](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-query-builder-utilities.md)
- [About the Wix API Query Language](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language.md)
- [About Sorting and Paging](https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging.md)