Coding Examples

Sled Tests

Go Headless

Develop Websites (SDK)

Build Apps

Client (Deprecated)

API Preview

Wix CLI

Ricos

Develop Websites

API Reference

Velo

Picasso

GraphQL (Alpha)

# About Query Builder Utilities

The Wix JavaScript SDK provides query builder utility methods that let you construct filter, sort, and paging objects using a chainable syntax. You can pass the resulting query object directly to any SDK query method.

Each SDK package that supports querying exports the following utilities: `QueryBuilder`, `Filter`, and `Sort`.

## Why use query builder utilities

SDK query methods accept queries written in the [Wix API Query Language](fallback::https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language), a JSON-based format for filtering, sorting, and paging. While this format is flexible and consistent across all Wix APIs, building these objects can be difficult, especially for complex queries.

Query builder utilities offer the following benefits:

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

## Available utilities

Each SDK package exports the following utilities alongside its query methods:

| Utility | Purpose |
|---------|---------|
| `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()`. |
| `Sort(fieldName)` | Creates a sort condition for a specified field. Supports `.asc()` for ascending and `.desc()` for descending order. |
| `QueryBuilder()` | Combines filters and sorts into a complete query object. Supports `.withFilter()`, `.withSorting()`, and `.build()`. |

## Code examples

The following examples query Bookings services for all services of type `"COURSE"`, sorted by `name` in ascending order.

### With query builder utilities

```javascript
import { services } from '@wix/bookings';

const { Filter, QueryBuilder, Sort } = services;

const query = QueryBuilder()
  .withFilter(Filter('type').eq('COURSE'))
  .withSorting(Sort('name').asc())
  .build();

const response = await services.queryServices(query);
```

### With a direct query object

```javascript
import { services } from '@wix/bookings';

const response = await services.queryServices({
  filter: {
    type: {
      $eq: 'COURSE'
    }
  },
  sort: [
    {
      fieldName: 'name',
      order: 'ASC'
    }
  ]
});
```

## Building dynamic queries

Query builder utilities are particularly useful when you need to construct queries based on conditions that aren't known until runtime. Instead of manually assembling a JSON filter object, you can compose filters and sorts programmatically.

For example, the following helper method builds a query for Bookings services where the filter and sort are optional and determined by the caller:

```javascript
import { services } from '@wix/bookings';

const { Filter, QueryBuilder, Sort } = services;

function buildServiceQuery(options) {
  let builder = QueryBuilder();

  if (options.type) {
    builder = builder.withFilter(Filter('type').eq(options.type));
  }

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

  return builder.build();
}

const query = buildServiceQuery({ type: 'COURSE', sortField: 'name', sortDirection: 'ASC' });
const response = await services.queryServices(query);
```

## See also

- [About the Wix API Query Language](fallback::https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-the-wix-api-query-language)
- [About Sorting and Paging](fallback::https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/about-sorting-and-paging)
- [Migrate from SDK Query Builders to Wix API Query Language](fallback::https://dev.wix.com/docs/api-reference/articles/work-with-wix-apis/data-retrieval/migrate-from-sdk-query-builders-to-wix-api-query-language)

Utility	Purpose
`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()`.
`Sort(fieldName)`	Creates a sort condition for a specified field. Supports `.asc()` for ascending and `.desc()` for descending order.
`QueryBuilder()`	Combines filters and sorts into a complete query object. Supports `.withFilter()`, `.withSorting()`, and `.build()`.