In This Article

Migrate from SDK Query Builders to Wix API Query Language

The Wix JavaScript SDK is transitioning from query builder methods to query methods that use the Wix API Query Language. This change provides a more consistent and powerful querying experience across all Wix APIs.

What's changed

Previously, SDK query methods used a builder pattern where you chained methods to build your query. For example, methods like queryBookings(), querySessions(), and queryResourceCatalog() returned query builder objects with methods like .eq(), .hasSome(), .limit(), and .find().

The new approach uses the Wix API Query Language, where you pass a query object directly to the query method. This provides more flexibility and consistency across different Wix APIs.

Backward compatibility

The existing query builder methods continue to work. However, we strongly recommend migrating to the new query methods that use Wix API Query Language as this is our path forward for SDK development.

Updating your code now ensures long-term compatibility and gives you access to the latest features and improvements.

Code comparison

Here's how the same query looks with both approaches:

New query method with Wix API Query Language

Copy

Old query method with query builders

Copy

How to migrate your code

Follow these steps to update your query methods:

Step 1 | Identify query methods with the query builder

Look for code patterns that include:

A method called query<Something>() followed by chained methods.
Methods like .eq(), .hasSome(), .limit(), .skip(), .ascending(), or .descending().
A final .find() call.

Step 2 | Convert the query structure

Map your query builder chain into a query object. Below are some common mapping examples:

Filters:

Old	New
`.eq('field', 'value')`	`filter: { field: 'value' }` or `filter: { field: { $eq: 'value' } }`
`.hasSome('field', ['val1', 'val2'])`	`filter: { field: { $in: ['val1', 'val2'] } }`
`.ge('field', 'value')`	`filter: { field: { $gte: 'value' } }`
`.lt('field', 'value')`	`filter: { field: { $lt: 'value' } }`

Sorting:

Old	New
`.ascending('field')`	`sort: [{ fieldName: 'field', order: 'ASC' }]`
`.descending('field')`	`sort: [{ fieldName: 'field', order: 'DESC' }]`

Paging:

Old	New
`.limit(50)`	`paging: { limit: 50 }` or `cursorPaging: { limit: 50 }`
`.skip(20)`	`paging: { offset: 20, limit: X }`
`.skipTo(cursor)`	`cursorPaging: { cursor: "..." }`

Note: The new query methods can support either cursor-based or offset-based paging. For offset-based paging, if you specify offset, you must also include limit. For cursor paging, the cursor value is a string token returned from previous query return values. Learn more about paging.

Did this help?